@event4u/agent-config 10.0.0 → 10.2.0

package/docs/guidelines/agent-infra/symptom-driven-harvest-loop.md

@@ -0,0 +1,104 @@
+# Symptom-driven harvest loop
+
+> The procedure that turns an **operator's production symptom** into a roadmap
+> this repository can execute. It is the inverse of the source-driven harvest:
+> that one starts from external material pushed onto the repo and asks what is
+> worth adopting; this one starts from a failure someone hit in production and
+> pulls external material in **per confirmed defect**.
+>
+> Body of `road-to-symptom-driven-harvest-loop` Phase 2. It lives here rather
+> than inline in [`roadmap-writing`](../../../src/skills/roadmap-writing/SKILL.md)
+> because that skill is already ~4.8k tokens — well past the 3,500-token band —
+> and a procedure needed a few times a quarter should not be paid for on every
+> roadmap-authoring turn. The skill carries the pointer.
+
+## When this applies
+
+An operator reports a failure in their own words — "runs never end", "the agent
+screenshots instead of reading the code" — rather than a defect with a file and
+a line. File it first under [`agents/tickets/symptoms/`](../../../agents/tickets/symptoms/README.md);
+that entry is what this loop resolves.
+
+Not this loop: a defect already traced to a file (that is a roadmap item), a
+feature request (roadmap or ticket), or external material arriving unprompted
+(the source-driven harvest family).
+
+## The four steps
+
+**1. Confirm against the live tree, at a pinned commit, before any external
+search.** One `file:line` per claim, and the pin recorded next to it. The
+ordering is the load-bearing part: searching externally first produces a plan
+about the ecosystem's problems rather than this tree's, and every subsequent
+round inherits that frame. A symptom that does not reproduce as a confirmed
+defect gets a `null:` block and stops here — that is a result.
+
+**2. Triangulate externally, per confirmed defect, never additively.** For each
+defect, and only for each defect: the host tool's own issue tracker, its official
+docs **fetched fresh**, and practitioner reports. Inverted form throughout — the
+defect is the anchor, the source is drawn in to explain or bound it. A source
+that matches no confirmed defect is not evidence for this roadmap; note it and
+drop it.
+
+**3. Iterate at least two further rounds, each stating its delta.** A round that
+changes nothing ends the loop early and says so. This is the step that is
+skipped under time pressure and the step that pays: on the first run of this
+loop, round 2 refuted a standing repo blocker from the official payload spec,
+imported a constraint that reshaped a whole phase from "block on invalid" to
+"command-hook, disk-fallback, block-once", and round 3 found a reopen-clause
+deadlock that was the *only* argument for reopening cancelled work at all. A
+one-pass version would have shipped a roadmap re-proposing cancelled items with
+no reopening argument and a mechanism the host would have broken.
+
+**4. Emit with a symptom→defect map and per-phase falsifiers.** The map is the
+artifact the operator can read: their words in one column, confirmed defects with
+anchors in the next, owning phase in the third. Every phase carries the
+measurement that would delete it.
+
+## Step 5, added by the first three runs: re-verify at adoption
+
+A roadmap drafted at a pin and adopted later is a **snapshot of an opinion about
+a tree that has since moved**. Before adopting, re-verify every repo claim at the
+current tip and record the deltas.
+
+This is not ceremony. Adopting the first three runs of this loop, 81 commits
+past their shared pin, re-verification found 32 of 36 claims still true — and:
+
+- one defect had **fixed itself** (a function measured as having zero production
+  callers had acquired one), which deleted a roadmap step before anyone built it;
+- one claim was **wrong at the pin too** (a count stated as six where the tree
+  binds seven), which no amount of re-reading the draft would have surfaced;
+- three anchors had **drifted** to new line numbers while their content held;
+- one cross-cutting conflict was invisible until two drafts were read together
+  (a proposed "adopt the artifact's code" duty against an existing
+  `NEVER ADOPT EXTERNAL CODE VERBATIM` Iron Law).
+
+The cheapest of those to find was the already-fixed one, and it was worth the
+most: an item prevented costs nothing to maintain.
+
+## Worked example — why round 2 is mandatory
+
+`hook_manifest.yaml` carried a comment stating that in-process subagents "inherit
+the host process env and cannot be marked per-spawn", and that comment had stood
+for months as a recorded blocker on a whole design axis. It was true about the
+mechanism it named — the env var — and false about the conclusion.
+
+Round 2 fetched the host's current payload specification, which states that tool
+events inside a subagent carry `agent_id` and `agent_type` precisely so
+subagent calls can be distinguished from main-thread ones. The env cannot mark a
+spawn; the payload already did. One fetch refuted a months-old blocker, and the
+axis it had closed reopened.
+
+The general shape: **a repo comment records what was tried, not what is
+possible.** Round 1 finds the comment and believes it, because it is this tree's
+own evidence. Only an external round can date it.
+
+## See also
+
+- [`roadmap-writing`](../../../src/skills/roadmap-writing/SKILL.md) — the authoring
+  skill this procedure extends; it owns phases, falsifiers, and the output format.
+- [`agents/tickets/symptoms/README.md`](../../../agents/tickets/symptoms/README.md) —
+  the intake convention and the two resolution blocks.
+- [`source-discovery-gate`](../../../src/rules/source-discovery-gate.md) — the
+  no-structural-claim-without-evidence rule step 1 is an application of.
+- [`external-reference-deep-dive`](../../../src/rules/external-reference-deep-dive.md) —
+  how to read a named external source properly in step 2.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "10.0.0",
+    "version": "10.2.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/agent-src/scripts/archive_completed_roadmaps.ts

