@event4u/agent-config 14.5.0 → 14.7.0

package/src/scripts/_lib/scope_guard.sh

@@ -12,13 +12,29 @@
 # Verdicts (per the roadmap contract):
 #   OK     — no install at the other scope; the install can proceed.
 #   WARN   — install at the other scope, SAME version as the one being installed.
-#            Same content; duplicate registration but no drift.
+#            No drift — and NOT free. The host loads both registrations with no
+#            dedup, so every shared artefact is delivered twice. This verdict used
+#            to read "Same content; duplicate registration but no drift", which
+#            classified duplication by DRIFT RISK and never by CONTEXT COST, and
+#            so taught every reader that identical copies cost nothing. Measured
+#            2026-08-19 on a freshly regenerated maintainer projection: 110 rules
+#            and 290 skills delivered twice, 203,873 tok of standing rule prose
+#            against a 110,000 cap. See ADR-236 and
+#            agents/evidence/analysis/single-delivery-partition-census.md.
 #   DRIFT  — install at the other scope, DIFFERENT version (or unreadable).
 #            Drift will produce the 2026-05-25 failure mode (stale frontmatter
 #            registered alongside fresh frontmatter).
 #
 # Output shape (line-oriented, parseable by install.sh):
-#   <verdict>\t<tool-id>\t<other-scope-path>\t<other-version>\t<this-version>
+#   <verdict>\t<tool-id>\t<other-scope-path>\t<other-version>\t<this-version>[\t<overlap>]
+#
+# Field 6 (<overlap>) is emitted on WARN lines only: the number of entry names
+# present in BOTH scope directories — what a same-version duplicate registration
+# actually delivers twice. It is APPENDED rather than inserted, so every existing
+# field-indexed consumer keeps working unchanged. `-1` means the count could not
+# be taken — the scope being installed to does not exist yet, or a directory is
+# unreadable — which is reported rather than silently rendered as 0. See
+# `count_overlap` for why the two are different facts.
 #
 # A final summary line is emitted:
 #   SUMMARY\t<verdict>\t<count-OK>\t<count-WARN>\t<count-DRIFT>
@@ -67,6 +83,44 @@ dir_nonempty() {
     [[ -d "$1" ]] && [[ -n "$(ls -A "$1" 2>/dev/null | head -1)" ]]
 }
 
