76 KiB
format, type, entry_prefix, schema, rules
| format | type | entry_prefix | schema | rules | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2 | blockers_registry | BLK |
|
|
Blockers registry (BLK)
BLK-001 — rtk curl returns compressed schema in pipes
- Date: 2026-04-22
- Friction: pipelines like
rtk curl ... | python -c "json.load(sys.stdin)"(orjq,awk) fail without clear error. - Real cause:
rtk curlauto-compresses stdout regardless of TTY — documented in.claude/tasks/rtk-upstream-issue.md. - Solution:
- Short-term workaround:
exclude_commands=["curl"]in~/.config/rtk/config.toml. - Alternative workaround: use
rtk proxy. - Upstream fix: issue reported, see
.claude/tasks/rtk-upstream-issue.md.
- Short-term workaround:
- Status: upstream (
rtkbug, workaround applied).
BLK-002 — rmdir denied in sandbox on empty directory
- Date: 2026-04-23
- Friction: couldn't delete
./tasks/after emptying (post-migration to.claude/tasks/).rmdir tasksandrm -r tasksreturned "Permission denied" even with empty dir and non-destructive intent. - Real cause: Claude Code sandbox blocks destructive commands (
rm,rmdir,rm -rf) by default via harness permission gate, regardless of actual semantics.git rmthroughgitpassed (commitc721a36) — git treated as non-destructive tool. - Solution:
- This session:
git rm tasks/*.mdhandled files individually (viagit rm, cleared gate). Git auto-detected renames to.claude/tasks/, sotasks/directory removed implicitly at commit time. - If dir persists empty after
git rm: ask user to runrmdir tasksmanually.
- This session:
- Status: resolved (fixed via
git rm+ rename auto-detection; normdirneeded in practice).
BLK-003 — scripts/screenshot.mjs hardcoded macOS path blocks PNG cards on Linux
- Date: 2026-05-12
- Friction:
/darwin-skillPhase 3 generates result cards vianode ~/.agents/skills/darwin-skill/scripts/screenshot.mjs <html> <png>. On Linux: script fails immediately —require('/Users/alchain/.npm-global/lib/node_modules/playwright/node_modules/playwright-core')resolves to a non-existent macOS user path. No PNG cards produced; Phase 3 falls back to markdown report only. - Real cause: upstream
alchaincyf/darwin-skillauthor dev'd on macOS, shipped absolute path to their own homedir's global npm install of playwright. Zero portability layer (no PATH lookup, noplaywrightbare require, no fallback tonpx). - Solution:
- Workaround (used 2026-05-12): skip PNG generation, deliver markdown + HTML cards (HTML viewable in browser without playwright).
- Local patch:
npm i -g playwrightthen replacerequire('/Users/alchain/...')withrequire('playwright'). Two lines edit. - Spec-documented fallback:
npx playwright screenshot "file:///path/to/card.html#<theme>" out.png --viewport-size=960,1280 --wait-for-timeout=2000— works without modifying the file, costs ~150MB chromium download. - PR upstream to
github.com/alchaincyf/darwin-skillonce tested.
- Status: upstream (third-party skill at
~/.agents/skills/darwin-skill/scripts/screenshot.mjs, not in any of our repos).
BLK-004 — /ship-feature wrapper references 6 deleted agent files
- Date: 2026-05-20
- Friction:
/ship-featureinvocation loads wrapper at~/.claude/commands/ship-feature.md. Wrapper saysLoad and follow strictly: .claude/agents/{ship-feature,analyzer,designer,implementer,reviewer,tester}.md. 5 of 6 paths missing on disk (onlyanalyzer.mdsurvives). User hits blocker — wrapper without orchestrator. - Real cause: refactor commits
0241e1d("extract skill logic into standalone agent files") +21960e0("changed orchestrators into skills") migrated orchestrator from.claude/agents/ship-feature.mdinto~/.claude/skills/ship-feature/SKILL.mdand replaced custom sub-agents (designer/implementer/reviewer/tester) with superpowers skills (brainstorming, writing-plans, subagent-driven-development, requesting-code-review, finishing-a-development-branch). Wrapper at~/.claude/commands/ship-feature.mdnever updated, never deleted. Untracked file — survived all refactor commits silently. - Solution:
rm ~/.claude/commands/ship-feature.md. Skill~/.claude/skills/ship-feature/SKILL.md(name: ship-feature,disable-model-invocation: true) becomes sole/ship-featureresolver. SKILL.md references only existing agents:plugin-advisor.md,analyzer.md,doc-syncer.md. - Status: resolved.
BLK-005 — /profile set full warns missing: checkpoint after gstack upstream rename
- Date: 2026-05-21
- Friction:
/profile set full(and dev, backend, web, web-full) emits⚠ missing: checkpoint — try: bash link.sh. Runningbash link.shreports✅ All symlinks already up to date. Next: bash install-plugins.sh— dead-end loop. User cannot resolve the warning by following the suggested next step. - Real cause: gstack upstream renamed the
checkpointskill tocontext-save(Claude Code now treats/checkpointas a native rewind alias, shadowing the gstack skill). New skill inskills-external/gstack/context-save/SKILL.mdcarries the description"Formerly /checkpoint — renamed because Claude Code treats /checkpoint as a native rewind alias". Fivelib/profiles/*.profilefiles still listed the dead name.link.shonly symlinks repo dirs into~/.claude/— it cannot materialize a skill that no longer exists upstream, so its suggested action was misleading. - Solution:
s/checkpoint/context-save/inlib/profiles/{dev,backend,full,web,web-full}.profile(commit69c5ded).CLAUDE.md:193routing lineSave progress, checkpoint, resume → invoke context-saveupdated locally, left uncommitted because the file holds unrelated in-progress graphify section work. Verify:bash lib/profile.sh set fullnow outputs✓ enabled: context-savewith no warning. - Status: resolved.
BLK-006 — bash lib/profile.sh current false-negative when invoked via ~/.claude/lib/ symlink
- Date: 2026-05-21
- Friction:
bash "$HOME/.claude/lib/profile.sh" currentreturnsnone (all gstack skills enabled — no profile set)even when a profile IS applied + 14gstack__*entries sit in the repo'sskills-disabled/. User cannot detect active profile via the official command. Same script invoked from inside the repo directory (bash lib/profile.sh current) returns the correct answer — invocation-path-dependent behavior is the worst kind of bug to diagnose. - Real cause:
lib/profile.sh:43setREPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)". Default bashcdpreserves symlinks (logical pathname mode,set -Poff). When the script is invoked via the~/.claude/lib/profile.shsymlink (link.sh wires~/.claude/lib -> <repo>/lib),$BASH_SOURCE[0]is the symlinked path,dirnamereturns~/.claude/lib,cd ..lands at~/.claude, andpwdreturns the logical path/home/bchanot-ubuntu/.claude.$SKILLS_DIR="$REPO/skills"still works because~/.claude/skillshappens to be a symlink to the repo'sskills/. But$DISABLED_DIR="$REPO/skills-disabled"resolves to~/.claude/skills-disabled— a real sibling directory created at some earlier point containing only 2 stale npx-skill symlinks (darwin-skill,find-skills).cmd_currentscans this near-empty dir, finds 0gstack__*entries, returns the "none" sentinel. - Solution:
REPO="$(cd -P "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"(commita4558ee).-Pforces physical-path resolution so$REPOis always the real repo path regardless of how the script is invoked. Verify:bash "$HOME/.claude/lib/profile.sh" currentnow returnsfull (100% match, 14 gstack skills disabled). - Status: resolved. Follow-up:
~/.claude/skills-disabled/(real dir with onlydarwin-skill/find-skillssymlinks) is orphaned — these npx skills are already symlinked into<repo>/skills/by link.sh, so the disabled-side copies serve no purpose. Could be deleted to remove confusion, but harmless as-is.
BLK-007 — 6 gstack source skills (ios-*, spec) unlinked — invisible to profile system + gstack on
- Date: 2026-06-02
- Friction:
skills-external/gstack/has 53 source skills; 6 (ios-clean,ios-design-review,ios-fix,ios-qa,ios-sync,spec) exist ONLY as source — NOT symlinked intoskills/(enabled) norskills-disabled/gstack__*(parked). So invisible to Claude AND untouched byreset/gstack on(both operate on parkedgstack__*only). Surfaced while addinggstack on|off:commof gstack source vsfull.profile. - Real cause: gstack submodule bump added new skills; gstack's own
./setup(source of truth for per-skill symlinks per link.sh) not re-run → symlinks never created. Same lifecycle gap class as toggle-external-source-only-state (LRN-007). NOT afull.profilebug — full curated by design (BDR-017 caveat: "full excludes rarely-used gstack skills"). Initial "full omits ios = bug" flag was WRONG, self-corrected (see EVAL-002). - Solution applied (NOT full
./setup— surgical, no side effects): (1) Linkedspeconly —mkdir skills/spec+ln -snf <abs>/skills-external/gstack/spec/SKILL.md skills/spec/SKILL.md, matching gstack setup:440-476 (per-skill real dir + SKILL.md symlink, name from frontmatter). (2) Addedspectofull.profile+web-full.profileplanning sections (must be in active profilefullelseset fullre-disables it). (3) iOS 5 skills deliberately NOT linked — Linux host, device-farm needs Mac daemon + Tailscale + iOS devices = dead skills + token cost. (4) Completed.gitignoregstack allowlist: added all 12 missing (spec, 5ios-*, 6 parkeddocument-generate/landing-report/scrape/setup-gbrain/skillify/sync-gbrain), removed stalecheckpoint(BLK-005 rename). Reason:gstack on(BDR-018) moves parked skills intoskills/— any gstack skill missing from allowlist = untracked git noise on enable. - Verified:
profile show full+web-full→ spec enabled; allowlist drift recheck EMPTY; spec skill now visible to Claude. - Status: resolved. iOS = intentional exclusion (re-linkable via gstack
./setupon a Mac). See gstack-gitignore-allowlist-completeness (LRN-025).
BLK-008 — gstack ./setup fails on Ubuntu 26.04 — Playwright chromium unsupported
-
Date: 2026-06-23
-
Friction: fresh Ubuntu 26.04,
make install/make plugin→ "Failed to install browsers / ERROR: Playwright does not support chromium on ubuntu26.04-x64" → "GStack ./setup failed". Non-fatal in our wrapper (warn only) but gstack's browser (/browse,/qa, design screenshots) is silently dead once gstack is enabled. -
Real cause: Playwright 1.58.2 (pinned in the gstack submodule) registry lists
ubuntu20.04/22.04/24.04only; 26.04 released later → not in list →getHostPlatformerrors. Pure OS-newness, not an install bug. -
Solution: gated
export PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64(ubuntu >24.04 only) before gstack setup + persisted to.bashrcfor runtime. Playwright then pulls a Chrome-for-Testing fallback build for ubuntu24.04. Verified on 26.04:lddresolves all libs + real headless render OK. -
Status: resolved (commit
211c7d4). Residual: exact rev 1208 launch not in-session-tested (sandbox download hung at extraction); proved via sibling rev 1228 same-platform CfT build. Confirm on next realmake plugin. Proper upstream fix = gstack bumps Playwright to a version that lists ubuntu26.04. See LRN-038. -
2026-06-23 UPDATE — Solution REVERTED, status downgraded to UPSTREAM/open (commit
b9c3937): thePLAYWRIGHT_HOST_PLATFORM_OVERRIDEsolution above does NOT work on 26.04. The fallback build downloads to 100% then HANGS at extraction (chrome binary never appears, no headless-shell download starts; reproduced on real machine + sandbox) → turned a 0.5s fast-fail into an install-blocking hang (user Ctrl+C). Reverted to the fast-fail (non-fatal; gstack OFF by default, browser only for /browse,/qa,screenshots). The earlier "verified ldd + headless render" was an isolated test on a sibling already-extracted build (rev 1228) — it masked the rev-1208 install-path hang. Real fix = upstream: gstack bumps Playwright to a version that lists ubuntu26.04. Until then gstack's browser is unavailable on 26.04, install completes cleanly. See LRN-038 correction. -
2026-06-23 FINAL — RESOLVED (commit
3b8ffb1): gstack browser now works on Ubuntu 26.04. Two layers fixed: (1) bumped gstack's pinned Playwright 1.58.2 → 1.61 (bun add playwright@latestin the submodule; 1.61 ships a native ubuntu26.04 build — chromium rev 1228), automated in the installer (gstack_bump_playwright_if_unsupported, idempotent, OS-gated); (2)GSTACK_CHROMIUM_NO_SANDBOX=1to work around the AppArmor userns restriction (sysctl kernel.apparmor_restrict_unprivileged_userns=1), persisted to.bashrc+ installer Step 9 (sysctl-gated). Verified end-to-end:browse goto https://example.com→ "Navigated (200)". Caveat: the Playwright bump is a local submodule edit, reset bygit submodule update, re-applied by the next install. See BDR-029, LRN-040.
BLK-009 — user-level path-scoped rules don't load (#21858) — still broken in CC 2.1.190
- Date: 2026-06-25
- Friction: tried to scope a global rule to matching files via
paths:frontmatter in~/.claude/rules/<name>.md— the rule never injects, even when a matching file (*.probe) is read in a fresh session. Blocks any "load this guidance only for matching files" strategy at the user level. - Real cause: GitHub issue #21858 — user-level (
~/.claude/rules/) rules carryingpaths:frontmatter are not evaluated/injected; still unfixed in 2.1.190. (Project-level path-scoped rules not tested here.) - Probe method: 3-file probe —
_probe.md(paths: ["**/*.probe"], sentinelSENTINEL_USER_RULE_LOADED),_probe_ctl.md(NOpaths, control sentinelCONTROL_NOPATHS_LOADED),_probe_target.probe(target, read in a fresh session). Result: control sentinel PRESENT in session context, path-scoped sentinel ABSENT → the path-scoped rule did not load. Probe files removed after. - Status: upstream, open. Workaround: don't rely on user-level path-scoping → keep global guidance unconditional + COMPRESSED (BDR-031). Side-note: native auto-memory = "on" but writes nothing yet (fresh machine). Re-test on CC upgrades.
- 2026-07-06 UPDATE — RESOLVED: re-probed
paths:frontmatter lazy-load with fresh 3-file probe (**/*.blkprobeglob) — confirmed loading works at BOTH project-level AND user-level (~/.claude/rules/) rule dirs. #21858 no longer reproduces on current CC version. Status → resolved. Prior workaround (unconditional + compressed global CLAUDE.md, BDR-031) no longer forced by this bug — see LRN-103. - Reference: GitHub #21858. Linked to BDR-031, LRN-044, LRN-103.
BLK-010 — init-project scaffold + bootstrap README have no deterministic commit owner; worktree on unborn HEAD
-
Date: 2026-06-27
-
Friction: init-project scaffold (STEP 5 — CLAUDE.md, settings, config, entry points,
.gitignore,.env.example,.claude/) + bootstrap README (STEP 5b) never get an explicit commit. Pipeline's only commits = STEP 10b memory (helper) + STEP 8 per-task implementer commits. Whether scaffold/README land in a commit = emergent: implementer-prompt.md says only "4. Commit your work", scope undefined. Greenfield deeper: STEP 8subagent-driven-developmentrequiresusing-git-worktrees→git worktree add -bbranches from HEAD, but post-git initHEAD is UNBORN → add fails; the worktree skill has no unborn-HEAD path. -
Real cause: no deterministic commit step between
git init(STEP 5) and FINISH (STEP 11). scaffolder + doc-syncer both write-only (zerogit commit). implementer commit scope unspecified.using-git-worktreesassumes a born HEAD. -
Solution: open — own chantier (real technical weight: unborn HEAD + worktree). Candidate: explicit initial scaffold commit after STEP 5/5b before STEP 8, OR handle unborn HEAD in the worktree step. NOT cured by the doc-sync coupled chantier — that commits ONLY doc-sync's patched files and (correctly) excludes scaffold. Consequence: after doc-sync coupled, ship-feature fully fixed, init-project PARTIAL (doc-sync ok, scaffold/bootstrap still open).
-
Status: resolved (2026-06-29; working tree uncommitted — durable only at the claude repo commit, cf BLK-012). Was "open"; closed by the gitflow chantier — see note below.
-
Reference: discovered in doc-sync-coupled analysis (2026-06-27). Distinct from the doc-sync twin BDR-034. Sibling BLK-011. Surfaces via analyze-before-plan bookend on any init-project commit-flow work.
-
2026-06-29 — RESOLVED by the gitflow chantier:
gitflow_initfresh path (_gitflow_init_fresh: unborn HEAD →git symbolic-ref HEAD refs/heads/main→git add -A→ deterministic root commit →git branch develop) wired at init-project STEP 5f (after scaffold STEP 5 + README STEP 5b, before STEP 8 implement). Closes all 3 components: (a) scaffold+README get a deterministic commit owner = the root commit (git add -Astages whole tree; SKILL.md STEP 5f + lines 141/249-250 "scaffold commit owner … BLK-010 closed"); (b) root commit + develop make HEAD BORN before STEP 8 →gitflow start feature/worktree add -bnever hits unborn HEAD; (c) STEP 5f IS the deterministic commit step betweengit initand FINISH. Tested: gitflow-test.sh T2 "init fresh (BLK-010 root commit)" (root commit on main, socle IN root commit, hook tracked, tree clean). Residual (non-blocking): the genericusing-git-worktreesskill still has no unborn-HEAD path — now MOOT (HEAD always born by STEP 5f, never reached), not patched in the skill itself.
BLK-011 — init-project STEP 13 GSD post-FINISH creates ROADMAP.md → stranded doc
- Date: 2026-06-27
- Friction: init-project STEP 13 (GSD v2 init) runs post-FINISH (STEP 11).
gsd initcreates.gsd/+ROADMAP.md(a public doc). Created AFTER FINISH integrates → ROADMAP never in the merge/PR. Same PR-stranding class as the doc-sync twin, 3rd post-FINISH artifact. - Real cause: artifact-producing step ordered after FINISH (= BDR-034 class).
gsd initis a CLI mechanism distinct from doc-syncer; ROADMAP is sync-only for doc-syncer (never created by it, BDR-022 rules), so the doc-sync coupled chantier does not touch it. - Solution: open — separate thread. Candidate: reorder GSD before FINISH, or commit ROADMAP after
gsd init. Out of scope for doc-sync coupled (different mechanism). [historical candidates — NOT the route taken] - Resolution: RESOLVED 2026-06-29 — by REMOVAL, not by committing the orphan. init-project STEP 12 (speculative gsd auto-bootstrap) DELETED → ROADMAP/.gsd never created post-FINISH → orphan dissolves, no commit helper built. TRUE reason: auto-bootstrapping a heavy multi-session ENGINE the sole user doesn't use, AT project-creation, is bad on its own terms. NOT the initial framing "ROADMAP redundant with TODO" — that was wrong and would have aged badly: gsd ≫ roadmap (state machine / crash-recovery / cost / parallel / worktree), and TODO ≠ gsd ROADMAP (different altitude + consumer). Reasoning trace: BOTH initial premises (gsd=only-roadmap; TODO-redundant) REFUTED on read, yet conclusion A (remove STEP 12) held for the STRONGER reason — right answer, reason corrected before engraving. Deliberate gsd use KEPT (onboarder PHASE 6
/onboard add gsd, plugin-advisor reco, status-reporter.gsd/read, USAGEgsd init). Removed STEP 12 + header 12→11-step + 10c note + 4 USAGE refs; coherence sweep = zero dangling refs. LRN-072 - Status: resolved (init-project STEP 12 removed —
skills/init-project/SKILL.md; branch bugfix/blk-011-gsd-roadmap). Title says "STEP 13" — stale (was STEP 12 at removal per BDR-036 renumber); left per append-only. - Reference: discovered in doc-sync-coupled analysis (2026-06-27). Sibling BLK-010 + twin BDR-034.
BLK-012 — gitflow_init non-transactional: socle-commit failure swallowed → hook activated on partial run → re-run self-blocks
- Date: 2026-06-29
- Friction: migrating faunosteo,
migrate_local→gitflow_inithalf-applied TWICE. Run 1: master→main renamed, develop created, socle staged, but the socle commit died —Author identity unknown ... unable to auto-detect email address (got 'bchanot@bchanot-server.(none)')→ tree DIRTY, exit 1. Run 2 (recovery): socle commit BLOCKED by the gitflow hook itself (gitflow pre-commit: BLOCKED — direct commit on 'main'), yetinitreportedexit=0(a lie); main still at the old tip, socle uncommitted. - Real cause:
_gitflow_init_existingSWALLOWED the socle-commit failure —git diff --cached --quiet || git commitwith no propagation, and the function's last stmt (git branch develop) returned 0, masking the dead commit. Init CONTINUED past the failed commit → rangitflow_activate_hookthough the socle was never committed → re-run then self-blocks (commit on main blocked by the now-active hook). Design's "idempotent" + "never self-blocked" claims hold ONLY for a clean single run; a partial run breaks both. Fresh-repo path already propagated its failure (_gitflow_init_fresh); existing-repo path did not — the asymmetry was the bug. Trigger upstream of it: git identity UNSET (global unset; faunosteo had no local identity, though its own history usesBastien Chanot <git@bchanot.fr>). - Solution: (1) socle commit FATAL in
_gitflow_init_existing—if ! git diff --cached --quiet; then git commit … || { echo …; return 1; }; fi→ aborts BEFORE develop/hook-activation; (2) identity precheck at top ofgitflow_init(fail loud, no half-apply); (3) identity guard ingitflow-migrate.sh:migrate_local. Recovery: set faunosteo local identity → deactivate hook → delete premature develop → reinit (socle commits with hook inactive, as designed) → main==develop @ socle, tree clean, master renamed. Verified: shellcheck clean, 57/57 tests pass, hardened init on an identity-less repo aborts rc1 with ZERO mutation. - Status: resolved (
lib/gitflow.sh+lib/gitflow-migrate.sh, uncommitted working tree as of the gitflow chantier). - Reference: LRN-068 (transactional-bootstrap principle). Discovered mid gitflow-migration 2026-06-29. Sibling chantier learning LRN-067.
BLK-013 — make plugin Error 127: npm absent on apt-nodejs host
- Date: 2026-06-30
- Friction:
make plugin(→install-plugins.sh) aborts at Step 4 (gsd-pi):install-plugins.sh: line 425: npm: command not found→make: *** [Makefile:10: plugin] Error 127. Steps 5-10 never run, AND the post-Step-4 stray-dir cleanup (Step 8.5) never reached → the BDR-030/LRN-042 residual (stray$REPO/.agents/skills+$REPO/.claude/skills, promised "auto-cleaned nextmake plugin") silently persists run after run. SessionStart banner already showedgsd v2 ✗. - Real cause: Debian/apt
nodejspackage shipsnodeWITHOUTnpm(npm = separate apt pkg)./usr/bin/nodepresent (v22.22.1); its bindir has acorn/corepack/semver but NO npm/npx — npm genuinely uninstalled, not a PATH miss. install-plugins.sh Step 1 checksnode >=22but NEVER verifies npm — assumes npm ships with node (true for nodesource/brew/dnf paths, FALSE for plain apt). - Solution: corepack (ships with node) over apt npm (apt npm could pull a divergent 2nd node).
corepack enable --install-directory "$HOME/.local/bin" npm→ npm 11.18.0 shim, no sudo,~/.local/binalready on PATH. Thennpm config set prefix "$HOME/.local"— default prefix/usris root-owned →npm install -gwould EACCES;~/.localwritable + bins land on PATH. Persisted in~/.npmrc. Re-run → EXIT=0, Step 4 ✓ (gsd-pi@2.64.0), Step 8.5 ran (Removed stray repo-local skills dir: .agents/skills+.claude/skills). Caveat: gsd-pi DEPRECATED + postinstall scripts SKIPPED (npm 11allow-scripts) —gsd --version/--helpok, full provisioning would neednpm install -g --allow-scripts=gsd-pi,… gsd-pi. - Fix-forward: install-plugins.sh Step 1 should GUARANTEE npm on apt-
nodejshosts — detect missing npm +corepack enable npm(not just check node) → stops Error 127 recurring on any fresh apt machine. - Status: resolved (env-level: corepack shim + npm prefix; zero repo change). Fix-forward (script hardening) NOT built.
- Reference: discovered fixing
make plugin2026-06-30. Distinct from BLK-003 (macOS playwright hardcoded path) + the Playwright-chromiummake pluginfailure. Blocked residual = BDR-030/LRN-042. - Update 2026-07-01: fix-forward BUILT. install-plugins.sh Step 1 gained unconditional npm guard (
corepack enable npm→ distroinstall npmfallback → fatalexit 1), placed AFTER theNODE_OKshort-circuit so a node>=22-present-but-npm-absent host no longer skips it. Now fully resolved (env-level + script). shellcheck/bash -nclean; fresh-apt live validation still pending. Commit1f2c1cc, branchbugfix/install-plugins-npm-guard.
BLK-014 — make install aborts npm EEXIST when claude already present
- Date: 2026-07-01
- Friction:
make install→ install.sh Step 2npm install -g @anthropic-ai/claude-code@latestfails EEXIST on~/.local/bin/claudewhen claude already installed →else err→exit 1. Bootstrap not idempotent on Claude Code step; rest (auth, symlinks, plugins) never runs. - Real cause: claude installed via NATIVE installer, not npm —
~/.local/bin/claude= symlink →~/.local/share/claude/versions/<v>(npm ls -g @anthropic-ai/claude-code= empty;claude --version= 2.1.197). npm prefix~/.local(set by BLK-013) targets same~/.local/bin/claude→ npm won't clobber a bin it doesn't own → EEXIST. Channel conflict, not double-install. Step had NO presence guard, unlike RTK (install-plugins.sh:388) / GSD (:419) / claude check (:252). - Solution: install.sh — skip-if-present guard
command -v claude(mirror RTK/GSD), npm only fresh machine (elif). update-all.sh — channel-aware updater:npm ls -g→ npm-managed uses npm, else native usesclaude update(self-update). Nevernpm --force(would clobber native, break self-update). - Status: resolved. Fix
8dc4027, branchbugfix/install-claude-idempotent, pending merge validation. - Reference: BLK-013 npm prefix
~/.local= contributing factor (npm bin over native bin). install-plugins.sh already pointed to code.claude.com (native) — install.sh was the npm outlier. Fresh-machineelif npmbranch channel-consistency = open design question (potential BDR). Pattern → LRN-085. - Update 2026-07-01: MERGED
2393ca5(bugfix/install-claude-idempotent → develop), pushed — supersedes "pending merge validation". The open channel-consistency question is RESOLVED by BDR-046 (fresh install → native installer, npm dropped for claude); install.sh has noelif npmbranch → nothing left to trancher.
BLK-015 — gitflow_finish ignored its args, merged the CURRENT branch not the one asked
- Date: 2026-07-03
- Friction: audit 2026-07-02 —
gitflow.sh finish bugfix audit-bugsrun while checked out onfeature/audit-tokensmerged audit-tokens (LOT3), NOT audit-bugs. Final develop state identical (disjoint hunks) so no data damage, but the merge order was silently wrong. UX trap: the command LOOKS like it targetsbugfix/audit-bugs. - Real cause: CLI dispatch (
lib/gitflow.sh:257finish) gitflow_finish "$@") forwards args, but the function derived its source fromHEAD(git symbolic-ref) and NEVER read$1/$2→ the<type> <name>were silently dropped. Merge source = ambient state (checked-out branch), not the named target. Design intended finish to always operate on HEAD (human gate = "be on the branch"), but nothing enforced that passed args, if any, MATCH the branch you're on. - Solution:
gitflow_finish [<type> <name>]— args now an optional safety ASSERTION: present AND"$req_type/$req_name" != "$br"→ erroroperates on the current branch 'X', but you asked 'Y' — checkout 'Y' first, rc 2. No args = behavior unchanged (only real callerskills/gitflow/SKILL.md:36+ every test pass none → zero regression). +7 regression assertions (gitflow-test.shT12, numbered to dodge collision with reconcile's own T6c). - Status: resolved. Commit
d9fdd4c, branchbugfix/gitflow-finish-args. - Reference: journal 2026-07-02 (trap noted, not fixed) → fixed 2026-07-03. Pattern → LRN-089 (pass-through wrapper deriving target from ambient state = silent contract violation).
BLK-016 — rtk compression PATH-dead for 30 days: installer's own check can't see the tool shell
- Date: 2026-07-04
- Friction: user asked "is rtk installed + used right?". Measured (
rtk discover): 6 of 5070 Bash commands compressed over 30 days, ~460K tokens missed (grep ~144K, git status ~112K, ls ~92K…). Hook registered, integrity pin OK, registry broad — yet near-zero real usage. Nobody noticed: degradation was silent (LRN-047 class). - Real cause: two-layer. (1) cargo installs rtk into
~/.cargo/bin; hand-managed profile lost the PATH line (LRN-036 class) → Claude's TOOL shell can't resolvertk. (2) install-plugins.sh sources~/.cargo/envfor itself, so itscommand -v rtkcheck PASSES in the installer shell — validating an env the runtime never has. Hook survived via absolute-path substitution, but ONLY at string head (f0b7e89guard): every COMPOUND rewrite (dominant Claude style — echo separators,&&) was dropped by design. - Solution: bridge symlink
~/.cargo/bin/rtk→~/.local/bin/rtk(standard PATH). Immediate: created live, compound rewrites revived, proven in-session (bare grep →rtk grepoutput). Durable: install-plugins.sh STEP 3 idempotent self-repairing bridge, flip-tested 4/4 sandboxed HOME (LRN-096). Commite58037c(RC fix on release/1.0.0). - Status: resolved.
- Reference: lesson: a PATH-dependent hook must be verified in the TARGET shell, not the installer's (installer sourcing envs lies to its own checks); usage is MEASURED (
rtk discover), never assumed. Corroborates LRN-047 (silent degradation → measure) + LRN-036 (hand-managed profile drift); guard interplay LRN-089-adjacent (ambient-state assumptions). - backmerge: entry from release/1.0.0 (2b4e7401); the fix
e58037cwas ALSO missing from develop (rtk was live-broken on develop) — ported to develop 2026-07-08 (review remediation A3, commit follows) so this "resolved" is now true on develop too.
BLK-017 — Bing Webmaster API unusable for a multi-client agency (W2 deferred) — 2026-07-17
- Friction: W2 (
bingverb — free Bing query stats + index status + first-party backlinks) abandoned after 4 challenge rounds. User's model = client sites live on CLIENT Bing accounts. - Real cause: two viable-looking paths, both dead. (API KEY) is per-user not per-site (docs), but IS the account identity → one key per client account, exactly what the user feared; non-scoped, no expiry, passed in query string. (OAuth) is the right delegation model (like GSC) but a swamp: Redirect URI rejects ALL local forms (http/https/127.0.0.1 — user-tested); refresh tokens are ROTATED + single-use, self-described non-compliant with OAuth 2.0 → store rewrite every call, AND our parallel seo‖geo dispatch would race the rotation →
invalid_grant+ dead token; undocumented "Could not extract expected anti-forgery token" on refresh, unanswered on MS Q&A; docs contradict themselves on grant_type + token endpoint; no library. MS's own advisor recommends falling back to the API key. - Verified live: the Webmaster API itself is ALIVE (
GetUserSites?apikey=INVALID→ HTTP 400{"ErrorCode":3,"Message":"InvalidApiKey"}, 0.4s) — distinct from Bing SEARCH API (retired 2025-08-11). So the block is auth/model, not availability. - Status: open/deferred. REVIVAL: a client already on Bing adds the user as Read-Only → test in ~10 min whether one API key sees DELEGATED sites (undocumented, nobody knows). If yes → W2 is cheap+clean (one key, client-owned verification, revocable, read-only, zero OAuth). Value RAISED by BDR-071: GetUrlLinks is now the only free viable backlink source (first-party only).
BLK-018 — release-executor finish span blocked by permission classifier (human signal invisible to subagent) — 2026-07-20
- Friction: v1.3.1 release —
SPAN: finishdispatch denied at tool-permission layer: classifier flagged "Merge Without Review" (gitflow.sh finishin subagent transcript carries no explicit human merge signal). Executor correctly refused workaround, reported BLOCKED. v1.2.0/v1.3.0 same span passed → classifier behavior change, not skill regression. - Real cause: gitflow doctrine "finish only on explicit human signal" lives in DISPATCHER transcript (user ask + STEP 4 AskUserQuestion go); subagent transcript starts fresh → classifier sees consequential merge with zero authorization evidence. Structural: any human-gated action dispatched to a subagent loses its gate evidence.
- Solution (workaround): dispatcher ran
gitflow.sh finish+ tag inline after its own human gate — where the signal is real. Release completed clean (main648bc6e, tag v1.3.1). - Status: open. Candidate fixes: (a) quote gate evidence verbatim in span prompt — untested vs classifier; (b) move finish+tag span permanently inline in /release-candidate — keeps prep span dispatched, costs the sonnet pin on ~5 mechanical commands, cheap; (c) permission rule allowing subagent
gitflow.sh finish— weakens the guard, refused. Decide at next release. - Status (2026-10-23, reconcile): open. Did not recur at 2.0.0 (journal: release-executor finish passed), no fix applied (release-candidate SKILL.md:88-90 still dispatches
SPAN: finish). Decide (a)/(b) at 3.0.0. - Reference: skill
release-candidateSTEP 5. Pattern adjacent LRN-089 (ambient-state/context assumptions across boundaries). Journal 2026-07-20. - Status (2026-11-02): resolved
536d39e: option b, /release-candidate runs gitflow.sh finish and the tag in the main loop under the ask prompt
BLK-019 — notify-attention bell silent, toast OK (VS Code client default) — 2026-09-01
- Friction: hook fired, Windows toast arrived, native bell never audible. User heard only Windows toast sound. Looked like half-broken hook.
- Real cause: not hook. Toast proves full
terminalSequencereached terminal,\a\asits at head of that same string → BEL emitted. VS Code defaultsaccessibility.signals.terminalBellto"auto"= sound OFF unless screen reader active. - Solution:
"accessibility.signals.terminalBell": { "sound": "on" }in CLIENT-side user settings.json (c:/Users/<u>/AppData/Roaming/Code/User/). Unreachable from remote: real SSH remote, not WSL (no/mnt/c,/proc/versionno Microsoft). User applied, retest → both channels OK. - Status: resolved (per-client-machine, not repo-portable).
- Reference:
~/.claude/hooks/notify-attention.shheader already documented the setting; never applied. New client machine → bell mute again while toast works. Silent-degradation class LRN-047. - Status (2026-10-28, upgrade): superseded by BLK-028
BLK-020 — notify-attention: both channels dead on one VS Code client — 2026-09-02
- Friction: client-side prereqs applied on Windows box (ext
wenbopan.vscode-terminal-osc-notifier+accessibility.signals.terminalBellsound:on), window reloaded. AskUserQuestion → nothing.idle_prompt90s wait → nothing. Direct write\a\a+ OSC 777 to claude own pty (/dev/pts/2) → nothing. Second client machine, same SSH server, same hook, same registries → both channels OK. - Server side cleared: hook dry-run emits
BELx2 + OSC 777 + STcorrectly,jqpresent, matcher coversidle_prompt, ext NOT wrongly installed remote-side. Not a hook bug — same class as BLK-019 (client default silently degrades). - Real cause: unresolved. Facts: claude runs under
dtach -c ~/.dtach/claude-190012; claude fd1 =/dev/pts/2(inner pty, dtach master side), REAL VS Code terminal =/dev/pts/1held by dtach client pid 742794.VSCODE_SHELL_INTEGRATIONunset this terminal; ext marketplace doc requires shell integration ON. BUT other working session (claude-154323) also runs under dtach → dtach alone insufficient explanation, weight shifts back to client-side. - Probes run: direct write to
/dev/pts/1(real VS Code pty, chain alive: bash pts/1 → dtach client 742794 S+ → master → claude pts/2) → no bell, no toast. Visible-marker injection both paths → user saw neither, BUT inconclusive: claude TUI repaints, injected text clobbered next frame. Only BEL is repaint-proof, and BEL stays silent. - Client settings verified by user: settings.json path correct (no VS Code profile indirection),
terminalBellsound on, ext installed + enabled local side. VS Code recent (server dirs 2026-08), so ≥ 1.93 ext requirement met. - Next probe: user opens FRESH VS Code integrated terminal (no dtach, no claude TUI) and runs
printf '\a\a\033]777;notify;Test;hello\033\\'. Isolates client renderer from claude/dtach path. Beep+toast there → fault in claude/dtach path; nothing → client-side, diff against working machine. - Fresh-terminal probe (decisive): user ran
printf '\a\a\033]777;notify;Test;hello\033\\'in NEW VS Code terminal → toast OK, bell still silent. Splits one symptom into TWO independent faults. - Fault A (toast in claude session): ext parses only terminals created AFTER its activation. Claude terminal pts/1 born 19:00, ext installed later same day → that terminal never hooked. Fix: restart claude in fresh terminal, or re-attach existing dtach session from one (
dtach -a ~/.dtach/<sess>; dtach broadcasts to multiple clients, no session loss). NOT a dtach filtering bug — earlier hypothesis wrong. - Fault B (bell): silent even in fresh terminal where toast works → not terminal path, VS Code audio side. Toast sound = Windows notification (works); bell = VS Code process audio (mute). Suspects: signal volume option, Windows volume mixer entry for Code, output device. Probe: palette
Help: List Signal Sounds→ Terminal Bell plays preview or not. - Fault A RESOLVED (verified 2026-09-02): re-attached session from fresh terminal (
dtach -a ~/.dtach/claude-190012, new client pts/3). Both sends toasted — one through session path (pts/2, dtach broadcast), one direct. Rule: ext hooks only terminals born AFTER its activation → install ext, THEN start/re-attach claude session. dtach broadcast means zero session loss. - Fault B still open: bell silent on every path. New signal: toasts arrive but user reports NO sound at all, while BLK-019 machine got audible Windows toast sound. Both audio channels dead + both visual channels fine → common factor is client audio output, not terminal stream. Suspects ranked: Windows per-app notification sound off for Code, system/app volume mixer mute, wrong output device,
accessibility.signalOptions.volume0. - Fault B ROOT CAUSE ISOLATED (2026-09-02): palette
Help: List Signal Sounds→ Terminal Bell preview plays NO sound, while Windows toast sound IS audible. Preview bypasses terminal, BEL, hook, dtach, ext entirely → VS Code renderer audio itself mute on this box. Toast sound emitted by Windows shell, not by Code → explains why one audio channel works and other does not. - Fix candidates (client, ranked): (1) Windows per-app volume mixer — Code muted/0, or per-app OUTPUT DEVICE pointing at disconnected device (mixer only lists app after it attempts playback → hit preview first, then open mixer); (2) VS Code
accessibility.signalOptions.volume= 0 kills all signals; (3) compare both against working machine. - Pragmatic out: toast already carries audible Windows sound → attention signal functional without bell. Bell is redundant channel, not blocker.
- Fault B RESOLVED (2026-09-03): cause = Windows per-app volume mixer, Code entry at 0. Toast audible throughout because Windows shell emits that sound, not Code → masked a plain app-volume mute. User set volume up → bell audible.
- Status: resolved (A: ext hooks only terminals born after activation → install ext THEN start/re-attach session; B: Code app volume 0 in Windows mixer).
- Lesson: two independent client faults presented as one symptom ("nothing works"). Splitting probe = run signal in FRESH terminal + play VS Code's own sound preview. Preview bypasses terminal/BEL/hook/dtach/ext → isolates renderer audio in one step. Do that FIRST next time, before any server-side archaeology.
- Reference: BLK-019 bell-only variant (resolved differently — setting alone insufficient here), LRN-145 terminalSequence-not-/dev/tty pattern. Silent-degradation class LRN-047.
- Status (2026-10-28, upgrade): superseded by BLK-028
BLK-021 — Bash tool dead mid-session ("every command exits 1"): /tmp usrquota blown by a dead session's probe HOMEs — 2026-09-22
- Friction: previous session on
feature/21st-cli-migrationlost its shell before tests + commit: every Bash call,echoincluded, returned 1. Its harness fileimptest2/step8d-test.shlanded as 0 bytes. - Real cause (strong evidence, not reproduced on purpose):
/tmp= tmpfs 7.4 GB mountedusrquota;/tmp/claude-1000/-home-bchanot-Documents-claude/fefd277c-…/scratchpadholds 5.9 GB of sandbox HOMEs (pinprobe/2.1 GB,pinrc/1.6 GB,imp1 impg imptest sbx1 sbx2 v3.2.0 v3.6.1 v4.0.5 …) from the impeccable pin probes.dd40 MB to/tmp/claude-1000→ "Disk quota exceeded" (EDQUOT) whiledfstill shows 1.6 GB avail. Same write to~/.cacheOK. Bash tool +mktemp+ heredocs live in /tmp → all die together. This session: first impeccable probe failed withQuota exceeded (os error 122)on the installer's/tmp/impeccable-update-*staging, same cause. - Solution: this round ran everything with
TMPDIR=~/.cache/imp-probe/tmp(probe, harness,make test). Durable fix = delete the dead session's scratchpad:rm -rf /tmp/claude-1000/-home-bchanot-Documents-claude/fefd277c-e143-4d51-b589-a566641079b5(agent'srm -rfon /tmp denied by the classifier → user action). Rule for probes: sandbox HOMEs that pull npm/node payloads go under~/.cache/<probe>/, never the /tmp scratchpad, and get removed at the end of the session. - Recurred same day: this session's shell died the same way mid-G8 (BDR-095 amendment) while the 5.9 GB still sat there; recovered the moment the user deleted the dir. Mechanism now established, not inferred: stock
/usr/lib/systemd/system/tmp.mountmounts /tmp withx-systemd.graceful-option=usrquota(no override, no fstab line on this machine) and systemd caps each user at 80% of the tmpfs → 0.8 × 7.4 GB = 5.9 GB, the exact volume observed. One quota for every session AND every sub-agent of the uid: multi-session is not the cause, the shared cap is. - Durable fix: (1) launch claude with
TMPDIR=$HOME/.cache/claude-tmp(in~/.bashrcdtach_claude(), beforeexec claude;mkdir -pit) → Claude Code's scratchpad, tool outputs,mktempand npm staging all leave the tmpfs; children inherit. (2)~/.config/user-tmpfiles.d/claude-tmp.confwithe %h/.cache/claude-tmp - - - 3d+ the usersystemd-tmpfiles-clean.timerso dead-session dirs age out. (3)make doctor"Scratchpad" section warns while TMPDIR sits on a quota'd tmpfs. Probe rule unchanged: HOMEs with npm payloads under~/.cache/<probe>/. - Status: cause established; open until the launcher exports TMPDIR (user's .bashrc, hand-managed). Links BDR-094, BDR-095, LRN-159.
- Status (2026-11-02): resolved 2026-11-02: lib/cc.sh exports TMPDIR=$HOME/.cache/claude-tmp for every cc session (phase 5)
BLK-022 — hooks/guard-bash.sh withheld by the safety classifier; executable spec shipped instead — 2026-09-22
- Friction: layer C item G2 (PreToolUse Bash guard: whole-command scan incl. nested
bash -c,docker compose run … lftp, scripts the command runs; exit 2 + reason +loggertrace; fail-closed without jq). The response carrying the hook body was stopped by a safety classifier mid-write; content withheld, instruction not to regenerate it. - Real cause: the hook body is a dense list of destructive-command patterns (rm -r forms, disk tools, docker escapes, history rewrites); the classifier reads it as harmful capability regardless of the defensive frame.
- Solution:
lib/tests/guard-bash.test.sh(214 cases, deny/allow) stays as the spec and SKIPs while the hook is absent, somake teststays green. Options: user writes the hook against the spec (start from/mnt/cloudpex/RECOVERY/01-prochain-systeme/claude-config/hooks/guard-bash.sh, already on disk, then iterate to green); or a different design (allowlist of first words + path containment) requested explicitly. Until then: static deny (BDR-095) covers the direct forms; nested forms rely on the classifier prose. - Status: open. Links BDR-095, LRN-160.
BLK-023 — floor-guard xit( substring flags every exit( — 2026-09-28
- Friction: fresh verifier returned ECARTS(1) on a fully conform diff:
FLOOR SKIP lib/tests/profile-census.test.sh:116 sys.exit(1 if violations else 0). One re-dispatch spent on a tool artefact. - Real cause:
lib/floor-guard.shSKIP_SUBSTRINGS holds the bare fragment'xit('to catch Jasmine'sxit(…);skip_kind()is a plain substring match, sosys.exit(,SystemExit(,process.exit(all hit. - Solution: workaround applied — the inline python prints violations only, the bash wrapper derives the return code from the captured output (no
exit(anywhere). Root fix pending: word-bound the pattern ((^|[^a-zA-Z_.])xit\() or matchxit(only in JS/TS test files; hotfix-sized. - Status: resolved 2026-09-28 — hotfix
0deb559(bugfix/floor-guard-xit-boundary): the four bare Jasmine identifiers moved intoSKIP_IDENT_REwith lookbehind(?<![A-Za-z0-9_.]), dotted/decorator forms stay substrings; fixtures SKIP_EXIT_CLEAN (RED before, GREEN after) + xit/fit/fdescribe flags. Residualshortcut:in the guard:def fit(/function xit(still match,xit (/xit.each(still do not (as before). Links BDR-105, BDR-102 (floor-guard origin), EVAL-034.
BLK-024 — resync dropped the vendored effort pins, twice — 2026-09-29
- Friction: BDR-107 re-applied brainstorming/writing-plans xhigh only in install-plugins.sh STEP 8e; update-all.sh §7.3 re-fetches at the same commit → SKILL.md overwritten,
effort:gone until the nextmake plugin. Latent since 2026-09-28. - Real cause (second instance): my re-apply call landed after the superpowers refresh; update-all.sh §7.4 (21st pack) runs LATER and
rm -rf+mvevery 21st-* SKILL.md. My grep of update-all.sh was truncated by rtk ("+28 more hidden") and I read the partial listing as the whole file. Fresh verifier caught it (ECARTS). - Solution:
lib/effort-pins.txt+lib/effort-pins.shcalled ONCE after the LAST vendoring step of both scripts; census locks the order by line number (ln_last). Rule: a truncated tool listing is not a census; re-run without the pager or grep the anchor directly. - Status: resolved 2026-09-29 (feature/effort-round, BDR-108).
BLK-025 — deny rule bypassed by an alias spelling: npm i -g vs npm install -g — 2026-09-30
- Friction: user pasted a vendor setup block ("run
npm i -g @higgsfield/cli"); command ran. settings.json deniesBash(npm install -g *)(BDR-093: global installs are the user's, viamake plugin). Rule read only later, in the analyzer digest. - Real cause: deny entries are literal patterns;
ialias and--globalspelling do not match. No refusal fired, so nothing signalled the guardrail. Not a deliberate reroute, same effect. - Solution: deny +=
npm i -g *,npm install --global *,npm i --global *(3dad33e, user go). Disclosed to the user at the design gate. Rule for me: before a global install, grep settings.jsondenyfor the verb family, not the exact spelling. - Status: resolved (partial) 2026-09-30 — flag-after-package forms (
npm i <pkg> -g,npm add -g,npm -g i) still pass; pattern grammar for a mid-string wildcard unverified. Open question left to the user. BDR-109
BLK-026 — make test red on macOS: GNU-only idioms — 2026-10-06
- Friction: release prep for 2.0.0 ran
make test: 13 suites red, ~45 FAIL. gitflow-test 15 "merged into" FAIL while merge commit present. - Real cause: suite + 7 libs written on Ubuntu.
cmd | grep -qunderset -o pipefail: grep exits at 1st match, producer SIGPIPE rc 141 (5/5 repro ongit log | grep -q). Plussed -ino suffix (BSD reads file as script),wc -lpadded,stat -c,touch -d,realpath -m(gstack write-guard never fired), baretimeoutoff sanitized PATH (design gate UNVERIFIED),grep -oP(update-all_pluginsempty), empty array underset -uon bash 3.2, extractor false positive in doctrine-citers. Effort pins also dropped on 2 gitignored SKILL.md (cause not established, re-applied by hand). - Solution: BDR-110 forms at every site, 23 files, commit 0efdff0; regression tests T4b, Alphabet/Alpha flip, profile-set-managed T18, portability-census suite.
- Status: resolved 2026-10-06. Open: Linux
make testdeferred (TODO); effort-pins re-red trigger (TODO).
BLK-027 — machine never onboarded: no global hooksPath, push hook silent — 2026-10-06
- Friction: fix commit
0efdff0and release/2.0.0 prep commit stayed[ahead 1]; nobody noticed untilgit status -sb. - Real cause:
make linknever run on this Mac →core.hooksPathunset (local + global),~/.claude/githooksabsent.gitflow startpushes explicitly so branch creation looked fine; commits rely on the post-commit hook.make linkalso reportsmake pluginnever ran (11 vendored skills absent) and~/.claude/.envmissing. - Solution: pushed both branches by hand;
make linkrun (user go) →core.hooksPath=~/.claude/githooks, 4 hooks installed.make doctor"Git hooks" section flags this; run it first on a new machine. - Status: resolved for hooks; open:
make plugin+.envon this machine (user action).
BLK-028 — notify-attention on VS Code client: three client-side faults, one probe order (merge BLK-019 + BLK-020) — 2026-10-06
- Friction: hook fires, server side clean, yet bell and/or toast silent on a VS Code client over SSH. Looks like half-broken hook. Two machines, three distinct faults.
- Real cause (3 faults, all client-side): (1) VS Code
accessibility.signals.terminalBelldefaults"auto"= sound OFF unless screen reader active (BLK-019). (2) extwenbopan.vscode-terminal-osc-notifierparses only terminals created AFTER its activation: claude terminal born before install never hooked, toast dead (BLK-020 fault A). (3) Windows per-app volume mixer, Code entry at 0: toast still audible because Windows shell emits that sound, not Code → masked plain app mute (BLK-020 fault B). Not a hook bug; not dtach (dtach broadcasts to every attached client, zero session loss). - Solution: client settings.json
"accessibility.signals.terminalBell": { "sound": "on" }; install ext THEN start or re-attach claude (dtach -a ~/.dtach/<sess>from a fresh terminal); raise Code volume in Windows mixer (mixer lists app only after it tried playback → hit preview first). Per-client-machine, not repo-portable. - Probe order (do FIRST, before server archaeology): fresh VS Code terminal,
printf '\a\a\033]777;notify;Test;hello\033\\'→ splits terminal path from client renderer; paletteHelp: List Signal Sounds→ Terminal Bell preview bypasses terminal/BEL/hook/dtach/ext, isolates renderer audio in one step. - Status: resolved (BLK-019 2026-09-01, BLK-020 A+B 2026-09-02/03). Sources superseded by this entry; bodies kept for history.
- Reference:
~/.claude/hooks/notify-attention.shheader documents the setting; LRN-145 terminalSequence-not-/dev/tty; silent-degradation class LRN-047; sources BLK-019, BLK-020.
BLK-029 — Mods: model alias set by a hook resolves to a stale id (sonnet → claude-sonnet-5, 404) — 2026-10-08
- Friction: model-router spike. Sub-agent routed by
agent.spawnortool.call Agentrewrite with aliassonnet/haiku→ "model_not_found HTTP 404, model sent to the API: claude-sonnet-5". Same alias typed by the model in the Agent tool param →claude-sonnet-5-5, OK. - Real cause: two alias tables in the CLI (2.1.294): the Agent tool's is current, the function-hooks path's is stale. Not an access issue (
/modellists all four tiers; explicit haiku/sonnet dispatches answered). - Solution: hooks write full ids (
claude-sonnet-5-5,claude-haiku-4-5-20251001,claude-opus-5-5,claude-fable-5-1) from the mod's own table; Agent tool param rewrite stays alias-only (schema enum) → the mod sets the model atagent.spawn, not at the param. - Status: upstream (report to anthropics/claude-code with the request id
req_011Cfppp7VFt8z2Pd3zJrpUi); workaround in model-router. - Reference: LRN-203, plan
.claude/tasks/plans/2026-10-08-model-router-mod.md.
BLK-030 — model-router routes main to Fable out of usage credits; turn lost every session + hold lapse — 2026-10-15
- Friction: Fable 5.1 out of credits.
route(reflect)answeredclaude-fable-5-1 (upgrade)after hold lapse; next request died<synthetic>"You're out of usage credits",apiError: model_requires_usage_credits,error: rate_limit, HTTP 429. Holds 15→30→60 min, user typed "reprends" each time. - Real cause: availability learned only reactively. Breaker (
markDown) fed byclassic.StopFailure+PostModelSwitch auto, i.e. AFTER real request died. Hold in-memory w/ backoff; nothing checked move target before main sent there. 429 body generic (no credits marker) → no cheap typed signal. - Solution:
2cccc43(bugfix/router-probe-before-route).decideFordecides first, then probes decided move target once:$.model.completeraced vsPROBE_MS8000 via sharedraceTimeout; timeout/reject →markDown(..., 'probe')+ ONE re-decision, no further probe.verifiedset kept across/clear, cleared bymarkDown. Never probes cur or held id. Configprobe(default true). Stand-in effort one notch up (reflect xhigh, plan max, orchestrate high) when lower model replaces held tier head where head would have run; explicit/floor effort never bumped. 497 tests. - Status: resolved. Residuals in TODO (explicit
Agent(model:"fable")pins, spawn path, session model itself out of credits, ≤8 s stall per new session). - Reference: LRN-218, BDR-116, BDR-115, LRN-207, contract
.claude/tasks/contracts/2026-10-14-router-probe-before-route-0005.md, plan r3.claude/tasks/plans/2026-10-14-router-probe-before-route-0005.md.
BLK-031 — model-router: session ON Fable w/o credits still loses 1st turn; probe skipped kept model — 2026-10-16
- Friction: session model fable, credits out. Log
main: fable/high → fable/medium (implement: classifier)then "You're out of usage credits", thenclaude-fable-5-1 unavailable (rate_limit) for 15 min. User suspected bad redeploy; not cause. - Real cause:
2cccc43unprobed()requiredcall.moved: only move target probed. Session model = cur, kept bydecideMain→ never probed. New process (emptyverified) + hold lapse (markDowndropsverified, cur = session model again) → real request to dead model. Residual of BLK-030, accepted then. - Solution:
c11cd3bdrops!call.movedguard: model decision lands on (moved or kept) probed once if table id, unverified, not held. Fail → markDown 'probe', one re-decision → leaveDown → opus, stand-in effort +1. Cost ~1.3 s healthy / ≤8 s dead, 1st decision per process. Testprobe: a session model that never answers leaves for opus on the first step. - Status: resolved. Open: leaveDown follows classifier
wanted(implement → sonnet), not opus; "context size unknown" likely document attachment →promptSizeunknown. - Reference: BLK-030, LRN-218, contract
.claude/tasks/contracts/2026-10-16-router-probe-session-model-1850.md.
BLK-032 — Main loop pinned on Fable in long sessions: session model Fable 1M + downgrade cap 120k + prompt rule plan → inline code on Fable xhigh [resolved]
-
Date: 2026-10-19
-
Cause:
~/.claude/settings.json"model": "claude-fable-5-1[1m]"(every session starts on Fable); model-router never moves main above the session model, moves DOWN only underdowngradeMaxTokens120000 (LRN-204 cold read) → a long session (faunosteo R4.x, context > 120k) never reachesimplement/sonnet; prompt rule(plan|design|architecture…)→ phase plan = best/xhigh each turn ("plan §B.1.7"). No doctrine ceiling: CLAUDE.md allows inline work "doable in a few tool calls", BDR-115 "pin = default, never ceiling". -
User policy 2026-10-19: session model Opus 5.5; sonnet writes, opus decides what to write; Fable only for orchestrator reflection/plans and the important audits (security, functional), other judges opus. → next
/feat: settings model,judgesplit, ceiling rule in CLAUDE.md, BDR superseding part of BDR-066 / BDR-115. Links BDR-066, BDR-107, BDR-115, LRN-204. -
Solution (2026-10-23): feat A+B (BDR-123) + feat C
786ee13(feature/router-keyword-cap): keyword prompt rules,ultrathinkfloor, derivedorchestratedispatch write effort-only routes (effortRoute,belowRunpattern) → never lift main above session model; held best-tier run keeps its model (per-axis fall-through);mainModelSlotdropsturnFloor. Fable on main only via skill row,routetool,/route. Docsd2d590f. Links LRN-226, EVAL-048.
BLK-033 — Guardrails residuals: probe trusted plan supabase.url, redirects free of budget, unread bodies read CLOSED; rules 5 FP / 7 misses [resolved]
- Date: 2026-10-21
- Friction: GATE 2 of the a11y split (
f586304) left a MEDIUM + 3 LOW on probe.py, opus review left Minors on the rules. Parked in TODO, fixed via/bugfix2026-10-20/21. - Cause:
supabase.urlread from the plan w/o_http_url→ planted SUPABASE_URL would receive GUARDRAILS_ANON_KEY / JWT2,file://read CLOSED;_SameHostredirector followed hops w/o chargingsession.budget;_rows_statecollapsed non-200 / empty / >1 MB / non-JSON into CLOSED (unobserved = CLOSED, breaks LRN-220); plan r2 mapped budget exhaustion onstr(URLError), which wraps the reason → never matched. Rules: SENSITIVE_KEY on metadata names (token_type,has_password), 403 on first map candidate stopped the walk, hydrated scan read whole route file, NOSQL$wherefired on GraphQL_bool_exp; misses: Go backtick Sprintf,rf/triple-quoted f-strings,sql|db|trx.raw, empty.select(), multi-line hidden input, Rust{}shell arg,"sources"map head. - Solution:
5a98c2c(_BudgetExhausted(URLError)+BUDGET_EXHAUSTEDconstant,_SameHost(session)charges per hop,_rows_staterows|empty|unreadable → SKIPPED,_map_outcomefull candidate walk,data:OPEN w/o decoding,printableon remote strings,_safe_textin scanner, rule fixes + mutant per language variant) +633faa2(checks.md:IN (…)placeholder list flagged, judged by hand). Plan r3 after 2 challenge rounds, contract 22 oracles MET, verifier CONFORME, auditor PASS. Suites probe 84, scan 241. - Residual (LOW, parked in TODO): table names not
IDENT.fullmatch-checked per table (/→ path walk on the approved host);printablelets Unicode bidi/format controls through. Links LRN-219, LRN-220, LRN-222, LRN-223.
BLK-034 — mods.test.sh red on CLI 2.1.306: whole-output warning grep caught the advisory plugin-directory section [resolved]
- Date: 2026-10-22
- Friction:
make test suite=lib/tests/mods.test.sh→FAIL model-router: validate printed a warning, pre-existing on develop (git archive baseline), surfaced as feat B criterion 8 (NEED-DECISION, BDR-123 run). - Cause: CLI 2.1.306
claude plugin validateprints "Plugin directory checks" section (submission catalogue):⚠ Found 1 plugin directory warning:ICON_MISSING,--jsondirectory.findings[].blocking: false. mods.test.sh:57 grepped whole output forwarning(also matched hooks notes quoting register.ts identifiers, checkout paths). Prose scraping of a CLI with an exit-code contract:--strict→ per-file warnings rc 1, directory findings rc only under--profile directory. - Solution:
801992a(bugfix/mods-validate-advisory). Helpervalidate_strict= rc ofclaude plugin validate --strict; check_cli + positive control share it; control = scratch manifests{"name":"warnfix"}(rc 1) / cleanfix with version+description+author (rc 0) under script-levelmktemp -d. Plan r3 after 3 lenses + 1 re-challenge (sed range on closing marker killed: CLI prints it only when findings > 0, fail-open to EOF). GATE 0 7/7, verifier ECARTS(2) = out-of-scope routing.json dialog write only, auditor PASS. - Residual: 3 historical contracts carry old scrape as CHECK oracle (
.claude/tasks/contracts/2026-10-08-model-router-w1a-1533.md:22,2026-10-08-model-router-floor-1835.md:22,2026-10-09-model-router-tiers-1237.md:23), left unedited; re-run fails on ICON_MISSING, not a model-router regression. Unverified: whether--strictescalatesadvice[]. Links LRN-225, BDR-123.
BLK-035 — model-router: haiku session unrouted, table still on Haiku 4.5 [resolved]
- Friction: integration_alphalink 2026-10-25T16:22:53Z
model-router: claude-haiku-5-5 unknown to the models table; no switch./model haiku→ This project (BDR-126) would write stale id. - Cause: DEFAULT_CONFIG
haiku: 'claude-haiku-4-5-20251001'+windows200K entry; native alias moved toclaude-haiku-5-5(1M, effort low–max) silently. - Solution:
2c39524(feature/model-scope-dialog): haiku →claude-haiku-5-5,windows: {}; regression test + window test on explicit override. Negative control: revert → 20 tests red. - Residual: "haiku takes no effort" strip (effortWord, step plan, isHaiku sites, census
effort-routing.test.sh:170) still 4.5-era →mechanical(low) runs haiku at default medium. Follow-up /bugfix. Links LRN-230, BDR-126. - Status 2026-10-25: residual resolved
8e93507(bugfix/router-haiku-effort): no-effort guard scoped to Haiku 4.x, Haiku 5.x gets route effort; negative control (family prefix) → 6 tests red.
BLK-036 — bare /model picker writes tracked user settings for a per-project intent [resolved]
- Friction: user picked haiku in native picker in integration_alphalink, wanted that project only →
"model": "haiku"landed in tracked user settings.json (every project). Restored opus by hand; haiku pinned in alphalink.claude/settings.local.json. - Cause: BDR-126 dialog fires only on
/model <name>; spec said "no args → native picker untouched". Picker = real usage path. Main applied spec without flagging gap. - Next: /feat picker scope: pick model in picker, then ask project vs user scope. Check engine types for a settings-write intercept first; else mod must restore user settings (BDR-116 amendment, user call). Links BDR-126.
- Status 2026-10-25: resolved for the picker,
2202964(BDR-127: PreModelSwitch deny + deferred scope dialog, no user-settings write by the mod). Residual:/configModel row still native (sourcecommand).
BLK-037 — Same-model /model pick fires no PreModelSwitch: no scope question, project pin stays [resolved] (2026-10-29)
- Friction:
/modelpicker, pick = session's current model (Opus 5.5) → native "Set model toOpus 5.5and saved as your default… settings.local.json pinsFable 5.1— that applies on restart"; no scope question; project pin stays. - Real cause: engine fires no
PreModelSwitchwhen the pick equals the session model (nothing to switch) → handlePicker (BDR-127) never runs. Proof 2026-10-29: user picked Sonnet 5.5 (different) → "Model switch to Sonnet 5.5 was blocked by a PreModelSwitch hook". First guess (gateway idsanthropic/claude-opus-5.5) was a logged-out OpenRouter session, not the bug (3 lenses FATAL). - Solution: bare
/modelopens router dialog in command.run (BDR-132),657e5cb.
BLK-038 — memory.sh upgrade cements a v1 prose false-closed as an explicit resolved status line [open] (2026-10-30)
- Date: 2026-10-30
- Friction: phase 4a per-repo pass.
memory.sh upgradeon orbistep wrote- **Status (2026-10-30, upgrade)**: resolvedunder BLK-021 (status: open, fix not decided) and BLK-030 (status: code resolved (df5818c) · SMTP open (upstream OVH)), twice under BLK-008. Oracle silent: "open BLK unchanged (14)". - Real cause:
_mem_upgrade_repaircopies the v1 legacy reader's closed verdict, never asks where it came from. Legacy reader = last line matchingstatus|resolved|…|open, prose included ("another tab already resolved it"). v1 false-closed → explicit status line. Oracle shares that reader → blind (LRN-237). Duplicate:_mem_verdict_diffloops_mem_heading_ids, which lists### BLK-008 UPDATEsub-heading too. - Measured: 13 repos, 4 v1 closures without a labelled leading closed word: orbistep BLK-021 (really open), BLK-026 (prose addendum, really resolved), BLK-030 (mixed), bchanot-cv BLK-001 (strict already resolved, no effect). No lexical rule decides prose: BLK-021 and BLK-026 same shape, opposite truth.
- Solution: /bugfix bugfix/memory-upgrade-prose-closure: repair only from a
Status/Statutlabel whose leading word closes; else refuse file (rc 2), name ID + v1 line + remedymemory.sh status. Dedupe IDs. Committed repos audited clean; orbistep + zenquality redone after fix. - Status (2026-10-31): resolved
2dae528: repair writes only a single closed Status word, prose/mixed refused and named, diff captured before inserts, one upgrade line per entry; orbistep + zenquality redone (144505f, b7edb9c)
BLK-039 — Nested heredoc executed plan text: settings.json committed, user's stash popped [resolved] (2026-11-02)
- Friction: a Bash call holding a python heredoc that itself contained
<<'EOF'blocks: the innerEOFclosed the outer heredoc; the rest of the plan text ran as shell commands →git stash push settings.json(silently failed),git commitof settings.json WITH the UI writes (theme, switchModelsOnFlag), auto-pushed;git stash poppopped the USER's own stashwip: settings+routing dirty (user)(conflict, entry kept). - Real cause: heredoc nesting with the same delimiter;
rm -r-class rules did not matter, the damage was git state. - Solution: tree restored (
git reset -q, checkout of the three stash-touched files to HEAD, stash-brought spec removed), commit dropped withgit reset --soft HEAD~1+git push --force-with-lease=<branch>:<sha>(user approved), user's stash untouched. Rule: plan/doc text via Write/Edit, never heredoc-in-heredoc; nevergit stash popon a machine with the user's own stashes; settings.json only through the index recipe (LRN-253). - Status: resolved 2026-11-01.
BLK-040 — Permission rules and auto-mode classifier refuse destructive-shaped compound calls and dispatches [resolved] (2026-11-02)
- Friction: phase 5 execution: the permission rules refused a compound Bash call holding a
trapwithrm -f/rmdir(Task 1 canary), a 53-namerm … && rmdir && rm .active-profilechain, andrmdiralone; the auto-mode classifier refused the whole Task 2 dispatch because its brief described removing ~70 symlinks, moving impeccable and rewriting settings.json. - Real cause: destructive-shaped text in one call or one brief; the classifier judges the dispatch prompt, the rules judge each command.
- Solution: split build steps (implementer) from state steps (main loop, after the user's explicit approval); one
rmof literal names per call;mvto the scratch dir instead ofrmdir/rm -r; never retry a refused command through a wrapper. Cost: three extra user gates, no data loss. - Status: resolved 2026-11-02.
BLK-041 — gitleaks 8.16 pre-commit ignores .gitleaks.toml allowlists: secret-shaped fixtures built at runtime [resolved] (2026-11-04)
- Friction: 4b spec quoted the fake AWS key and test fixtures held
AKIA…-shaped literals; the pre-commit hook refused:gitleaksfound leaks although.gitleaks.toml[[allowlists]]named them (gitleaks 8.16). - Real cause: the installed gitleaks does not honour the allowlist block under the hook's invocation (rules compiled in; allowlist silently ignored).
- Solution: secret-shaped fixtures built at runtime by concatenation (
'AKIA' + 'I'.repeat(16),'eyJ' + 'a'.repeat(20) + …), expected strings stay literal (LRN-237); spec and NOISE.md quote shapes by reference, never a literal. - Status: resolved 2026-11-03.
BLK-042 — Package extracted into the root filesystem of a VM replaced usr-merge symlinks and overwrote system binaries [resolved] (2026-11-05)
- Friction: on a VM (vaas-cli ssh, no package manager), a Debian package was extracted with
dpkg -xinto the root filesystem; system binaries overwritten, usr-merge symlinks (bin, sbin, lib, lib64) replaced by real directories carrying the archive's paths. - Real cause: no rule or guard named package/archive extraction into system dirs; the ssh deny rule did not cover vaas-cli ssh; extraction improvised instead of telling the user there was no package manager.
- Solution:
hooks/extract-guard.sh(deny before run, quoted remote scripts re-scanned) + soft_deny line + doctrine bullet (list first, extract into a literal mktemp -d path, PATH/PYTHONPATH, no package manager → tell the user). See the extract-guard BDR. - Status: resolved 2026-11-05.
BLK-043 — detect_plan CLI fallback forks claude from SessionStart hook: recursive fork bomb, OOM, reboot [open] (2026-11-06)
- Friction:
make test suite=lib/tests/session-digest.test.sh(uncommitted SD13 cases) ate 14 GiB in 45 s, 2026-11-05 23:49; earlyoom killed valheim, node, mariadb, docker, audio; kernel OOM; machine rebooted 23:55; all sessions + RC lost. OOM dump: 126claude, 396bash, 124sh. - Real cause:
lib/detect-plugins.shdetect_planfalls back toclaude config get planTypewhen$HOME/.claude.jsonlacks plan markers. claude 2.1.318 has noconfigsubcommand → words read as prompt → full session → its SessionStart hook (hooks/session-start.sh:158) callsdetect_planagain, same HOME → unbounded recursion. SD13mkhomelinked~/.claude/*but not~/.claude.json. Prod survives only via internal flagstengu_cobalt_compass+tengu_harborin~/.claude.json; flag rename upstream → every session start recurses. - Solution: pending /bugfix (plan
.claude/tasks/plans/2026-11-06-detect-plan-fork-bomb-0030.md): CLI fallback dropped (default pro), hook recursion guard env marker, suite-wideclaudestub in PATH + regression cases. - Status: open 2026-11-06, fix in progress.
- Status (2026-11-06): resolved
49aa2ff(hotfix/detect-plan-fork-bomb): CLI fallback dropped, env guard SESSION_START_RUNNING, lib/tests/detect-plan.test.sh red on main lib, green after; merge pending user
BLK-044 — claude processes run with oom_score_adj -1000 of unknown origin: OOM killers spare a runaway claude [open] (2026-11-06)
- Friction: during the detect_plan fork bomb (2026-11-05 23:49), every
claude,bash,grepchild carriedoom_score_adj=-1000; earlyoom and kernel OOM could not kill the runaway, killed every other service instead (valheim, mariadb, docker, networkd, logind) until reboot. Live session 2026-11-06 still shows-1000. - Real cause: unknown. Not set by the repo (
lib/cc.sh, hooks: no OOMScoreAdjust). Suspects: inherited from launcher (dtach undersystemd-run --user --scope, sshd, or the RC/remote-control process). - Solution: none yet. Next: trace
/proc/<pid>/oom_score_adjup the parent chain of a live claude; then setOOMScoreAdjust(e.g. 500) on theccscope so a claude runaway dies first. - Status: open 2026-11-06.
BLK-045 — Hook-running test suites could reach real claude CLI: fail-open inline stubs, 3 suites unstubbed [resolved] (2026-11-06)
- Date: 2026-11-06
- Friction: hook-running test suites could still reach real
claudeCLI (BLK-043 family). Inline stubs in detect-plan + session-digest ranclaude probebefore checking stub won PATH; red control did not stop suite. graphify-gate, memory, push-guard ranhooks/session-start.shwith no stub; cc.test.sh shims same fail-open shape. - Real cause: stub pattern (LRN-263) copied inline, fail-open: failed write (no
set -e) or noexec TMPDIR (command -vskips non-exec) → real CLI; relative work dir passes same-cwd check, breaks after hook'scd. - Solution: shared
lib/tests/claude-stub.sh:stub_first_or_die(command -v == stub else exit 1),claude_stub_install(absolute dir viacd -P, every step|| exit 1, control from/,GIT_CEILING_DIRECTORIES),claude_stub_calls; 6 suites adopt, each ends zero-call check;lib/tests/claude-stub.test.shproves fail-closed (no-op chmod script + sentinel fake claude). Commitsdc5f127,7ca6b18on bugfix/safety-residuals. - Status: resolved
dc5f127
BLK-046 — Banner plugin rows showed user-scope state, not effective profile [resolved 556d0e6] (2026-11-10)
- Date: 2026-11-10
- Friction: session banner plugin rows showed user-scope state, not project's. dev project showed
ui-ux-pro-maxin🟢 ON; audit project hidpr-review-toolkit; /status read~/.claude/plugins/cacheas active. - Real cause:
detect_uiux_pro_maxtested plugin cache only (installed = on); ✅ row grepped"<id>": truein user~/.claude/settings.json. PROFILE_PLAIN (profile.sh current --plain) already held effective state, unused there. Found by code-clean 2026-11-09 (G1, G4). - Solution:
list_on_pluginsin lib/detect-plugins.sh: profileplugin:<id>=onfor managed ids, user-scope true for rest, awk set difference,return 0. ✅ row + detect_uiux_pro_max (cache AND enabled) + status-reporter read it; plugin-advisor INPUT names PROFILE. Test lib/tests/session-banner.test.sh SB1-SB8. Commit556d0e6.
BLK-047 — Passive-cost constants stale in banner and advisor, budget row on wrong denominator [resolved 1971b8d] (2026-11-10)
- Date: 2026-11-10
- Friction: passive-cost figures disagreed: banner
_plugin_costs(gstack 2750, ui-ux-pro-max 400, context7 200, graphify 300) and plugin-advisor~Ntvs doctor.sh (ui-ux 670 only). Banner 💰 row divided by per-plan "budget" (Pro 11000, Max 20000). - Real cause: hand-copied constants. 2026-09-28 skill-catalog prune re-measured doctor (ui-ux 400 → 670, gstack/context7/graphify dropped: skills already in catalog) but missed banner + advisor citers (BDR-100 class). Measured 2026-11-10: gstack 3 packs ~445t (~196/120/129), ui-ux ~666t, context7 = CLI, find-docs skill always loads.
- Solution: user split. Bugfix removed constants, 💰 row, budget block, dead
detect_plan(BLK-043 source); advisor + status-reporter point tomake doctor; detect-plan.test.sh → hook-recursion-guard.test.sh; SB9/SB10. Commit1971b8d. Measured-cost API = TODO feature (spec input: two challenge rounds in plan 2026-11-10-passive-cost-source-1330).
BLK-048 — Handover STEP 9 parsed blocker status by hand, client section 5 could list closed or drop open [resolved 93a8e19] (2026-11-11)
- Friction: handover-doc-writer STEP 9 said "parse manually", blocker status read from prose of cwd-relative
.claude/memory. Client §5 could list closed blocker or drop open one (BLK-032..034 class). - Real cause: agent prompt bypassed shared readers.
reconcile_blk_opennot reusable as is: v1 branch closes on substring "resolved" (dropsunresolved); v1 non-word lines (closed, prose) leak as open;###entries invisible to enumerator. - Solution: new
reconcile_blk_classify(lib/reconcile.sh): strict word v2,_mem_v1_wordv1, never## Index; closed omitted; empty/prose/mixed/closed/###= unreadable. STEP 9 rooted on PACKAGE root,no-file/reader-unavailablelines. Fenced SYNTH REPORT, mandatoryMEMORY:line; orchestrator retries when missing or contradicted by existing blockers.md, relays unreadable IDs +memory.sh statusremedy in 9.7. Test handover-memory-contract.test.sh HM1-HM3. Commit93a8e19. Real data: game repo 14 unreadable (v1status:lines left after upgrade). Follow-ups G6-G9 in BUGS-FOUND.