@@ -335,6 +335,23 @@ function archive_completed(
         if (stats.open_ !== 0 || stats.deferred !== 0) {
             continue; // not complete
         }
+        // An unresolved blocker outlives its steps. Closing every box does not
+        // answer a question the roadmap raised for a human, and archiving on
+        // step-count alone is how `b-highlights-mechanism` left the active tree
+        // unanswered in the 9.29 roadmap — four releases before the failure it
+        // predicted shipped in the 9.36.0 changelog head. Same discipline
+        // `roadmap-progress-sync` Iron Law 3 applies to `[~]` steps: a roadmap
+        // carrying an open decision stays visible until the decision is made.
+        const open_blockers = stats.open_blockers;
+        if (open_blockers.length > 0) {
+            const ids = open_blockers.map((b) => b.id).join(', ');
+            process.stderr.write(
+                `  ⚠️  ${stats.rel}: all steps closed but ${open_blockers.length} ` +
+                    `blocker(s) still open (${ids}) — not archived. Resolve them, ` +
+                    'or record the decision, then re-run the sweep.\n',
+            );
+            continue;
+        }
         const old_rel = `agents/roadmaps/${stats.rel}`;
         if (changed_only && !(touched as Set<string>).has(old_rel)) {
             continue; // complete, but not this branch's work

package/src/agent-src/templates/scripts/work_engine/_lib/agent_settings.ts

@@ -210,7 +210,6 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'memory.cadence',
     'personal.bot_icon',
     'personal.autonomy',
-    'telegraph.speak_scope',
     // Knowledge-card global cross-project sharing is a USER-GLOBAL setting
     // (ADR-100 / road-to-structure-grounding-v2). Whitelisted so the
     // ~/.event4u/agent-config/agent-settings.yml values are honoured.

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

@@ -166,33 +166,25 @@ lean_projection:
 
 # --- Telegraph condensation (output-side) ---
 #
-# speak_scope: off | prose_only | aggressive   (QUOTE the value — bare `off` is a
-#                                              YAML 1.1 boolean, not the string)
-#
-# `off` is the shipped default per docs/adrs/telegraph/0001-default-off-until-bench.md
-# (Status: accepted) and docs/contracts/condensation-default-kill-criterion.md.
+# `speak: false` is the shipped default per
+# docs/adrs/telegraph/0001-default-off-until-bench.md (Status: accepted) and
+# docs/contracts/condensation-default-kill-criterion.md.
 # Reason it is off: the only output-side bench (telegraph-v1, n=10, 2026-05-16)
 # measured median vs_terse -9.27% (API counts) / -5.47% (exact cl100k_base
 # re-analysis) — telegraph emits MORE tokens than a plain "be terse" instruction.
 # The kill-criterion table therefore lands on "criterion not met — defer" and the
 # telemetry multiplier stays suspended (0.9155 < 1.0).
 #
-# NOTE: `speak_scope: off` disables the BEHAVIOUR but not the COST — the projector
-# gates this rule on `telegraph.speak`, never on speak_scope, so under
-# `lean_projection.mode: eager-all` the ~982-token body still ships every session.
-# Set `speak: false` for zero-cost dormancy.
-#
 # Stated explicitly here because until 2026-07-29 this default existed only in
-# prose — and two prose sources disagreed (the rule said prose_only, the accepted
-# ADR said off). Do not flip without a passing output-side bench.
+# prose — and two prose sources disagreed. Do not flip without a passing
+# output-side bench.
 telegraph:
   # speak: false = DORMANT (the shipped default per docs/adrs/telegraph/0002).
   # The rule is omitted from dist/router.json entirely, so its ~982-token body
-  # never ships. This — not speak_scope — is the lever that stops the cost:
-  # compile_router gates on `speak` and never reads speak_scope.
+  # never ships. This is the only lever that stops the cost: compile_router
+  # gates on `speak` and on nothing else.
   # Set true only after an output-side bench clears the kill-criterion bar.
   speak: false
-  speak_scope: "off"
 
 # --- Token-rich skills governance ---
 #
@@ -420,14 +412,6 @@ chat_history:
   #   per_tool  = one entry per tool call (most verbose)
   frequency: __CHAT_HISTORY_FREQUENCY__
 
-  # Max file size in KB before overflow handling kicks in (integer)
-  max_size_kb: __CHAT_HISTORY_MAX_SIZE_KB__
-
-  # Overflow behavior
-  #   rotate   = drop oldest entries to stay under max_size_kb
-  #   condense = mark for summarization on the next agent turn
-  on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
-
   # Per-entry-type text-length caps (chars). 0 = verbatim, no slice.
   # N > 0 = collapse whitespace, slice to N chars, append " … [+K chars]"
   # so the log self-reports truncation. Defaults match the hardcoded
@@ -656,12 +640,6 @@ quality:
   # gates delegated to remote CI", never claim an unrun pipeline passed.
   local_auto_run: false
 
-  # Wait for remote CI to finish on the PR / pipeline (true, false)
-  # true  = after push, poll GitHub check-runs / pipeline status and
-  #         report green / red before handing back
-  # false = push and hand back immediately; user inspects CI
-  #         themselves (default — saves agent runtime and tokens)
-  wait_for_remote_ci: false
 
 # --- Design fidelity ---
 #
@@ -744,6 +722,11 @@ screenshots:
   #       ship-and-hope. Illustrative / no-data screenshots (diagrams, logos,
   #       placeholder-only UI) may embed with a stated justification.
   # off = no data-bearing gate (legacy; the anonymization taxonomy still applies).
+  #
+  # NOTE: nothing reads this key yet — the gate it names is unconditional prose in
+  # `doc-screenshot-hygiene`. Kept rather than deleted so the missing reader is a
+  # visible gap instead of a silently unguarded action; see settings-classes.md
+  # § The six unread keys for the disagreement about which repair is right.
   data_bearing_gate: "on"
 
 code_style:
@@ -1365,7 +1348,6 @@ explain:
 # rule refuses every legal-review-prep skill until `acknowledged: true`.
 legal_review_prep:
   acknowledged: false
-  consented_at: ""
   # Gate legal work-product behind a multi-model council / deep-research pass
   # (defense-in-depth + audit trail; fail-closed). Off lets single-model legal
   # output through — not recommended for this high-risk pack.

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

@@ -22,9 +22,9 @@
       "note": "Markdown links between source artefacts that cross a pack boundary the source pack's `requires` graph does not reach — revealed when the scan root moved off the deleted packages/ tree to the live corpus (0 -> 753 artefacts scanned). 82 distinct pack pairs across 131 source files; largest single class is engineering-base -> meta (73), skills in a consumer-installable pack citing this package's own maintenance skills. Each is a link that dangles for a consumer who installs the source pack without the target's. Judged real drift rather than an over-strict gate because it is long-tailed — top bucket 22%, no single systematic cause — unlike the lint_artefact_frontmatter case, where one required shape had 0-of-288 adoption. Fix per finding: add the edge to packs.yml requires, retarget the link, or move the artefact."
     },
     "check_gate_completeness": {
-      "count": 217,
-      "landed": "2026-08-05",
-      "note": "Ledger adoption ratchet. 217 of 221 CI-registered gates do not yet carry per-target completeness accounting (`_lib/gate_ledger.ts`) or a `// ledger-exempt:` marker. This is deliberately NOT a sweep: road-to-skill-ecosystem-gate-integrity Phase 1 adopts exactly three gates (lint_framework_leakage, check_references, lint_roadmap_complexity) plus the checker itself to prove the interface, and the remainder migrates as gates are touched. Shrink-only from here — the number may not grow, so a NEW gate must adopt or exempt.",
+      "count": 216,
+      "landed": "2026-08-12",
+      "note": "Ledger adoption ratchet. 216 of 244 registered gates do not yet carry per-target completeness accounting (`_lib/gate_ledger.ts`) or a `// ledger-exempt:` marker. This is deliberately NOT a sweep: road-to-skill-ecosystem-gate-integrity Phase 1 adopts exactly three gates (lint_framework_leakage, check_references, lint_roadmap_complexity) plus the checker itself to prove the interface, and the remainder migrates as gates are touched. Shrink-only from here — the number may not grow, so a NEW gate must adopt or exempt.",
       "falsifier": "./scripts-run src/scripts/check_gate_completeness"
     },
     "check_depth_budget": {
@@ -37,6 +37,12 @@
       "landed": "2026-08-06",
       "note": "Self-test adoption ratchet, expressed as a shrink-only NON-adopter count. 24 of the 32 gates registered enforced in gate-coverage.yml carry neither a `--self-test` (`_lib/gate_self_test.ts`) nor a `// self-test-exempt: <reason>` marker, so nothing proves they DISCRIMINATE — an enforced `scanned:` floor proves a gate read something, only a self-test proves the reading changes the verdict. Deliberately NOT an adoption column ratcheted upward: check_gate_coverage.ts's own report_hardening_ratchet rejects that shape in this same file (\"grades the solution instead of the problem\"), and the sibling adoption ratchet (check_gate_completeness) is already a non-adopter count. Population is the manifest, not every script under src/scripts: padding the manifest to move this number would mean adding a floor per row. Shrink-only from here — a NEW registered gate must adopt or exempt. Migration mechanism, same as the ledger ratchet above: gates adopt as they are touched, not in a sweep — the eight current adopters were each added alongside a real change to that gate. The 56-day non-stagnation clause applies unchanged, so a count parked here fails on its own.",
       "falsifier": "./scripts-run src/scripts/check_gate_coverage"
+    },
+    "lint_settings_classes:derivable-surface": {
+      "count": 83,
+      "landed": "2026-08-12",
+      "note": "Anti-regrowth ratchet for the settings disposition axis. 83 of 134 template leaves are classified `derivable` — the mechanism can decide from the situation, so the key should not exist — and each names the replacement that would decide instead (`lint_settings_classes` rejects the bare label, which is what keeps the class from becoming a synonym for \"inconvenient to keep\"). This is a DELETION QUEUE, not 83 deletions: a row stays until the mechanism it names actually exists, and deleting a key ahead of its mechanism is a silently-changed default rather than a simplification. Shrink-only from here, which is the anti-regrowth half — a NEW key classified `derivable` raises the number and reds, so a key whose answer the situation already carries cannot be added at all. The 56-day non-stagnation clause is the other half and is wanted here rather than tolerated: a queue that never drains is a stated direction nobody is walking. The queue opened at 88 of 140 on 2026-08-12 and drained to 83 of 134 the same day: six keys had no reader whatsoever (telegraph.speak_scope, chat_history.max_size_kb, chat_history.on_overflow, quality.wait_for_remote_ci, screenshots.data_bearing_gate, legal_review_prep.consented_at), five of them `derivable` and one a `consent` row reclassified because a published-egress confirmation is a Hard Floor no setting may lift. An unread key is the only deletion that cannot silently change a default, which is why that batch went first. The classification itself is docs/contracts/settings-classes.md.",
+      "falsifier": "./scripts-run src/scripts/lint_settings_classes"
     }
   }
 }

