@event4u/agent-config 10.4.0 → 12.0.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-5fXOHoVh.js"></script>
+      <script type="module" crossorigin src="/assets/index-B0aMJnuz.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/MIGRATION.md

@@ -16,6 +16,7 @@ releaser here on every `release:major`.
 
 | Surface | Committed | Deprecation notice due | Removal due | Reversal condition |
 |---|---|---|---|---|
+| Free-text `compatibility` skill-frontmatter field (`src/scripts/schemas/skill.schema.json`) | 2026-08-14 | shipped 2026-08-14 — `deprecated: true` + superseded-by note in the schema; `harness_compat` lands beside it, additively | next major after the notice — **not pinned here** (removal date is maintainer-owned, same stance as the manifest `tier` entry, whose `sunset` shipped `null`) | The public Agent-Skills spec makes `compatibility` load-bearing for cross-host portability, or an external consumer is found reading it. `harness_compat` is package-local; `compatibility` mirrors the public spec, so keeping the mirror stays cheaply reversible. Superseded by `harness_compat` (class) + `runtime_requires` (probeable detail); both users (`docx-authoring`, `pdf-tools`) already carry both fields, so nothing breaks on removal day. |
 | `code_graph` native code-graph engine (`code_graph.enabled`, the `code-intelligence` skill's native arm, `code_graph_nudge_hook`) | 2026-07-28 | next major after 9.x | the major after that | A consumer case the graph answers and disciplined grep cannot. Measured null: recall 0.365 vs grep 0.797 (`docs/CLAIMS.md` `code-graph-retrieval-null`). Until then `enabled: false` is permanent. **Its parser pair (`web-tree-sitter@0.24.7` / `tree-sitter-wasms@0.1.13`, ~51 MB unpacked) moved from `dependencies` to `devDependencies` ahead of the schedule, so consumers no longer install it — the runtime paths (CLI leaf, nudge hook, skill, rule) stay registered until the removal date above, but re-enabling now also means installing that ABI-locked pair yourself.** |
 
 **Adding a row:** any change that ships a capability as default-off-pending-removal,

package/docs/contracts/settings-classes.md

@@ -39,9 +39,10 @@ surface without a consumer.
 **It governs writes, not reads.** Every class is readable by everything. A C
 class does not hide a value; it refuses to let a non-human change it.
 
-**It governs writes, not asks.** Four settings ship an `ask` value in their own
-enum (`tokens.rich_skills`, `subagents.adversarial_council`, `worktrees.mode`,
-`decision_engine.on_block`).
+**It governs writes, not asks.** Three settings ship an `ask` value in their own
+enum (`tokens.rich_skills`, `subagents.adversarial_council`,
+`decision_engine.on_block`). It was four until ADR-229 deleted
+`worktrees.mode`.
 Those are C-class here, and that is not a contradiction: the class says who may
 *persist* a new value; the `ask` value says what happens *at runtime* when the
 setting is already set to `ask`. A C-class key set to `ask` still produces a
@@ -141,6 +142,47 @@ larger set; it is the set that passes both halves.
 | `personal.canary_name` | un-inferrable, and answering arms the session-degradation canary; one keypress to accept the prefill | `""` (canary dark) |
 | `memory.learn_on_session_end` | it turns on automatic memory writes at the end of every session — a standing write the user should authorise | `false` |
 
+## Class B is a persistence property, not an enforcement claim
+
+Recorded 2026-08-13, from `road-to-zero-settings` step 3.2 — the step that asked
+each class-B key *"does the action need authorising at all?"*. Two of the three
+answers turned out not to be about the keys.
+
+```
+CLASS B SAYS: MAY BE ASKED ONCE, THEN PERSISTED. IT SAYS NOTHING ABOUT
+WHETHER ANYTHING CAN REFUSE THE ACTION. THE DISPOSITION SAYS THAT.
+A `consent` KEY NEEDS A MECHANISM THAT CAN WITHHOLD, OR AN EXPLICIT
+PROSE-ONLY LABEL. AN `un-inferrable` KEY NEEDS ONLY PERSISTENCE.
+```
+
+The two axes are independent, and reading class B as implying an enforcement
+obligation is what made two non-problems look like problems:
+
+- **`personal.canary_name`** authorises nothing — it holds a nickname used as a
+  liveness marker. It is class B because it cannot be inferred and is worth
+  keeping once answered, and its disposition (`un-inferrable`) already says so.
+  There is no gate to build here and never was.
+- **`personal.open_edited_files`** is a genuine `consent` key with **no mechanism
+  that can refuse the action** — its only reader is prose in
+  `src/skills/file-editor/SKILL.md`. The suite's standing rule is *never claim
+  enforcement you do not have*, and the discharge of that rule is to **declare
+  the limit**, not to delete the user's choice: it is carried as an explicitly
+  prose-only preference. An unenforceable flag that says it is unenforceable is
+  honest; one that presents as a gate is not.
+- **`memory.learn_on_session_end`** is what a consent key looks like when the
+  mechanism exists: `src/scripts/memory_learn_hook.ts` reads it and can withhold
+  the write, and the default is conservative.
+
+Splitting class B into `B-consent` and `B-config` was considered and **not
+taken** — it would churn a contract, a linter and every consumer's mental model
+to express what this paragraph expresses. What the split would have bought is
+the obligation stated above; stating it directly costs one section.
+
+**Consequence for anyone adding a class-B key:** the § B eligibility invariant
+still binds in full. This section adds one question on top of it — *if the
+disposition is `consent`, what can refuse the action?* An answer of "nothing"
+is allowed, and must then be written down as such.
+
 ## The one exception — `emergency.orchestration_halt`
 
 The always-on-orchestration doctrine (subagents, council, team) deletes every
@@ -189,12 +231,15 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 26 |
 | B — consent | 3 |
-| C — guarded | 106 |
-| **Total** | **135** |
+| C — guarded | 105 |
+| **Total** | **134** |
 
 The total was 140 until 2026-08-12, when five of the six keys no code path read were
 deleted, minus the one held open (§ The six unread keys, below): one A
-(`telegraph.speak_scope`) and four C.
+(`telegraph.speak_scope`) and four C. It dropped to 134 on 2026-08-13 when
+ADR-229 deleted `worktrees.mode` — a fifth C, and the first deletion in this
+series of a key that WAS read: the doctrine there is that the decision was never
+the agent's to make, not that nothing consulted it.
 
 The total is every leaf in the template, where *leaf* means anything that is not
 a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
@@ -244,9 +289,9 @@ the template, which is the drift this contract exists to prevent.
 |---|---|
 | derivable | 83 |
 | un-inferrable | 9 |
-| consent | 38 |
+| consent | 37 |
 | policy | 5 |
-| **Total** | **135** |
+| **Total** | **134** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -421,7 +466,6 @@ Rows follow template order, so a diff against the template reads straight down.
 | `subagents.model_ceiling` | C | `""` | session-wide subagent model cap (exported as `CLAUDE_CODE_SUBAGENT_MODEL` by suite-owned CLI spawn wrappers), which is spend and quality | consent |
 | `subagents.max_parallel` | C | `3` | parallelism cap, and therefore a spend rate | consent |
 | `subagents.adversarial_council` | C | `"off"` | governs a paid verification step | consent |
-| `worktrees.mode` | C | `ask` | standing permission for autonomous worktree creation | consent |
 | `ai_team.model` | C | `auto` | names an external model | un-inferrable |
 | `ai_team.allow_delegate` | C | `false` | grants an external tool write access to the repository | consent |
 | `ai_team.max_calls_per_day` | C | `50` | quota cap on a shared budget | consent |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "10.4.0",
+    "version": "12.0.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -133,6 +133,40 @@ projection:
 # (vendor-granular unknown_defaults in src/config/host-capabilities.yml).
 discipline_profile: __DISCIPLINE_PROFILE__
 
+# OPT-IN PRESET — the measured-lift configuration, shown but NOT shipped.
+#
+# The evidence above says `essential` carries the significant discipline lift
+# (+0.458, p=0.0135) while `full`'s residual over it is not significant
+# (p=0.37). That reads like an argument to flip the shipped default. It is not,
+# for two independent reasons, and both are worth stating where the key lives
+# rather than in a roadmap nobody reads at install time.
+#
+#   1. This key family is marked "do not set this from automation". That reads
+#      as ABSOLUTE — it forbids an automated CHOICE of default for the family,
+#      not merely a script rewriting your file. No measurement, however clean,
+#      licenses an agent to flip it on your behalf.
+#   2. The flip was pre-registered against a fresh-install census of
+#      <= 30k tokens of always-on rule prose. Measured at audit time: ~163k as
+#      loaded, i.e. 5.4x the target. The criterion fails on its own terms
+#      regardless of point 1.
+#
+# So the better-evidenced value is carried here as a visible option you may
+# uncomment, with its cost stated inline. Uncomment the line below to replace
+# the resolved value above:
+#
+#   discipline_profile: essential      # ~3.3x kernel tokens (vs ~11.7x for full)
+#
+# Read the two factors as what they are: multiples of the kernel-only baseline
+# from the cost-factor sweep, NOT the fresh-install census. They answer "what
+# does this tier cost relative to `off`", never "does this tier reach 30k" —
+# nothing has measured the latter for `essential`, and this comment does not
+# claim it does.
+#
+# Recorded 2026-08-14 on an outside opinion (1 seat, 2 rounds; the second seat
+# failed to start, so a single-model judgement on its checkable merit and NOT a
+# convergence). It rejected both the flip and the do-nothing, and proposed this
+# third route: you see the option, nothing automated chose for you.
+
 # --- Cost profile (legacy knob — superseded by discipline_profile above) ---
 #
 # Master switch that controls which rule tiers load each session.
@@ -815,24 +849,21 @@ subagents:
 
 # --- Git worktrees ---
 #
-# Controls how the `using-git-worktrees` skill and `subagent-orchestration`
-# mode 6 (`do-in-worktrees`) behave. Mechanical layer on top of the
-# existing `scope-control` permission gate — narrows, never widens.
-worktrees:
-  # off | on | ask  (default: ask)
-  #
-  # ask = status quo. Skill asks before creating any worktree; mode 6 is
-  #       selectable when the chain shape warrants it. Matches the
-  #       behaviour required by `scope-control` and `autonomous-execution`.
-  # off = no autonomous worktree creation. Skill refuses; mode 6 falls
-  #       back to mode 3 (do-in-steps). Explicit user request in the
-  #       chat ("do this in a worktree", "use mode 6") overrides for
-  #       that single task — the setting suppresses *unprompted* usage,
-  #       not the tool itself.
-  # on  = standing permission. Skill skips the per-creation permission
-  #       ask; mode 6 may be picked without prompting. Iron-Law gates
-  #       (ignore-check, clean baseline) still apply.
-  mode: ask
+# There is no setting. Worktree creation is INSTRUCTION-ONLY (ADR-229):
+# `using-git-worktrees` and `subagent-orchestration` mode 6 (`do-in-worktrees`)
+# create a worktree ONLY when the user asks for one in the chat ("do this in a
+# worktree", "use mode 6"). Unprompted, mode 6 is not selectable and the chain
+# falls back to mode 3 (`do-in-steps`).
+#
+# `worktrees.mode` was DELETED. It offered `ask`/`on`/`off` over a decision that
+# was never the agent's to make: `ask` spent a round trip on every spawn, `on`
+# let the agent start parallel work on its own, and `off` was the behaviour
+# everyone actually wanted — so the setting's only real value was hardcoded and
+# the other two values removed. A leftover key from an older install is ignored
+# with one deprecation line (see `REMOVED_KEYS` in `_lib/agent_settings.ts`).
+#
+# The Iron-Law gates on creation (ignore-safety check, clean baseline) are
+# unchanged and still run on every explicitly-requested worktree.
 
 # --- AI Council (external second-opinion network) ---
 #

package/src/config/gate-coverage.yml

@@ -335,9 +335,19 @@ gates:
       Why 340 and not 360, the measured value: gate-authoring.md § registration
       requires a floor BELOW the live count, because a floor pinned at today's
       number reds on the very change that legitimately retires one unit. 340
-      leaves ~20 units (~5.5%) of headroom while still catching the collapse this
-      floor exists for — a re-broken extractor would drop the count by 164, not
-      by 20.
+      leaves ~20 units (~5.5%) of headroom.
+      What this floor can and cannot catch, corrected after the R2 review caught
+      the first version arguing from a break that cannot fire it. The extraction
+      bug INFLATED the count — phantom gate names entering the CI set — so a
+      re-break raises the population to roughly 527 and a min_scanned floor never
+      triggers on a rise. The floor guards the opposite direction: an extractor
+      that stops finding taskfiles or workflows at all, a parse error zeroing one
+      side, a scan root that moves. Those are collapses of 100+ units and 340
+      catches every one of them. The realistic PARTIAL break — one taskfile
+      failing to parse, say ~14 units — passes 340 and would have failed 380,
+      which is the honest cost of the headroom and is accepted here rather than
+      hidden: a floor tight enough to catch that is also tight enough to red on
+      the next legitimate retirement.
 
   - id: check_site_links
     argv: []

package/src/config/gate-violation-baselines.json

@@ -4,13 +4,13 @@
     "ci-parity:local-only": {
       "count": 166,
       "landed": "2026-08-13",
-      "note": "Gates that `task ci` runs and no workflow does — the direction this manifest's own header calls the one that let real defects merge (16 stale index rows reached the trunk behind a local-only check-index). Revealed, not created, by repairing the checker's extraction: check_ci_local_parity built its CI-side set by regexing RAW workflow text for `task <name>` and expanding each closure, comments included. Several workflow comments contain the literal string `task ci` while stating that no workflow invokes it, so `ci` was read as an invocation and its full 247-gate closure entered the 'runs in CI' set. The count was therefore 0 BY CONSTRUCTION, and the prose documenting the gap was what suppressed it. Measured at the repair: CI-side 273 → 106, undeclared_local_only 0 → 167 of 247 local gates (68%). Baselined rather than hard-failed because 167 findings nobody can clear in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before; shrink-only keeps the property that matters, namely that a NEW gate registered in `task ci` with no workflow reds immediately. Lowering happens by wiring gates into workflows or declaring them under `local_only:` with a reason. Note the punchline, because it bounds the risk of this entry: check_ci_local_parity ITSELF runs in no workflow, so it is its own finding and this ratchet has no remote reach either — clearing the backlog is what gives it teeth. DRAINED BY ONE, 2026-08-13: check_ci_local_parity itself was wired into consistency.yml, so it left the set it exists to report. That is the whole shape of a legitimate drain here — the gate stops being local-only because a workflow now runs it, not because the declaration list grew. The floor in gate-coverage.yml moved in the same change and for the same reason: wiring two gates raised the parsed population 357 -> 359.",
+      "note": "Gates that `task ci` runs and no workflow does — the direction this manifest's own header calls the one that let real defects merge (16 stale index rows reached the trunk behind a local-only check-index). Revealed, not created, by repairing the checker's extraction: check_ci_local_parity built its CI-side set by regexing RAW workflow text for `task <name>` and expanding each closure, comments included. Several workflow comments contain the literal string `task ci` while stating that no workflow invokes it, so `ci` was read as an invocation and its full 247-gate closure entered the 'runs in CI' set. The count was therefore 0 BY CONSTRUCTION, and the prose documenting the gap was what suppressed it. Measured at the repair: CI-side 273 → 106, undeclared_local_only 0 → 167 of 247 local gates (68%). Baselined rather than hard-failed because 167 findings nobody can clear in the change that reveals them is the gate-that-lands-as-N-instant-blockers failure this repository has refused before; shrink-only keeps the property that matters, namely that a NEW gate registered in `task ci` with no workflow reds immediately. Lowering happens by wiring gates into workflows or declaring them under `local_only:` with a reason. Note the punchline, because it bounds the risk of this entry: check_ci_local_parity ITSELF runs in no workflow, so it is its own finding and this ratchet has no remote reach either — clearing the backlog is what gives it teeth. DRAINED BY ONE, 2026-08-13: check_ci_local_parity itself was wired into consistency.yml, so it left the set it exists to report. That is the whole shape of a legitimate drain here — the gate stops being local-only because a workflow now runs it, not because the declaration list grew. The floor in gate-coverage.yml moved in the same change and for the same reason: wiring two gates raised the parsed population 357 -> 360 (109 CI + 251 local). The intermediate 359 was the reading after the CI-side wiring alone and before check_gate_coverage joined the local `ci` chain; it was committed here by mistake and is corrected rather than left as a second number for the same measurement.",
       "falsifier": "./scripts-run src/scripts/check_ci_local_parity"
     },
     "check_no_new_legacy_path:hardcoded-scan-roots": {
-      "count": 48,
-      "landed": "2026-08-09",
-      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` — a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts → 147 string-literal lines → 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant — gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 — a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56→51 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md). Lowered 51→49 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver — two gates that had been reading the retired container and scoring 0 of 288 skills. Lowered 49→48 by road-to-rule-delivery-integrity P2.2: score_skill_selection was repointed at the live skills tree via the shared resolver. It is the same shape as the two gates lowered before it — a scorer reading the retired container and scoring 0 of 288 skills — and here the consequence was sharper than a dead gate: the roadmap's pre-registered selection-accuracy criteria would have been compared against a baseline of silent zeros."
+      "count": 47,
+      "landed": "2026-08-13",
+      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` — a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts → 147 string-literal lines → 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant — gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 — a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56→51 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md). Lowered 51→49 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver — two gates that had been reading the retired container and scoring 0 of 288 skills. Lowered 49→48 by road-to-rule-delivery-integrity P2.2: score_skill_selection was repointed at the live skills tree via the shared resolver. It is the same shape as the two gates lowered before it — a scorer reading the retired container and scoring 0 of 288 skills — and here the consequence was sharper than a dead gate: the roadmap's pre-registered selection-accuracy criteria would have been compared against a baseline of silent zeros. Lowered 48→47 on 2026-08-13, and this one is a catch-up rather than a repair: the pass reported 47 against a baseline of 48, so a gain had already landed without the ratchet following it. Attributed to 455160160 (fix(evals): resolve the eval orchestrator against the live skills tree), the most recent repair in this branch's base that removes a path-constructing line — SKILLS_ROOT repointed through _lib/agent_src.ts::SRC_SKILLS(). A loose ratchet is not harmless: it silently permits one new violation to be added back without any gate noticing, which is the shape this entry exists to prevent."
     },
     "audit_user_type_axis": {
       "count": 1,

package/src/config/pack-size-budget.json

@@ -20,9 +20,10 @@
         "rationale": "Measured 2026-07-31: the largest non-excepted skill is corpus-grounding at 2.33%, so a 5% cap is green with better than 2x headroom and red for any skill that doubles. It is a falsifiable gate, not a ritual one.",
         "exceptions": {
             "design-intelligence": {
-                "max_pct": 23.0,
+                "max_pct": 23.5,
                 "measured_pct": 22.63,
-                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit."
+                "reason": "771 KB of BM25 corpus (27 CSVs + 16 design-language prose specs + manifest.json) consumed at runtime by corpus-grounding's retriever, and referenced by 6 further skills. Moving it behind a lazy fetch would add a network dependency to a skill that works offline today — the same trade-off ADR-061 §8 already REJECTED for a 745 KB font index. The exception is visible debt, not an endorsement: raising max_pct requires a reason in the same commit.",
+                "baseline_note_2026_08_13": "23.0 → 23.5 on 2026-08-13, and the reason belongs in this file per the sentence above. WHAT WAS ADOPTED: data/motion.csv, 10.5 KB, 16 rows. WHY IT IS NOT DISCRETIONARY: the roadmap's three design dials were all in its original scope, and two of the three (variance, density) were already portable — variance's keywords resolve against the local styles.csv (2/3/3 hits) and density is three pure range maps. The motion dial is not: upstream filters its corpus rows by `Intensity Tier == <dial tier>`, and that column exists only in motion.csv, so shipping the dial without the file means shipping a flag that silently does nothing. Two of three dials plus an inert third is a worse surface than three working ones. WHAT WAS DECLINED IN THE SAME PASS, so this is not a ratchet slipping: google-fonts.csv (743 KB — ADR-061 §8 rejects it by name and by size; the 2026-06-16 amendment authorises a slim top-N slice from a different mirror, not this file), typography.csv (our curated font-pairings-reference.csv is the ADR's working substitution), six desktop-UI stacks outside frontend-design's scope, and eleven content-drifted files nobody has reviewed. The base pin in ATTRIBUTION.md is deliberately NOT bumped for the same reason. HONEST LIMIT ON THE NUMBER: 22.63 is the committed measurement, not a fresh one — check_pack_size cannot be re-measured from a built worktree (it reads 9.096 against the 7.8 packed cap before any change, the trap the packed_size_mb note above documents), so the post-adoption share is arithmetic (~22.87 %) and the new cap carries ~0.6 pp over it rather than clearing by a hair. DECIDED BY: AI council, 2026-08-13, on a maintainer delegation — and honestly, by ONE member over two rounds, not by convergence: the second seat returned exit_1 (the codex CLI refuses a git worktree as an untrusted directory). Recorded as a single-member review in agents/evidence/analysis/design-system-blockers-council.md."
             }
         }
     }