+# Count entry names present in BOTH scope directories — what a same-version
+# duplicate registration actually delivers twice, which is the cost the WARN
+# verdict used to omit.
+#
+# Returns -1 rather than 0 when the count cannot be taken, because the two are
+# different facts and reporting "0 overlap" for "could not look" is how a gate
+# starts reading as coverage.
+#
+# R2 review corrected the docstring twice over. The copilot probe was named here
+# as the concrete -1 case; it is UNREACHABLE, because `dir_nonempty`'s `[[ -d ]]`
+# test short-circuits a single-file path to OK before probe_tool ever reaches a
+# version comparison. The reachable cases are: the scope being installed TO does
+# not exist yet (a first install at this scope — genuinely no overlap to count,
+# not a failure), and a directory that exists but cannot be read.
+#
+# The unreadable case used to return 0 — the precise failure this function's own
+# docstring claimed to prevent, because `cd` failed inside the process
+# substitution and `comm` compared two empty streams. It is now detected before
+# the comparison.
+count_overlap() {
+    local a="$1" b="$2" n
+    if [[ ! -d "$a" ]] || [[ ! -d "$b" ]]; then
+        printf '%s' '-1'
+        return 0
+    fi
+    # Readability is checked explicitly: `ls` on an unreadable directory fails,
+    # and inside `<(...)` that failure is invisible to the caller.
+    if ! ls -A "$a" >/dev/null 2>&1 || ! ls -A "$b" >/dev/null 2>&1; then
+        printf '%s' '-1'
+        return 0
+    fi
+    n="$(comm -12 \
+            <(ls -A "$a" 2>/dev/null | sort) \
+            <(ls -A "$b" 2>/dev/null | sort) \
+         2>/dev/null | wc -l | tr -d ' ')" || n=''
+    printf '%s' "${n:--1}"
+}
+
 # Per-tool probe definitions: tool-id, user-scope path, project-scope path.
 # Project-scope path is relative to "$TARGET_DIR" (or "$HOME/<proj>" for user).
 probe_tool() {
@@ -111,10 +165,38 @@ probe_tool() {
     local this_ver
     this_ver="$(this_version)"
 
+    # Field 6 is the duplicate-registration count, and it is printed on BOTH
+    # verdicts. It used to appear only on WARN, which required the two scopes to
+    # report the SAME version — and `installed_version_at` returns `unknown` for
+    # `~/.claude/…` because a host directory has no `package.json` beside it. So
+    # every real cross-scope install classified as DRIFT and the count never
+    # printed at all: the instrumentation was live and unreachable, which reads as
+    # coverage in a diff and is strictly worse than absent.
+    #
+    # Resolved 2026-08-20, road-to-single-delivery Phase 5, blocker
+    # `warn-path-unreachable-without-version-marker`, option (b). The council had
+    # already put the reasoning on record in the round that decided the partition:
+    # *"overlap reporting should not depend on version equality in the first
+    # place. Duplicate files can and should be reported whether versions match,
+    # drift, or are unknown."* A duplicate is a duplicate at any version pair.
+    #
+    # (a) — having the installer stamp a version beside every host layer — was the
+    # larger change and is NOT what shipped: it alters a consumer-facing surface to
+    # repair a reporting line. (c) — treating `unknown` as "same version" for the
+    # overlap half — was rejected because it weakens the DRIFT block itself.
+    #
+    # Wire compatibility: the DRIFT line gains a SIXTH field. The only structured
+    # consumer (`src/server/routes/wizard.ts`) destructures the first five and
+    # ignores the rest, so this is additive.
+    local overlap
+    overlap="$(count_overlap "$other_path" "$this_scope_path")"
     if [[ "$other_ver" == "unknown" ]] || [[ "$this_ver" == "unknown" ]] || [[ "$other_ver" != "$this_ver" ]]; then
-        printf 'DRIFT\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver"
+        printf 'DRIFT\t%s\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver" "$overlap"
     else
-        printf 'WARN\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver"
+        # Same version, so no drift — but the duplicate registration is delivered
+        # twice, and field 6 is what makes that cost visible at the moment of the
+        # decision instead of only in a token census nobody runs.
+        printf 'WARN\t%s\t%s\t%s\t%s\t%s\n' "$tool" "$other_path" "$other_ver" "$this_ver" "$overlap"
     fi
 }
 

package/src/scripts/_lib/self_repair.ts

@@ -338,6 +338,25 @@ const COMPLAINT_PATTERNS: readonly RegExp[] = [
     /\byou (didn'?t|did not|failed to|ignored|forgot)\b/i,
     /\bthat'?s (wrong|not right|incorrect)\b/i,
     /\byou (worked|did (it|that)) (wrong|incorrectly)\b/i,
+    // Recurrence phrasings. A restated complaint often carries none of the fault
+    // words above — "das habe ich dir schon dreimal gesagt" names no fault at
+    // all — so without these the SECOND and THIRD report of a defect were
+    // silently not records, which is exactly when the occurrences counter
+    // carries the most signal.
+    //
+    // Every branch requires an explicit COUNT word next to a saying-verb, and
+    // that is the precision knob: "nochmal" / "wieder" / "again" are deliberately
+    // NOT counts, because a bare repetition word fires on a large share of
+    // ordinary prompts ("mach das nochmal") and a spurious record becomes a
+    // spurious PR. Ordinals and numerals only.
+    /\b(schon|bereits)[^.!?]{0,30}(zum (zweiten|dritten|vierten|fünften) mal|(zwei|drei|vier|fünf)mal|mehrmals|mehrfach|\d+ ?mal)[^.!?]{0,20}(gesagt|erwähnt|geschrieben|angesprochen)\b/i,
+    /\b(sage|sag|sagte)[^.!?]{0,30}(zum (zweiten|dritten|vierten|fünften) mal|(zwei|drei|vier|fünf)mal|mehrmals|mehrfach|\d+ ?mal)\b/i,
+    /\bwie oft (soll|muss|müssen)\b/i,
+    // Typographic AND ASCII apostrophe: the curly form is what a real prompt
+    // carries, and matching only the ASCII one is a dead branch on live input.
+    /\bi ?(have|['’]ve)? ?already (told|said)\b/i,
+    /\b(told|said) (you )?(this|that|it)? ?(\w+|\d+) times?\b/i,
+    /\bhow many times (do|must|should) i\b/i,
 ];
 
 // Phrasings that MATCH a complaint pattern but are not complaints — a curious

package/src/scripts/_lib/self_repair_class_b.ts

@@ -0,0 +1,171 @@
+/**
+ * The Class-B path (road-to-org-telemetry Phase 5, step 5.2).
+ *
+ * Class A is the automatic half: structural fields, no content, shipped under
+ * recorded org consent. Class B is an abstracted CASE — what was expected
+ * versus what happened, and which artefacts were involved — and it ships only
+ * on explicit per-case approval of the exact text that would leave.
+ *
+ * THE GATE IS THE HUMAN READING THE OUTBOUND TEXT, NOT A FILTER. Rank 1 of the
+ * roadmap risk register is "an abstraction miss ships a path or an identifier
+ * out of a consumer project", and its stated mitigation is per-case review of
+ * the exact outbound text rather than a filter heuristic. So this module's job
+ * is to make the exact bytes visible and then refuse to release them unless the
+ * approval names those same bytes. `approve` takes a digest of the rendered
+ * text; a text that changed after the human read it no longer matches, and the
+ * release refuses rather than shipping something nobody approved.
+ *
+ * SILENT SHIPPING IS PERMANENTLY OUT OF SCOPE, and the step says so in those
+ * words. There is deliberately no "auto-approve", no allow-list of
+ * self-evidently safe classes, and no timeout that approves by default.
+ *
+ * TWO EXISTING PRIMITIVES ARE REUSED RATHER THAN RE-INVENTED:
+ *  - `renderReport` is "the existing symptom format" the step names.
+ *  - `egressBlockedReason` is the audited privacy floor — the same one the
+ *    local corpus write and the upstream release already pass through. It
+ *    REFUSES rather than rewriting, which is the property that makes it a gate;
+ *    a module that silently scrubbed and shipped would be a soft gate wearing
+ *    a hard gate's name.
+ *
+ * WHAT THIS MODULE DOES NOT DO: send anything. Transport and sink-side storage
+ * are Phase 5 step 5.3, transferred with `sink-choice` — no sink exists for an
+ * approved case to travel to. `ClassBRecord` is therefore built, gated and
+ * held; the field that carries the text is `case_text` and it is a typed
+ * member of a typed record, never a string interpolated into a prompt.
+ */
+import * as crypto from 'node:crypto';
+
+import {
+    type DefectRecord,
+    egressBlockedReason,
+    renderReport,
+} from './self_repair.js';
+
+/** Schema version for the Class-B envelope, independent of Class A. */
+export const CLASS_B_SCHEMA_VERSION = 1;
+
+/**
+ * One approved case.
+ *
+ * `case_text` is the ONLY free-form member and it exists on purpose: Class B
+ * is defined as an abstracted case, so a Class-B record without text would be
+ * a Class-A record. The controls are that it is (a) a named, typed field
+ * rather than an open `payload`, (b) present only after `approve` matched a
+ * digest a human read, and (c) documented as data end to end — see
+ * `assertNeverInterpolated`.
+ */
+export interface ClassBRecord {
+    schema_version: number;
+    record_class: 'case';
+    /** Detector / intake class, from the pinned vocabulary. */
+    defect_class: string;
+    /** Fingerprint of the local record this case abstracts. */
+    fingerprint: string;
+    /** SHA-256 of `case_text`, so a consumer can verify what was approved. */
+    case_digest: string;
+    /** The abstracted case, exactly as the human approved it. */
+    case_text: string;
+}
+
+export type ClassBRefusal =
+    | { ok: false; reason: string; kind: 'privacy-floor' | 'digest-mismatch' | 'empty' };
+
+export type ClassBResult = { ok: true; record: ClassBRecord } | ClassBRefusal;
+
+/** SHA-256 hex of the exact bytes a human is asked to approve. */
+export function caseDigest(text: string): string {
+    return crypto.createHash('sha256').update(text, 'utf-8').digest('hex');
+}
+
+/**
+ * Render the exact outbound text for one record, or refuse.
+ *
+ * Refusal comes from the audited privacy floor and is returned as a reason
+ * string for the caller to show. It is NOT downgraded to a scrub-and-continue:
+ * a record whose evidence trips the floor stays local, which is the same
+ * verdict the upstream release path already reaches.
+ */
+export function renderCase(
+    record: DefectRecord,
+    repoRoot?: string | null,
+): { ok: true; text: string; digest: string } | ClassBRefusal {
+    const blocked = egressBlockedReason(record, repoRoot ?? null);
+    if (blocked !== null) {
+        return { ok: false, reason: blocked, kind: 'privacy-floor' };
+    }
+    // `issue` is the route whose rendering carries no patch and no repository
+    // path — the narrowest of the existing shapes, and the right one for a
+    // case that travels to a telemetry sink rather than to a code host.
+    const text = renderReport(record, 'issue');
+    if (text.trim() === '') {
+        return { ok: false, reason: 'nothing to send', kind: 'empty' };
+    }
+    return { ok: true, text, digest: caseDigest(text) };
+}
+
+/**
+ * Approve one rendered case for release.
+ *
+ * `approved_digest` is what the human saw. If the text has changed since —
+ * a new occurrence folded in, a re-render, anything — the digests differ and
+ * this refuses. That is the difference between approving a case and approving
+ * a category.
+ */
+export function approve(
+    record: DefectRecord,
+    text: string,
+    approved_digest: string,
+): ClassBResult {
+    const actual = caseDigest(text);
+    if (actual !== approved_digest) {
+        return {
+            ok: false,
+            kind: 'digest-mismatch',
+            reason:
+                'the approved text is not the text that would be sent — '
+                + 're-render, read it again, and approve the new digest',
+        };
+    }
+    return {
+        ok: true,
+        record: {
+            schema_version: CLASS_B_SCHEMA_VERSION,
+            record_class: 'case',
+            defect_class: record.defect_class,
+            fingerprint: record.fingerprint,
+            case_digest: actual,
+            case_text: text,
+        },
+    };
+}
+
+/**
+ * Serialise an approved case as ONE JSON object.
+ *
+ * This is the whole of "quoted, typed data" (step 5.3's repository-side half):
+ * the text is a JSON string value, so a downstream reader parses it into a
+ * field. Nothing here concatenates it into a sentence, a prompt, or a shell
+ * argument, and rank 2 of the risk register — a crafted complaint steering a
+ * generated change — is what that discipline is for.
+ */
+export function serialiseCase(record: ClassBRecord): string {
+    return JSON.stringify(record);
+}
+
+/**
+ * Guard for a downstream consumer: refuse a prompt-shaped use of case text.
+ *
+ * Deliberately a narrow, honest tool. It cannot stop a caller that never asks;
+ * what it does is give the generation step in Phase 6 something to call, so
+ * "reads taxonomy fields only, never Class-B free text" is a check rather than
+ * a convention. The intended use is at the boundary where a record becomes
+ * model input.
+ */
+export function assertNeverInterpolated(candidate: string, record: ClassBRecord): void {
+    if (record.case_text !== '' && candidate.includes(record.case_text)) {
+        throw new Error(
+            'Class-B case text must reach a model as quoted data, never as part '
+            + 'of an instruction string — pass the record, not a concatenation',
+        );
+    }
+}

package/src/scripts/_lib/subagent_capsule.ts

@@ -120,6 +120,76 @@ function isShortLine(value: unknown, max: number): value is string {
     return typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\n');
 }
 
+/**
+ * Is this a path ref rather than prose?
+ *
+ * The discriminator is **whitespace**, and it is deliberately the only one.
+ * A path ref is one token; a prose sentence is several words. Anything
+ * narrower — a character class, a required extension, a mandatory `/` —
+ * rejects entries this tree really uses: a bare directory (`docs`), a sibling
+ * worktree (`../other-worktree/`), a dotfile. Anything wider stops telling the
+ * two shapes apart at all.
+ *
+ * This is a SHAPE check, never an existence or semantics check. A single-token
+ * value that is not a real path passes and then simply never matches anything,
+ * which is correct: the failure this closes is a field whose own documentation
+ * says "a list of path refs" silently accepting full sentences.
+ *
+ * **It is not a matcher, and a consumer must not mistake it for one.** It
+ * answers "is this one token", never "does this entry cover that write target".
+ * It admits a bare directory, a trailing-slash relative ref, a glob and a
+ * `file:line` ref; normalisation, directory-prefix matching and glob matching
+ * are deliberately unspecified here, because they are a separate decision that
+ * belongs to whatever ships the comparison. Reuse this for what VALIDATES;
+ * decide separately what MATCHES.
+ *
+ * **Stated default, not a measured optimum:** zero tracked paths in this repo
+ * contain whitespace, so the rule costs nothing here. *Revisit-if* a consumer
+ * legitimately needs a path containing a space — that needs a quoting
+ * convention, not a wider character class.
+ */
+export function isPathRef(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0 && !/\s/.test(value);
+}
+
+/**
+ * `checkList` plus the path-ref shape, for a field whose own documentation
+ * calls its entries path refs. Names the offending entries: "one of your
+ * twelve entries is wrong" is not an actionable error.
+ *
+ * The shape report is suppressed for exactly one reason — the same entries
+ * already failed the per-entry budget, where reporting both says the same thing
+ * twice. It is deliberately NOT suppressed by the entry-COUNT error, which is
+ * orthogonal: a 41-entry list of prose sentences must report both problems in
+ * one pass, or the author trims to 40, re-validates, and only then learns the
+ * entries were prose — an extra refuse-and-repair round-trip on the write path
+ * this contract points at as the repair mechanism.
+ */
+function checkPathRefList(
+    errors: string[],
+    field: string,
+    value: unknown,
+    max: number,
+    required: boolean,
+): void {
+    checkList(errors, field, value, max, required);
+    if (!Array.isArray(value)) return;
+    // Same-entry duplicate only: an entry that failed the budget is already
+    // reported, and its shape adds nothing a reader can act on separately.
+    if (value.some((x) => !isShortLine(x, max))) return;
+
+    const bad = value.filter((x) => !isPathRef(x));
+    if (bad.length === 0) return;
+
+    const shown = bad.slice(0, 3).map((x) => JSON.stringify(String(x))).join(', ');
+    errors.push(
+        `${field} carries ${bad.length} entr${bad.length === 1 ? 'y' : 'ies'} that are prose, not path refs: ` +
+            `${shown}${bad.length > 3 ? ', …' : ''} — write the path (src/generated/api.ts, ../other-worktree/) ` +
+            'or drop the entry; a sentence naming a file cannot be compared against a write target, and being ' +
+            'comparable is the whole reason this is a field rather than a line of prose',
+    );
+}
+
 function checkList(
     errors: string[],
     field: string,
@@ -257,6 +327,14 @@ export interface MainSessionRecycleEnvelope {
      * adjudication set (a field whose presence is checkable survives where a
      * doctrine whose effect is unmeasured did not).
      *
+     * The path-ref shape is **enforced** (`isPathRef`), not merely documented.
+     * It was documented-only until 2026-08-19, and the gap was not academic:
+     * the validator applied the ref CHARACTER BUDGET and no shape rule, so the
+     * one real non-empty producer — a composing model — wrote prose sentences
+     * naming files, and every one of them validated. A field that accepts
+     * whatever prose the writer felt like is `constraints` with extra steps,
+     * and nothing downstream can compare it to a write target.
+     *
      * Optional: an envelope with nothing off limits states nothing here, and an
      * empty list is not a claim that everything is writable.
      */
@@ -596,7 +674,9 @@ export function validateRecycleEnvelope(input: unknown): string[] {
     errors.push(...decisionTagErrors(e['decisions']));
     checkList(errors, 'constraints', e['constraints'], MAX_LINE_CHARS, false);
     // Path refs, so the REF budget applies — not the prose one `constraints` uses.
-    checkList(errors, 'do_not_touch', e['do_not_touch'], MAX_REF_CHARS, false);
+    // And the SHAPE is checked, not only the budget: the budget alone accepted a
+    // prose sentence naming a file, which is what the only real producer wrote.
+    checkPathRefList(errors, 'do_not_touch', e['do_not_touch'], MAX_REF_CHARS, false);
     checkList(errors, 'open_worker_envelopes', e['open_worker_envelopes'], MAX_REF_CHARS, false);
     checkList(errors, 'artifact_paths', e['artifact_paths'], MAX_REF_CHARS, false);
     checkList(errors, 'suggested_skills', e['suggested_skills'], MAX_REF_CHARS, false);

package/src/scripts/adr/regenerate_index.ts

@@ -23,7 +23,17 @@ const NAMED = /^ADR-(\d{3})-([a-z0-9-]+)\.md$/;
 const FM = /^---\n([\s\S]*?)\n---/;
 // ^([a-z_]+):\s*(.+?)\s*$  (MULTILINE)
 const FIELD = /^([a-z_]+):[ \t]*(.+?)[ \t]*$/gm;
-const HEAD = '| # | Title | Status | Date | Supersedes |\n|---|---|---|---|---|';
+/**
+ * The index used to render `| # | Title | Status | Date | Supersedes |`, which
+ * is forward-only: a dead ADR showed `superseded | —` and the reader learned it
+ * was dead but not by what. `superseded_by` was read nowhere despite being a
+ * documented field, and `amended_by` had no representation at all — 18 ADRs
+ * carry an amendment block and the index could not distinguish one with five
+ * amendments from one never touched.
+ */
+const HEAD =
+    '| # | Title | Status | Date | Supersedes | Superseded by | Amended by |\n' +
+    '|---|---|---|---|---|---|---|';
 
 type Meta = Record<string, string>;
 interface Row extends Meta {
@@ -182,7 +192,8 @@ export function row(r: Row): string {
     const label = 'num' in r ? `ADR-${r.num}` : (r.path as string).slice(0, -3);
     return (
         `| [${label}](${r.path}) | ${title} | ${r.status ?? '—'} ` +
-        `| ${r.date ?? '—'} | ${r.supersedes ?? '—'} |`
+        `| ${r.date ?? '—'} | ${r.supersedes ?? '—'} | ${r.superseded_by ?? '—'} ` +
+        `| ${r.amended_by ?? '—'} |`
     );
 }