package/src/config/profiles/balanced.ini

@@ -17,5 +17,3 @@ discipline_profile=auto
 
 ; Chat history (crash recovery) — balanced = phase-level traceability
 chat_history_frequency=per_phase
-chat_history_max_size_kb=256
-chat_history_on_overflow=rotate

package/src/config/profiles/full.ini

@@ -13,7 +13,5 @@ rule_loading_tier=full
 ; via the legacy mapping (minimal->off, balanced->essential, full->full).
 discipline_profile=full
 
-; Chat history (crash recovery) — full = tool-level traceability + summarize on overflow
+; Chat history (crash recovery) — full = tool-level traceability
 chat_history_frequency=per_tool
-chat_history_max_size_kb=512
-chat_history_on_overflow=condense

package/src/config/profiles/minimal.ini

@@ -15,5 +15,3 @@ discipline_profile=off
 
 ; Chat history (crash recovery) — minimal = lightest footprint
 chat_history_frequency=per_turn
-chat_history_max_size_kb=128
-chat_history_on_overflow=rotate

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -20,6 +20,7 @@
  *   agent-config session:recycle --file <envelope.json>   # read from file
  *   agent-config session:recycle < envelope.json          # read from stdin
  *   agent-config session:recycle --template               # print a skeleton
+ *   agent-config session:recycle --project <path>         # name the repo explicitly
  *
  * Exit codes: 0 written (or template printed) · 1 invalid / refused · 2 usage.
  */