package/src/scripts/_dispatch.bash

@@ -447,6 +447,9 @@ require_tsx() {
 # command surface (`sync`, `doctor`, `validate`, `upgrade`, …) and its
 # basenames are unique, so the mapping is collision-free. Other exec_ts
 # callers (resolve_script results, the work engine, …) are unaffected.
+#
+# In a DEV tree the bundle is also suppressed when any `src/**/*.ts` is newer
+# than it — see cli_delegate_bundle_is_stale.
 cli_delegate_bundle() {
   local ts_abs="$1"
   case "$ts_abs" in
@@ -457,18 +460,52 @@ cli_delegate_bundle() {
   name="$(basename "${ts_abs%.ts}")"
   local bundle="$PACKAGE_ROOT/dist/cli-delegate/$name.js"
   if [[ -f "$bundle" ]] && command -v node >/dev/null 2>&1; then
+    cli_delegate_bundle_is_stale "$bundle" && return 0
     printf '%s' "$bundle"
   fi
 }
 
+# Is a `dist/cli-delegate/` bundle older than the sources it was built from?
+#
+# Only asked in a DEV tree — `$PACKAGE_ROOT/src` exists there and nowhere else.
+# A consumer install ships no `src/`, so it returns "not stale" without a single
+# stat and the ADR-204 fast path is untouched.
+#
+# The scan covers `src` WHOLE, not `src/scripts`: `_cli/*.ts` imports reach into
+# `src/shared`, `src/install`, `src/server`, `src/agent`, `src/config` and
+# `src/agent-src`, and the defect this guard exists for lived two hops away in
+# `src/scripts/_lib/cc_transcript.ts` — a scan narrowed to the entry point's own
+# directory would have missed it.
+#
+# Cost, measured 2026-08-14 on the local tree (1075 `.ts` files): 78 ms when the
+# bundle is current (the full walk) and ~12 ms when it is not (`-quit` exits at
+# the first newer file). The bundle saves ~290 ms against the tsx path, so the
+# worst case still leaves most of that — and buys the guarantee that a dev-tree
+# edit is never silently ignored in favour of a stale compile.
+cli_delegate_bundle_is_stale() {
+  local bundle="$1"
+  [[ -d "$PACKAGE_ROOT/src" ]] || return 1
+  local newer
+  newer="$(find "$PACKAGE_ROOT/src" -name '*.ts' -newer "$bundle" -print -quit 2>/dev/null)"
+  [[ -n "$newer" ]]
+}
+
 # Run an absolute script path. The argument is an absolute path that may carry
 # a `.py` (legacy) or `.ts` extension; we resolve the `.ts` twin.
 #
-# A precompiled `dist/cli-delegate/` bundle wins when present — the consumer
-# tree ships no tsx (see require_tsx), and the bundle is also ~5.7x faster
-# than the npx path it replaces (p50 56-71 ms vs 346-392 ms, measured
-# 2026-07-31; see docs/decisions/ADR-204). The tsx path stays as the dev-tree
-# route and as the fallback for every non-`_cli` caller.
+# A precompiled `dist/cli-delegate/` bundle wins when present AND not stale —
+# the consumer tree ships no tsx (see require_tsx), and the bundle is also
+# ~5.7x faster than the npx path it replaces (p50 56-71 ms vs 346-392 ms,
+# measured 2026-07-31; see docs/decisions/ADR-204). The tsx path stays as the
+# dev-tree route and as the fallback for every non-`_cli` caller.
+#
+# "Not stale" is the load-bearing qualifier, and it was added because the
+# unqualified version shipped a real failure: a dev-tree `dist/cli-delegate/`
+# built before a `projectStoreSlug` fix kept running the OLD slug, so
+# `agent-config handoff --list` reported "no recent sessions" in any worktree
+# whose path carried a `+`, while the fixed source right next to it listed ten.
+# A compiled copy that silently outranks the source it was built from turns
+# every edit into a coin flip — see cli_delegate_bundle_is_stale.
 #
 # Argv/stdin/stdout/stderr/exit-code pass through unchanged in both routes —
 # mirrors src/scripts/run.ts resolution.

package/src/scripts/_lib/agent_settings.ts

@@ -922,6 +922,13 @@ export function load_agent_settings(
  * whether the repair is to build its missing reader or to delete a promise a
  * Hard Floor can never honour. See `settings-classes.md` § The six unread keys.
  *
+ * `worktrees.mode` (2026-08-13, ADR-229) is a third doctrine again: not
+ * always-on, not unread. It WAS read, and the reader honoured all three values —
+ * the deletion says the decision was never the agent's to make. `ask` bought a
+ * round trip per spawn, `on` let the agent start parallel work unprompted, and
+ * `off` described the wanted behaviour, so `off` became the hardcoded rule and
+ * the switch went. What decides instead is the user's own sentence in the chat.
+ *
  * Every reason string must name what decides INSTEAD, never just "removed".
  * Exported so `lint_settings_classes` can check the deletion side of the
  * surface: a reason that names no replacement, or an entry whose key is live in
@@ -942,6 +949,7 @@ export const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
     ['chat_history.on_overflow', 'the overflow mode comes from the rotate command --mode argv'],
     ['quality.wait_for_remote_ci', 'whether to poll follows from the push plus a detectable remote pipeline'],
     ['legal_review_prep.consented_at', 'the provenance sidecar settings:set writes and consentVerdict reads'],
+    ['worktrees.mode', 'the user asking for a worktree in the chat; creation is instruction-only and hardcoded'],
 ]);
 
 /** Keys already warned about in THIS process — the "once per run" dedupe. */

package/src/scripts/audit_command_surface.ts

@@ -57,9 +57,14 @@ const SIZE_BUDGETS: Record<string, number> = {
     platform: 10,
 };
 // ADR-092: `visibility:` is the named source of truth (visible / advanced /
-// internal); the integer `tier:` is a back-compat alias. A command counts
-// toward the per-pack budget when it is surfaced — visibility in {visible,
-// advanced} (or, when only the alias is present, tier in {0,1}). `internal`
+// internal). The integer `tier:` alias was REMOVED from live command files in
+// road-to-tier-removal Phase 4, but this file still parses it on purpose: the
+// surface-growth check reads PAST git revisions (`_tier_at_ref`), and pre-ADR-092
+// blobs carry only the alias. The live-file tier read below is therefore a
+// harmless residue on current files and the correct read on historical ones.
+// A command counts toward the per-pack budget when it is surfaced — visibility
+// in {visible, advanced} (or, when only the alias is present, tier in {0,1}).
+// `internal`
 // (or absent → defaults to internal) is uncapped.
 const VISIBLE_TIERS: ReadonlySet<number> = new Set([0, 1]);
 const VISIBLE_VISIBILITIES: ReadonlySet<string> = new Set(['visible', 'advanced']);
@@ -622,17 +627,17 @@ export function render_md(commands: Command[], pairs: OverlapPair[]): string {
             '[`command-surface-synthesis.md`](command-surface-synthesis.md). Every command ' +
             "in this table maps to `keep` unless named in that file's tables.",
         '',
-        '| Name | Path | Tier | Cluster | Aliases | Lines | Commits | Age (d) | Bucket |',
+        '| Name | Path | Visibility | Cluster | Aliases | Lines | Commits | Age (d) | Bucket |',
         '|---|---|---:|---|---|---:|---:|---:|---|',
     );
     const sortedCmds = _stableSortStr(commands, (c) => c.relpath);
     for (const c of sortedCmds) {
         const aliases = c.aliases.length ? c.aliases.join(', ') : '—';
-        const tier = c.tier === null ? '—' : String(c.tier);
+        const visibility = c.visibility === null ? '—' : c.visibility;
         const cluster = c.cluster || '—';
         const age = c.days_since_first_commit === null ? '—' : String(c.days_since_first_commit);
         lines.push(
-            `| \`${c.name}\` | \`${c.relpath}\` | ${tier} | ${cluster} | ${aliases} | ` +
+            `| \`${c.name}\` | \`${c.relpath}\` | ${visibility} | ${cluster} | ${aliases} | ` +
                 `${c.line_count} | ${c.commit_count} | ${age} | |`,
         );
     }
@@ -738,7 +743,7 @@ function _is_visible(c: Command): boolean {
 
 interface VisibleCommand {
     name: string;
-    tier: number | null;
+    visibility: string | null;
     cluster: string;
     citations_docs: number;
     commit_count: number;
@@ -797,7 +802,7 @@ export function build_budget_audit(
         if (over) {
             const vis = visible.map((c) => ({
                 name: c.name,
-                tier: c.tier,
+                visibility: c.visibility,
                 cluster: c.cluster,
                 citations_docs: citation_count(c.name),
                 commit_count: c.commit_count,
@@ -832,8 +837,9 @@ export function render_budget_md(audit: BudgetAudit): string {
     L.push('# Command budget audit (6.0.0-B Phase 2 Step 4)\n');
     L.push(
         '> Per-pack VISIBLE-command counts vs. the `size_class` budget ' +
-            '(capability-packs.md). `visible` = tier ∈ {0,1}; tier 2 / absent = ' +
-            'internal (uncapped). Citations = docs/ files referencing `/<name>`.\n' +
+            '(capability-packs.md). `visible` = visibility ∈ {visible, advanced}; ' +
+            '`internal` / absent = uncapped. Citations = docs/ files referencing ' +
+            '`/<name>`.\n' +
             '>\n' +
             '> **Signal note:** docs-citations is the load-bearing signal (rank ' +
             'candidates low→high). The git commit/idle columns are low-variance on ' +
@@ -862,11 +868,11 @@ export function render_budget_md(audit: BudgetAudit): string {
                 `budget ${p.budget} (${p.size_class}), over by ${p.over_by}\n`,
         );
         L.push('Decide per command: keep-visible · set `internal` · relocate-to-pack-X.\n');
-        L.push('| Command | tier | cluster | docs citations | commits | days idle |');
-        L.push('|---|--:|---|--:|--:|--:|');
+        L.push('| Command | visibility | cluster | docs citations | commits | days idle |');
+        L.push('|---|---|---|--:|--:|--:|');
         for (const c of p.visible_commands ?? []) {
             L.push(
-                `| \`${c.name}\` | ${c.tier} | ${c.cluster || '—'} | ` +
+                `| \`${c.name}\` | ${c.visibility ?? '—'} | ${c.cluster || '—'} | ` +
                     `${c.citations_docs} | ${c.commit_count} | ` +
                     `${c.days_since_modified !== null ? c.days_since_modified : '—'} |`,
             );
@@ -1050,8 +1056,8 @@ export function check_new_budget(baseline: string, quiet: boolean): number {
             );
         }
         process.stdout.write(
-            '\nResolve by one of: set the command to `tier: 2` (internal, ' +
-                'uncapped) · merge into a sibling cluster · relocate to a pack ' +
+            '\nResolve by one of: set the command to `visibility: internal` ' +
+                '(uncapped) · merge into a sibling cluster · relocate to a pack ' +
                 'with budget headroom · file a budget-exemption ADR ' +
                 '(docs/contracts/capability-packs.md § Budget exemption process).\n',
         );

package/src/scripts/build_catalog_index.ts

@@ -138,7 +138,7 @@ export function buildEntries(): CatalogIndexEntry[] {
             cls: 'command',
             name,
             description: _str(fm['description']) || _str(fm['intent']),
-            tags: [_str(fm['pack']), _str(fm['tier']), _str(fm['visibility'])].filter((s) => s.length > 0),
+            tags: [_str(fm['pack']), _str(fm['visibility'])].filter((s) => s.length > 0),
             path: _rel(abs),
         });
     }

package/src/scripts/build_discovery_manifest.ts

@@ -657,26 +657,13 @@ function _build(strict: boolean): [JsonObject, JsonObject[]] {
         // 6.0.0-C: surface command routing metadata. Does not affect the
         // per-file checksum (computed over frontmatter, below).
         if (category === 'command' && fm !== null && _isObject(fm)) {
-            if (fm['tier'] !== undefined && fm['tier'] !== null) {
-                entry['tier'] = fm['tier'];
-            }
-            // ADR-090: `visibility:` is the named source of truth; the integer
-            // `tier:` is a back-compat alias. Dual-emit BOTH into the manifest
-            // (a published data contract) during the deprecation window so
-            // external consumers reading the integer key keep working. The
-            // top-level `deprecations` block (ADR-092 / road-to-tier-removal)
-            // announces the `tier` deprecation; removal is Phase 4. Prefer the
-            // explicit field; derive from tier when absent.
-            const _tierToVis: Record<number, string> = { 0: 'visible', 1: 'advanced', 2: 'internal' };
-            let _vis: Json = fm['visibility'];
-            if (
-                (_vis === undefined || _vis === null) &&
-                fm['tier'] !== undefined &&
-                fm['tier'] !== null
-            ) {
-                // `.get(fm["tier"])` returns None when tier is not 0/1/2 → undefined here.
-                _vis = typeof fm['tier'] === 'number' ? _tierToVis[fm['tier']] : undefined;
-            }
+            // ADR-090 named `visibility:` the source of truth; the integer
+            // `tier:` alias it superseded was dual-emitted here through the
+            // deprecation window and REMOVED in road-to-tier-removal Phase 4.
+            // The manifest no longer carries `tier` in any entry — the
+            // top-level `deprecations` block records the removal for consumers
+            // that still read the old key.
+            const _vis: Json = fm['visibility'];
             if (_vis !== undefined && _vis !== null) {
                 entry['visibility'] = _vis;
             }
@@ -788,27 +775,36 @@ function _build(strict: boolean): [JsonObject, JsonObject[]] {
     const stats = _compute_stats(artefacts, unassigned, documentedUnassigned);
 
     const manifest: JsonObject = {
-        version: 2,
-        // Machine-readable deprecation signal (road-to-tier-removal Phase 1,
-        // ADR-092). The integer command `tier` (0/1/2) is a back-compat alias
-        // for the named `visibility` field (ADR-090). It is STILL emitted into
-        // command entries above (non-breaking) — this block only ANNOUNCES the
-        // deprecation so external manifest consumers can migrate to `visibility`
-        // during the soak window. Removal of `tier` is Phase 4 of
-        // road-to-tier-removal (cheaply reversible per ADR-092); `sunset` is
-        // maintainer-owned and stays null until the soak clears.
+        // v3 (road-to-tier-removal Phase 4): the integer command `tier` is no
+        // longer emitted on `category: command` artefacts. That is a breaking
+        // change to a published data contract, and this schema's own rule is
+        // "bump on breaking change" — so the version carries the break rather
+        // than leaving a v2 consumer to discover a silently-absent field.
+        version: 3,
+        // Machine-readable removal record (road-to-tier-removal Phase 1 added
+        // this block as a deprecation ANNOUNCEMENT; Phase 4 turned it into the
+        // record of an executed removal). The entry is retained on purpose: a
+        // consumer that still reads the old key needs to find out what replaced
+        // it and when it went, and an absent entry would say neither. `sunset`
+        // is maintainer-owned: SET on 2026-08-13, with the soak wait explicitly
+        // waived ("wir haben lange genug gewartet"). ADR-137 had already reduced
+        // the re-open trigger set to this one act — a concrete sunset — after
+        // withdrawing the second trigger as structurally impossible in a
+        // no-runtime package.
         deprecations: [
             {
                 key: 'tier',
                 scope: 'command',
                 replacement: 'visibility',
                 since: 'ADR-092',
-                sunset: null,
+                sunset: '2026-08-13',
+                removed_in: 3,
                 note:
-                    'Integer command `tier` (0/1/2) is a deprecated back-compat ' +
-                    'alias for the named `visibility` field (ADR-090). Read ' +
-                    '`visibility`; `tier` is still emitted (non-breaking) but ' +
-                    'scheduled for removal — see road-to-tier-removal.',
+                    'Integer command `tier` (0/1/2) was a back-compat alias for ' +
+                    'the named `visibility` field (ADR-090). REMOVED in manifest ' +
+                    'v3 — command artefacts no longer carry `tier`. Read ' +
+                    '`visibility` (`visible` / `advanced` / `internal`); the old ' +
+                    'mapping was 0↔visible, 1↔advanced, 2↔internal.',
             },
         ],
         generated_at: _nowUtc(),