@@ -29,7 +30,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { resolve_project_root } from '../_lib/agent_settings.js';
+import { ORIGIN_CWD_FALLBACK, resolve_project_root } from '../_lib/agent_settings.js';
 import {
     RECYCLE_ENVELOPE_MAX_BYTES,
     RECYCLE_ENVELOPE_REL,
@@ -77,6 +78,7 @@ interface ParsedArgv {
     ok: boolean;
     message?: string;
     file?: string;
+    project?: string;
     template?: boolean;
     verify?: boolean;
 }
@@ -94,6 +96,11 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
             if (!value) return { ok: false, message: '--file requires a path' };
             parsed.file = value;
             i += 1;
+        } else if (a === '--project') {
+            const value = argv[i + 1];
+            if (!value) return { ok: false, message: '--project requires a path' };
+            parsed.project = value;
+            i += 1;
         } else if (a === '-h' || a === '--help') {
             return { ok: false, message: 'usage' };
         } else {
@@ -110,11 +117,50 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
  */
 export function runSessionRecycle(
     input: string,
-    opts: { cwd: string; now?: Date; verify?: boolean },
+    opts: { cwd: string; now?: Date; verify?: boolean; project?: string },
 ): RecycleResult {
     const out: string[] = [];
     const err: string[] = [];
-    const [projectRoot] = resolve_project_root(null, { cwd: opts.cwd });
+
+    // `--project` is validated by the resolver (existence + directory), which
+    // signals by THROWING. Uncaught, that would surface as a stack trace from
+    // a command whose entire subject is legible failure.
+    let projectRoot: string;
+    let origin: string;
+    try {
+        [projectRoot, origin] = resolve_project_root(opts.project ?? null, { cwd: opts.cwd });
+    } catch (exc) {
+        return { code: 1, out, err: [`recycle envelope refused — ${String(exc)}`] };
+    }
+
+    // An unanchored cwd is the ONE case where a successful write is worse than
+    // a refusal. `resolve_project_root` falls back to the cwd itself when it
+    // reaches the filesystem root without finding an anchor, so a call from
+    // outside any repo — the shape a consumer with a toolchain pin is forced
+    // into — writes a valid envelope into a directory the successor session
+    // never looks at, and then prints a resume instruction whose next step is
+    // `/clear`. The exit code says it worked; the session is gone anyway.
+    //
+    // Refused BEFORE the parse: everything downstream reads this root, so a
+    // wrong one also produces a wrong `workspace` field and grounding read
+    // from the wrong git tree. `--verify` is refused too — validating against
+    // a root the write would not use answers a question nobody asked.
+    if (origin === ORIGIN_CWD_FALLBACK) {
+        return {
+            code: 1,
+            out,
+            err: [
+                `recycle envelope refused — no project anchor at or above ${projectRoot}`,
+                'Writing here would put the envelope where the successor session never reads it,',
+                'and the resume instruction would then advise /clear on a session that cannot resume.',
+                'Name the repository explicitly — it must be the WORKSPACE ROOT OF THE SESSION',
+                'that will resume, because that is the directory the successor reads the envelope',
+                'from; a path that merely happens to be a project is not enough:',
+                `  agent-config session:recycle --project <session-workspace-root> …`,
+                `  AGENT_CONFIG_PROJECT_ROOT=<session-workspace-root> agent-config session:recycle …`,
+            ],
+        };
+    }
 
     let parsed: unknown;
     try {
@@ -179,23 +225,28 @@ export function runSessionRecycle(
         };
     }
 
+    // Absolute, not `RECYCLE_ENVELOPE_REL`: the relative form is identical for
+    // every root, so it cannot tell the reader WHICH tree was written — the
+    // one thing in doubt at the moment this line is read.
+    const target = path.join(projectRoot, RECYCLE_ENVELOPE_REL);
+
     // `--verify` stops HERE: every rejection above has already run, and the
     // only thing skipped is the write. Validating through a different path
     // than the one that writes would make the check a second implementation
     // to keep in sync — the failure this suite refuses elsewhere.
     if (opts.verify === true) {
         out.push(`recycle envelope VALID — ${bytes} bytes, not written (--verify).`);
+        out.push(`Target would be: ${target}`);
         return { code: 0, out, err };
     }
 
-    const target = path.join(projectRoot, RECYCLE_ENVELOPE_REL);
     try {
         atomic_write_json(target, envelope);
     } catch (exc) {
         return { code: 1, out, err: [`could not write ${target}: ${String(exc)}`] };
     }
 
-    out.push(`recycle envelope written — ${RECYCLE_ENVELOPE_REL} (${bytes} bytes)`);
+    out.push(`recycle envelope written — ${target} (${bytes} bytes)`);
     out.push('');
     out.push('Resume instruction:');
     out.push('  1. End this session now: run /clear (or start a fresh session in this workspace).');
@@ -210,10 +261,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const parsed = parseArgv(argv);
     if (!parsed.ok) {
         const usage = [
-            'usage: agent-config session:recycle [--file <envelope.json>] [--template] [--verify]',
-            '  --file <path>   read the envelope JSON from a file (default: stdin)',
-            '  --template      print a skeleton envelope and exit',
-            '  --verify        validate only — same rejections, no write',
+            'usage: agent-config session:recycle [--file <envelope.json>] [--project <path>] [--template] [--verify]',
+            '  --file <path>     read the envelope JSON from a file (default: stdin)',
+            '  --project <path>  the workspace root of the session that will resume — required',
+            '                    when the working directory is outside any project (the command',
+            '                    refuses rather than writing an envelope the successor cannot',
+            '                    find). The successor reads the envelope from ITS OWN workspace',
+            '                    root, so a path that is merely a valid project is not enough.',
+            '  --template        print a skeleton envelope and exit',
+            '  --verify          validate only — same rejections, no write',
         ].join('\n');
         if (parsed.message === 'usage') {
             process.stdout.write(`${usage}\n`);
@@ -246,6 +302,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const result = runSessionRecycle(input, {
         cwd: process.cwd(),
         ...(parsed.verify === true ? { verify: true } : {}),
+        ...(parsed.project !== undefined ? { project: parsed.project } : {}),
     });
     for (const line of result.out) process.stdout.write(`${line}\n`);
     for (const line of result.err) process.stderr.write(`${line}\n`);

package/src/scripts/_cli/handoff_sessions.ts

@@ -30,6 +30,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
+import { projectStoreSlug } from '../_lib/cc_transcript.js';
 import { derive_session_tag, list_sessions, read_entries } from '../chat_history.js';
 import { eolSessionKey, readEolCounters, type StoredEolCounters } from '../_lib/session_eol.js';
 
@@ -102,9 +103,9 @@ export interface ListOptions {
     workspaceRoot?: string;
 }
 
-/** Mirrors the Claude Code project-dir naming: `/` and `.` → `-`. */
+/** Mirrors the Claude Code project-dir naming — see `_lib/cc_transcript.projectStoreSlug`. */
 export function encode_project_path(cwd: string): string {
-    return cwd.replace(/[/.]/g, '-');
+    return projectStoreSlug(cwd);
 }
 
 function _snippet(text: string, max: number = SUMMARY_SNIPPET_CHARS): string {

package/src/scripts/_lib/agent_settings.ts

@@ -283,7 +283,6 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'personal.bot_icon',
     'personal.pr_comment_bot_icon',
     'personal.autonomy',
-    'telegraph.speak_scope',
     // Knowledge-card global cross-project sharing is a USER-GLOBAL setting
     // (ADR-100 / road-to-structure-grounding-v2). Whitelisted so the
     // ~/.event4u/agent-config/agent-settings.yml values are honoured.
@@ -908,8 +907,27 @@ export function load_agent_settings(
  * made the soak impossible; whether the gate fires is now decided by each
  * detector's own trigger conditions. See `turn_end_gate_hook.ts` § "Always
  * armed".
+ *
+ * The five `derivable` leaves below (2026-08-12, road-to-zero-settings Phase
+ * 2.1) are a different case from every entry above them, and the difference is
+ * the whole safety argument: no code path ever *consulted* them. Each appeared
+ * in the template, the schema and the reference page, and several in the setup
+ * wizard, while the decision they looked like they governed was taken
+ * elsewhere. A key nothing reads cannot change a default by leaving — so this
+ * is the one deletion batch that needs no replacement mechanism, only the
+ * per-key statement of what already decides.
+ *
+ * A sixth unread key, `screenshots.data_bearing_gate`, was found in the same
+ * pass and deliberately NOT deleted — it is `consent`, and the open question is
+ * 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.
+ *
+ * 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
+ * the template again, is a contradiction the loader itself cannot notice.
  */
-const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
+export const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
     ['subagents.enabled', 'always-on orchestration'],
     ['subagents.auto', 'always-on orchestration'],
     ['subagents.host_capabilities', 'always-on orchestration'],
@@ -919,6 +937,11 @@ const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
     ['hooks.turn_end_gate.promissory', 'the turn-end gate is always armed'],
     ['hooks.turn_end_gate.language', 'the turn-end gate is always armed'],
     ['hooks.turn_end_gate.verification', 'the turn-end gate is always armed'],
+    ['telegraph.speak_scope', 'the rule body states its own scope; compile_router gates on telegraph.speak alone'],
+    ['chat_history.max_size_kb', 'the rotate command takes --max-kb from argv; session-count pruning bounds the file'],
+    ['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'],
 ]);
 
 /** Keys already warned about in THIS process — the "once per run" dedupe. */

package/src/scripts/_lib/bench_telegraph.ts

@@ -23,7 +23,7 @@ import YAML from 'yaml';
 
 // ── system prompts per arm ──────────────────────────────────────────────
 
-export const SYSTEM_PROMPT_CONDENSED = `You are speaking in TELEGRAPH-SPEAK mode (speak_scope=aggressive).
+export const SYSTEM_PROMPT_CONDENSED = `You are speaking in TELEGRAPH-SPEAK mode (condense aggressively).
 
 Condense all body prose to telegraph grammar:
 - Drop articles (the, a, an).

package/src/scripts/_lib/cc_transcript.ts

@@ -35,6 +35,31 @@ import { homedir } from 'node:os';
 /** Default base directory holding one subdirectory per Claude Code project. */
 export const DEFAULT_PROJECTS_ROOT = path.join(homedir(), '.claude', 'projects');
 
+/**
+ * The store directory name Claude Code derives from a working directory.
+ *
+ * Every character outside `[A-Za-z0-9-]` becomes `-`: `/Users/x/.claude` →
+ * `-Users-x--claude`, and a worktree `feat+turn-end-gate-always-on` →
+ * `feat-turn-end-gate-always-on`.
+ *
+ * This lives here because it was wrong in six places at once. The sweep on
+ * 2026-08-12 found `replace(/[/.]/g, '-')` copied across every transcript-reading
+ * report; each one computed a directory that does not exist for any path
+ * carrying a `+` and returned an empty corpus — indistinguishable from a clean
+ * result. One of those copies already carried a comment about the round BEFORE
+ * that, when only `/` was replaced and dotted segments missed. Widening the
+ * class by one character per incident is how a defect survives two fixes, so
+ * the class is closed instead: anything not `[A-Za-z0-9-]` is slugged.
+ */
+export function projectStoreSlug(cwd: string): string {
+  return cwd.replace(/[^A-Za-z0-9-]/g, '-');
+}
+
+/** Absolute path to a working directory's transcript store. */
+export function projectStoreDir(cwd: string, root: string = DEFAULT_PROJECTS_ROOT): string {
+  return path.join(root, projectStoreSlug(cwd));
+}
+
 export type TranscriptBucket = 'main' | 'subagent';
 
 /** The six token counters every downstream metric (cost, weight, share) is built from. */

package/src/scripts/_lib/compile_time_toggles.ts

@@ -60,9 +60,10 @@ export const COMPILE_TIME_TOGGLES: Record<string, (s: ToggleSettings) => boolean
     // family master switch, and flipping it would silence sibling telegraph settings
     // that were never measured negative.
     //
-    // This predicate deliberately does NOT read `speak_scope`. That key disables the
-    // rule's *behaviour* and never removed its token cost — the trap the measurement
-    // exposed.
+    // The predicate gates on `telegraph.speak` because that is the only lever that
+    // removes the rule's ~982-token body from the router and the projection. A knob
+    // that merely narrowed the grammar at runtime would leave the token cost in place
+    // — the trap the measurement exposed.
     'telegraph-speak': (s: ToggleSettings): boolean => {
         const tg = (s['telegraph'] as ToggleSettings | undefined) ?? {};
         const enabled = tg['enabled'] === undefined ? true : tg['enabled'];