@event4u/agent-config 9.25.0 → 9.26.0

package/dist/shared/nicknamePrefill.js

@@ -0,0 +1,59 @@
+/**
+ * What to put in the nickname field before the user types anything.
+ *
+ * Phase 4 step 2 of `road-to-zero-ceremony-settings`: *"Ask the nickname once,
+ * prefilled from git user name then `$USER`, so accepting is one keypress."*
+ * `src/rules/settings-ask-protocol.md` states the chain and closes it with a
+ * negation — **"Never `$USER` alone."**
+ *
+ * WHY THIS MODULE EXISTS. The rule shipped that chain; the one surface that
+ * actually prefills shipped a different one. `src/server/routes/ping.ts` read
+ * `userInfo().username` and nothing else — precisely the `$USER`-alone shape the
+ * rule forbids. A rule and the code it describes disagreeing is drift, not a
+ * preference, so the chain now has exactly one implementation and both the
+ * server route and the tests read it from here.
+ *
+ * WHY GIT COMES FIRST. `$USER` is a login handle (`mathiasberg`); `git config
+ * user.name` is the name the human chose to be called by (`Mathias Berg`). The
+ * whole point of the prefill is that accepting costs one keypress, and that only
+ * holds when the prefilled value is the one they would have typed. Note the
+ * lookup is deliberately NOT `--local`: the merged config includes
+ * `~/.gitconfig`, so the wizard still finds a name when it runs outside a repo.
+ *
+ * Pure: the git lookup is injected, so the resolver is a function of its probe
+ * alone and a test never depends on the machine it runs on — the same shape as
+ * `interactiveContext.ts` and `settingsConsent.ts`. The Node-side half (running
+ * git, falling back to `userInfo()`) lives in `src/server/nicknameResolver.ts`,
+ * because `src/shared/**` may not import Node built-ins and the lint enforces it.
+ *
+ * @see src/server/nicknameResolver.ts — the impure half
+ * @see src/rules/settings-ask-protocol.md § Worked example — the nickname
+ * @see docs/contracts/settings-classes.md
+ */
+/** Trim, and treat a whitespace-only value as absent. */
+function _clean(value) {
+    return (value ?? '').trim();
+}
+/**
+ * The prefill for the nickname ask, following the documented chain.
+ *
+ * Order is the rule's, and the negation at the end of it is the load-bearing
+ * part: `$USER` is a fallback, never the first answer.
+ */
+export function nicknamePrefill(probe) {
+    const git = _clean(probe.gitUserName);
+    if (git !== '') {
+        return { name: git, source: 'git-user-name' };
+    }
+    const user = _clean(probe.env['USER']);
+    if (user !== '') {
+        return { name: user, source: 'env-user' };
+    }
+    // Windows spells it differently; the rule names it explicitly.
+    const username = _clean(probe.env['USERNAME']);
+    if (username !== '') {
+        return { name: username, source: 'env-username' };
+    }
+    return { name: '', source: 'none' };
+}
+//# sourceMappingURL=nicknamePrefill.js.map

package/dist/shared/nicknamePrefill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nicknamePrefill.js","sourceRoot":"","sources":["../../src/shared/nicknamePrefill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAsCH,yDAAyD;AACzD,SAAS,MAAM,CAAC,KAAyB;IACrC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAChD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9C,CAAC;IACD,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/shared/settingsAsks.js

@@ -0,0 +1,128 @@
+/**
+ * The one-question budget, as a function rather than as a promise.
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`. The rule
+ * `src/rules/settings-ask-protocol.md` states the budget — at most ONE settings
+ * question per command execution, every further undecided key taking its
+ * conservative default silently and being named in the end-summary. Prose is
+ * where that obligation has to live, because no gate can count the questions in
+ * a chat turn.
+ *
+ * But the *split* is not a judgement call: given the keys an execution needs
+ * decided, which one is asked and what the others resolve to is fully
+ * determined. Leaving that determined part in prose too would mean the roadmap's
+ * own exit criterion — "a planted fixture needing three B decisions asks once,
+ * assumes two conservatively, and lists both in the summary" — had nothing to
+ * run against. So the split is computed here and the rule points at it.
+ *
+ * What this module does NOT do, stated so nobody mistakes it for the fence:
+ * it does not ask, it does not write, and it cannot stop an agent that ignores
+ * it. The write fence is one layer down and is real —
+ * `src/scripts/_cli/cmd_settings_set.ts` and the Fastify settings route both
+ * refuse every C-class key and fail closed on an unreadable class contract.
+ *
+ * Pure — no I/O, no clock, no environment.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+import { classOfPath, isConservativeDefault } from './settingsClasses.js';
+/**
+ * The end-summary line for a silently defaulted key.
+ *
+ * `--source manual` and not `jit-answer`: the user did not answer a question, so
+ * stamping the write as a just-in-time answer would record a consent nobody
+ * gave. The provenance vocabulary exists to keep exactly that distinction.
+ */
+export function changeCommand(key) {
+    return `agent-config settings:set ${key} <value> --source manual`;
+}
+/**
+ * Plan one execution's settings asks.
+ *
+ * `needed` is the keys this execution genuinely cannot proceed without, in the
+ * order they became needed — the caller's own ordering is respected because the
+ * first key to actually block the run is the one that earned the question.
+ *
+ * `decided` is every key already settled on any resolution layer. A decided key
+ * is not a candidate: re-asking a settled question is the cheap question the
+ * ask-discipline rules forbid, and it is the single most likely way this budget
+ * gets spent on nothing.
+ *
+ * `defaultOf` supplies the template default. It returns `undefined` for a key
+ * the template does not carry, which is treated as unclassified rather than as
+ * a default of `undefined` — a missing template entry is a defect, not a value.
+ */
+export function planSettingsAsks(needed, classes, defaultOf, decided = new Set(), options = {}) {
+    const plan = { ask: null, silent: [], skipped: [] };
+    const seen = new Set();
+    // Non-TTY / CI / headless: nobody can answer, so the budget is ZERO rather
+    // than one. Every candidate takes its conservative default and the plan
+    // carries no ask — "no questions, ever", as a computed fact rather than as a
+    // promise the caller has to remember. Nothing is written either: this
+    // function never persists, and with no ask there is no `jit-answer` write.
+    const interactive = options.interactive ?? true;
+    for (const key of needed) {
+        // A duplicate in the caller's list must not consume the budget twice.
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        if (decided.has(key)) {
+            plan.skipped.push({ key, reason: 'already-decided' });
+            continue;
+        }
+        const cls = classOfPath(classes, key);
+        if (cls === undefined) {
+            // Unclassified is guarded everywhere else in this system; it is
+            // guarded here too. Never fall back to "probably fine".
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+        if (cls === 'A') {
+            plan.skipped.push({ key, reason: 'class-a-never-asked' });
+            continue;
+        }
+        if (cls === 'C') {
+            // A C key set to `ask` still produces a RUNTIME question, but that
+            // answer lasts one run and is never persisted, so it is not this
+            // budget's business. Persisting it stays on the human path.
+            plan.skipped.push({ key, reason: 'class-c-guarded' });
+            continue;
+        }
+        const fallback = defaultOf(key);
+        if (fallback === undefined) {
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+        if (interactive && plan.ask === null) {
+            plan.ask = key;
+            continue;
+        }
+        if (!isConservativeDefault(fallback)) {
+            // Taking a permissive value silently would be a decision made in
+            // the user's name — the one outcome the Iron Law names outright.
+            // Surfacing it as skipped forces the caller to deal with it instead
+            // of inheriting a permission nobody granted.
+            plan.skipped.push({ key, reason: 'non-conservative-default' });
+            continue;
+        }
+        plan.silent.push({ key, value: fallback, command: changeCommand(key) });
+    }
+    return plan;
+}
+/**
+ * The end-summary block for a plan, or `null` when nothing was defaulted.
+ *
+ * `null` rather than an empty string so a caller cannot append a heading with no
+ * rows under it. This text rides INSIDE the single end-summary that
+ * `direct-answers` already requires — it is never a second summary.
+ */
+export function silentDefaultsSummary(plan) {
+    if (plan.silent.length === 0) {
+        return null;
+    }
+    const lines = plan.silent.map((s) => `- \`${s.key}\` → ${JSON.stringify(s.value)} (default) · change: \`${s.command}\``);
+    return `Settings resolved without asking this run:\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=settingsAsks.js.map

package/dist/shared/settingsAsks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsAsks.js","sourceRoot":"","sources":["../../src/shared/settingsAsks.ts"],"names":[],"mappings":"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"}

package/dist/shared/settingsConsent.js

@@ -0,0 +1,93 @@
+/**
+ * Is a permissive B-class value a RECORDED CONSENT, or just a value?
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`, and the answer to that
+ * roadmap's Risk 3 — *"the provenance stamp becomes decoration; an unread stamp
+ * is cost with no return"*. Before this module the sidecar
+ * `settings/.agent-settings.provenance.json` was written by `settings:set` and
+ * read by exactly one caller, the GUI, to **display** it. Nothing decided
+ * anything on it. This is the reader that makes it load-bearing.
+ *
+ * The distinction it draws, which a bare value cannot: `true` that a human chose
+ * and `true` that the machine inferred are the same byte and are not the same
+ * permission. `auto-detected` is the provenance a machine writes about itself —
+ * a locale, an installed binary, a detected host. Letting it grant a consent
+ * would mean the agent could arrive at its own permission by observing the
+ * world, which is the confused-deputy shape in miniature.
+ *
+ * Modelled on `src/scripts/hooks/block_unauthorized_git.ts`: answer from a
+ * recorded fact rather than from the model's recollection, and treat a missing
+ * record as NOT granted rather than as probably-fine.
+ *
+ * WHAT THIS IS NOT. It is not a hook and it does not intercept anything. No
+ * B-class key currently gates an action through a guard — the two that gate
+ * behaviour at all (`personal.open_edited_files`, `memory.learn_on_session_end`)
+ * are read as values by the installer, the wizard and one session_end concern,
+ * and the *action* they govern is prose. So the enforcement gradient is honest
+ * and steep: this function is deterministic, the obligation to call it is
+ * model-carried, and on a prose-only host ask-once can degrade to ask-never.
+ *
+ * Pure — no I/O. Callers supply the value and the sidecar entry.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+import { isConservativeDefault } from './settingsClasses.js';
+/**
+ * The sources that can carry a human decision.
+ *
+ * `jit-answer` is a question the user answered. `gui` is a human at the settings
+ * editor. `manual` is a hand-edit or an explicit CLI write on the user's
+ * instruction. `auto-detected` is excluded on purpose — see the module header.
+ */
+const HUMAN_SOURCES = ['jit-answer', 'gui', 'manual'];
+/**
+ * The verdict for one consent-gated action.
+ *
+ * Order matters: class first (a C key never reaches a consent question at all),
+ * then the value (conservative means no, regardless of provenance), then the
+ * record.
+ */
+export function consentVerdict(query) {
+    if (query.cls !== 'B') {
+        return 'not-a-consent-key';
+    }
+    if (isConservativeDefault(query.value)) {
+        return 'withheld-default';
+    }
+    if (query.handEdited === true) {
+        return 'granted';
+    }
+    if (query.source === undefined) {
+        return 'withheld-unrecorded';
+    }
+    if (!HUMAN_SOURCES.includes(query.source)) {
+        return 'withheld-machine-inferred';
+    }
+    return 'granted';
+}
+/** `true` only for `granted` — every other verdict withholds. */
+export function consentGranted(query) {
+    return consentVerdict(query) === 'granted';
+}
+/**
+ * One line explaining a withheld verdict, for the surface that refused.
+ *
+ * `null` for `granted`, so a caller cannot accidentally print a refusal reason
+ * on the allow path.
+ */
+export function withheldReason(verdict, key) {
+    switch (verdict) {
+        case 'granted':
+            return null;
+        case 'withheld-default':
+            return `${key} is at its conservative default — absent and no are the same answer.`;
+        case 'withheld-unrecorded':
+            return `${key} permits this, but nothing records who decided it. Ask, or set it via the GUI.`;
+        case 'withheld-machine-inferred':
+            return `${key} was auto-detected, not decided. A machine inference is not a consent.`;
+        case 'not-a-consent-key':
+            return `${key} is not a class-B consent key — this gate does not apply to it.`;
+    }
+}
+//# sourceMappingURL=settingsConsent.js.map

package/dist/shared/settingsConsent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsConsent.js","sourceRoot":"","sources":["../../src/shared/settingsConsent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,qBAAqB,EAAsB,MAAM,sBAAsB,CAAC;AAKjF;;;;;;GAMG;AACH,MAAM,aAAa,GAA6B,CAAC,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAsChF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAC9C,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;QACpB,OAAO,mBAAmB,CAAC;IAC/B,CAAC;IACD,IAAI,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,OAAO,kBAAkB,CAAC;IAC9B,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,qBAAqB,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,OAAO,2BAA2B,CAAC;IACvC,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,KAAmB;IAC9C,OAAO,cAAc,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAuB,EAAE,GAAW;IAC/D,QAAQ,OAAO,EAAE,CAAC;QACd,KAAK,SAAS;YACV,OAAO,IAAI,CAAC;QAChB,KAAK,kBAAkB;YACnB,OAAO,GAAG,GAAG,sEAAsE,CAAC;QACxF,KAAK,qBAAqB;YACtB,OAAO,GAAG,GAAG,gFAAgF,CAAC;QAClG,KAAK,2BAA2B;YAC5B,OAAO,GAAG,GAAG,wEAAwE,CAAC;QAC1F,KAAK,mBAAmB;YACpB,OAAO,GAAG,GAAG,iEAAiE,CAAC;IACvF,CAAC;AACL,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.25.0",
+    "version": "9.26.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/agents-paths.yml

@@ -114,6 +114,21 @@
   writer: /team-knowledge:bootstrap skill
   rationale: Deterministic template pages; review-then-commit flow (nothing here is the artifact)
 
+# ---------------------------------------------------------------------------
+# Self-improvement proposals (TRACKED — listed for classification, not ignored)
+# ---------------------------------------------------------------------------
+
+- path: /agents/proposals/
+  scope: both
+  policy: tracked
+  writer: learning-to-rule-or-skill skill (drafts) → upstream-contribute (PR)
+  rationale: |
+    Proposal drafts must be committed — the proposal-drift workflow reads their
+    stage: frontmatter in CI, and upstream-contribute opens a PR from them. Listed
+    here because agents-layout.md requires every new top-level agents/ entry to
+    appear in this manifest; the entry is inert for the gitignore gate, which reads
+    policy: ignored only.
+
 # ---------------------------------------------------------------------------
 # Ghostwriter profiles
 # ---------------------------------------------------------------------------

package/src/config/gate-coverage.yml

@@ -44,7 +44,7 @@
 # ----------------------------------------------------------
 # 240 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
 # (the count is computed, not asserted — `check_gate_coverage.count_gate_scripts`).
-# **31 of them emit the machine-readable `scanned: <N>` line under their
+# **32 of them emit the machine-readable `scanned: <N>` line under their
 # CI-identical argv, and all 31 are listed below.** The manifest is therefore
 # complete with respect to its own contract, and covers ~13 % of the population.
 #
@@ -599,3 +599,31 @@ gates:
       check_kernel_prefix_stability). The canary is what distinguishes that from
       a gate scanning nothing — it plants the removal-permitting class with no
       evidence and the gate reds.
+
+  - id: check_corpus_staleness
+    argv: ["--quiet", "--today", "2026-08-06"]
+    min_scanned: 5
+    corpus: "src/skills/*/data/manifest.json — grounding-corpus manifests (6 at baseline; brand, database, accessibility-auditor, api-design, design-intelligence, threat-modeling)"
+    status: enforced
+    canary:
+      class: missing-declared-csv
+      path: src/skills/zz-canary-corpus/data/manifest.json
+      content: |
+        {
+          "manifest_version": 1,
+          "refresh_cadence": "quarterly",
+          "upstream": { "last_checked": "2026-07-01" },
+          "domains": { "d": { "file": "nope.csv", "search_cols": ["a"], "output_cols": ["b"] } }
+        }
+    note: >
+      `--today` is PINNED in argv on purpose, and it is the whole reason this
+      gate is testable at all: the five upstream-vendored corpora share
+      `last_checked: 2026-06-07`, so an unpinned reference date makes this row
+      flip from green to red on 2026-09-15 with no diff behind it. The pinned
+      date keeps the coverage guard measuring COVERAGE; the real calendar check
+      is the workflow step, which runs unpinned and is meant to red when the
+      cadence is actually missed. Changing the pin is how you re-baseline after a
+      re-vendor, and it should be visible in a diff.
+      The canary plants a manifest whose declared CSV does not exist — the exact
+      gap `corpus-grounding/scripts/schema_validator.ts` leaves open, since it
+      computes the path and never opens the file.

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

@@ -1,36 +1,42 @@
 {
-  "$comment": "Violation ratchet for gates whose dead scan root was repaired. A repair REVEALS pre-existing debt; it does not create it. Each entry records the count revealed at repair time \u2014 the gate fails only when its count RISES. Lowering a count is a normal commit; raising one is a defect. Entries expire: a baseline that has not dropped within 56 days of `landed` (or of `reaffirmed.date`) fails its gate, because a number that never moves is suppression with extra steps. Mechanism + rationale: src/scripts/_lib/gate_baseline.ts. Decision: AI council 2026-08-02, roadmap road-to-gates-that-can-fail blocker `dead-gate-finding-triage`.",
+  "$comment": "Violation ratchet for gates whose dead scan root was repaired. A repair REVEALS pre-existing debt; it does not create it. Each entry records the count revealed at repair time — the gate fails only when its count RISES. Lowering a count is a normal commit; raising one is a defect. Entries expire: a baseline that has not dropped within 56 days of `landed` (or of `reaffirmed.date`) fails its gate, because a number that never moves is suppression with extra steps. Mechanism + rationale: src/scripts/_lib/gate_baseline.ts. Decision: AI council 2026-08-02, roadmap road-to-gates-that-can-fail blocker `dead-gate-finding-triage`.",
   "gates": {
     "check_no_new_legacy_path:hardcoded-scan-roots": {
       "count": 49,
       "landed": "2026-08-04",
-      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` \u2014 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 \u2192 147 string-literal lines \u2192 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 \u2014 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 \u2014 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\u219251 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\u219249 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver \u2014 two gates that had been reading the retired container and scoring 0 of 288 skills."
+      "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."
     },
     "audit_user_type_axis": {
       "count": 1,
       "landed": "2026-08-02",
-      "note": "One orphan user-type value: `legal`. Five legal-review-prep skills (contract-review, dpa-review, nda-triage, legal-intake-triage, legal-practice-profile) declare `recommended_for_user_types: [legal]`, but there is no `user-types/legal.yml` \u2014 the pack shipped an axis value with no user-type definition behind it, and the dead scan root hid it (the audit reported used=0 orphans=0 while reading zero skills; it now reads 288 and reports used=8). Clearing this entry is a product call, not a copy edit: either author `user-types/legal.yml` (tagline, recommended packs, install-path hint) or drop `legal` from those five skills. Not decided here because both options change shipped pack behaviour."
+      "note": "One orphan user-type value: `legal`. Five legal-review-prep skills (contract-review, dpa-review, nda-triage, legal-intake-triage, legal-practice-profile) declare `recommended_for_user_types: [legal]`, but there is no `user-types/legal.yml` — the pack shipped an axis value with no user-type definition behind it, and the dead scan root hid it (the audit reported used=0 orphans=0 while reading zero skills; it now reads 288 and reports used=8). Clearing this entry is a product call, not a copy edit: either author `user-types/legal.yml` (tagline, recommended packs, install-path hint) or drop `legal` from those five skills. Not decided here because both options change shipped pack behaviour."
     },
     "lint_handoffs": {
       "count": 18,
       "landed": "2026-08-02",
-      "note": "All 18 are `handoff_tier_mismatch`: a senior-tier skill links to a peer whose frontmatter carries no `tier` (reported as tier='unset') \u2014 e.g. build-buy-partner \u2192 adr-create, customer-research \u2192 po-discovery, gated-reach \u2192 threat-modeling. This is a tier-metadata backfill backlog on the LINKED-TO skills, not a broken link. The one genuinely dangling link revealed by the same repair (competitive-positioning \u2192 a non-existent ../analyze-reference-repo/SKILL.md; it is a command, not a skill) was FIXED in the repairing commit rather than baselined. Clearing this entry means backfilling `tier` on the linked-to skills, or deciding that `tier: unset` on a link target is not a violation and narrowing the rule."
+      "note": "All 18 are `handoff_tier_mismatch`: a senior-tier skill links to a peer whose frontmatter carries no `tier` (reported as tier='unset') — e.g. build-buy-partner → adr-create, customer-research → po-discovery, gated-reach → threat-modeling. This is a tier-metadata backfill backlog on the LINKED-TO skills, not a broken link. The one genuinely dangling link revealed by the same repair (competitive-positioning → a non-existent ../analyze-reference-repo/SKILL.md; it is a command, not a skill) was FIXED in the repairing commit rather than baselined. Clearing this entry means backfilling `tier` on the linked-to skills, or deciding that `tier: unset` on a link target is not a violation and narrowing the rule."
     },
     "lint_pack_boundaries": {
       "count": 337,
       "landed": "2026-08-02",
-      "note": "Markdown links between source artefacts that cross a pack boundary the source pack's `requires` graph does not reach \u2014 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 \u2014 top bucket 22%, no single systematic cause \u2014 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."
+      "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 \u2014 the number may not grow, so a NEW gate must adopt or exempt.",
+      "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.",
       "falsifier": "./scripts-run src/scripts/check_gate_completeness"
     },
     "check_depth_budget": {
       "count": 4,
       "landed": "2026-08-06",
-      "note": "Four depth files exceed the 16,000-char per-file ceiling: rule-body-migration-inventory.md (23,782), design-antipatterns.md (20,707), roadmap-process-loop.md (20,360), orchestration-telemetry.md (16,155). Recorded rather than fixed because splitting four large reference documents is unrelated to the change that introduced the ceiling, and a gate that lands as four instant blockers is the shape this repository has already recorded as a failure. Shrink-only from here: a FIFTH over-ceiling file reds. roadmap-process-loop.md is the file that motivated the gate \u2014 it states 'Size budget: <= 4,000 chars' in its own header and is 5x over it, which is what a declared budget with nothing measuring it decays into. The ceiling is a GROWTH RATCHET, not a measured quality threshold: the 7,308-trajectory study behind the 3,500-token skill ceiling (ADR-217) was taken on procedural always-co-loaded skills, and this layer is declarative and loaded one or two files at a time. Replace the number when someone measures comprehension on THIS layer."
+      "note": "Four depth files exceed the 16,000-char per-file ceiling: rule-body-migration-inventory.md (23,782), design-antipatterns.md (20,707), roadmap-process-loop.md (20,360), orchestration-telemetry.md (16,155). Recorded rather than fixed because splitting four large reference documents is unrelated to the change that introduced the ceiling, and a gate that lands as four instant blockers is the shape this repository has already recorded as a failure. Shrink-only from here: a FIFTH over-ceiling file reds. roadmap-process-loop.md is the file that motivated the gate — it states 'Size budget: <= 4,000 chars' in its own header and is 5x over it, which is what a declared budget with nothing measuring it decays into. The ceiling is a GROWTH RATCHET, not a measured quality threshold: the 7,308-trajectory study behind the 3,500-token skill ceiling (ADR-217) was taken on procedural always-co-loaded skills, and this layer is declarative and loaded one or two files at a time. Replace the number when someone measures comprehension on THIS layer."
+    },
+    "gate-self-test:registered-non-adopters": {
+      "count": 24,
+      "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"
     }
   }
 }

package/src/scripts/_cli/cmd_route_audit.ts

@@ -36,8 +36,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { match_prompt, type Router } from '../_lib/router_match.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
 import { read_entries } from '../chat_history.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// Marker-anchored, not hop-counted — see the sibling note in cmd_route_explain.ts.
+// Both routing commands were the last two `_cli` entries still counting hops.
+const REPO_ROOT = resolvePackageRoot(import.meta.url);
 const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
 
 // cache-version: v1 — rebuildable audit log: delete-and-rerun rebuilds it from

package/src/scripts/_cli/cmd_route_explain.ts

@@ -31,8 +31,16 @@ import {
 } from '../_lib/router_match.js';
 import { measure, method_note } from '../_lib/token_count.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
 
-const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// Marker-anchored, not hop-counted: this module runs from `src/scripts/_cli/`
+// (three levels down) AND from the precompiled `dist/cli-delegate/` (two), and
+// a fixed hop count is right in exactly one of them. Three hops from the bundle
+// landed on `<pkg>/..` — `node_modules/@event4u` for a scoped install — so
+// `route:explain` and `route:audit` reported dist/router.json as missing on
+// every invocation through the shipped binary while both worked under `tsx`.
+// The resolver exists precisely for this and 12 sibling commands already use it.
+const REPO_ROOT = resolvePackageRoot(import.meta.url);
 const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
 const RULES_DIST_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'rules');
 

package/src/scripts/ai-video/stitch.sh

@@ -10,7 +10,10 @@
 #   stitch.sh <manifest.json> <output.mp4>
 #               [--skip-scene <id> ...]
 #               [--abort-on-missing | --continue]
-#               [--crossfade <seconds>]
+#
+# NOT a flag: --crossfade. It is parsed and REFUSED (exit 2). See
+# "Refused flags" below — it is listed so a caller who read the old
+# usage line gets an error instead of a hard cut.
 #
 # Failure semantics:
 #   - Missing clip → fail loud with scene_id and re-render hint
@@ -21,6 +24,22 @@
 #     <project>/scenes/<id>/error.json; stitch.sh checks for that
 #     file alongside the clip and surfaces it instead of an opaque
 #     ffmpeg error.
+#
+# Refused flags:
+#   --crossfade <seconds> — accepted by the parser, then REFUSED with
+#     exit 2 before any work. It used to print "not yet implemented"
+#     to stderr and fall straight through to the plain concat, so the
+#     script reported success (exit 0, success JSON) while delivering a
+#     hard cut. Worse, the notice sat AFTER the dry-run exit, and
+#     AIV_DRYRUN defaults to true — so in the default mode the flag was
+#     accepted in total silence.
+#     A crossfade is not a small addition here: the output path is
+#     `-f concat -c copy`, and stream copy precludes any filtergraph, so
+#     xfade/acrossfade need a re-encode path that does not exist. It was
+#     also never reachable from a governed surface: /video:stitch passes
+#     only --skip-scene and --continue and rejects anything else. So the
+#     honest state is a refusal, not a silent downgrade and not a
+#     filtergraph shipped into a script with no test harness.
 
 set -euo pipefail
 
@@ -39,19 +58,23 @@ esac
 MANIFEST="${1:-}"
 OUTPUT="${2:-}"
 [ -n "${MANIFEST}" ] && [ -n "${OUTPUT}" ] \
-  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue] [--crossfade <s>]"
+  || aiv_die 2 "usage: stitch.sh <manifest.json> <output.mp4> [--skip-scene <id>] [--abort-on-missing|--continue]"
 [ -r "${MANIFEST}" ] || aiv_die 2 "manifest not readable: ${MANIFEST}"
 shift 2 || true
 
 SKIP_IDS=""
 MISSING_POLICY="abort"
-CROSSFADE=""
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --skip-scene) SKIP_IDS="${SKIP_IDS} ${2:-}"; shift 2 ;;
     --abort-on-missing) MISSING_POLICY="abort"; shift ;;
     --continue) MISSING_POLICY="continue"; shift ;;
-    --crossfade) CROSSFADE="${2:-}"; shift 2 ;;
+    --crossfade)
+      # Refused HERE — before the dry-run branch, before ffmpeg, before any
+      # output. The old code warned after the dry-run exit and then concatenated
+      # anyway, so a caller asking for a crossfade got a hard cut and exit 0.
+      aiv_die 2 "stitch.sh: --crossfade is not implemented and will not be silently downgraded. The output path is 'ffmpeg -f concat -c copy', and stream copy precludes any filtergraph, so xfade/acrossfade require a re-encode path this script does not have. Re-run without --crossfade for a hard-cut concat, or open a roadmap item for the re-encode path."
+      ;;
     *) aiv_die 2 "stitch.sh: unknown flag '$1'" ;;
   esac
 done
@@ -149,11 +172,6 @@ if [ "${DRYRUN_FLAG}" -eq 1 ]; then
   exit 0
 fi
 
-if [ -n "${CROSSFADE}" ]; then
-  printf 'stitch: crossfade=%ss requested — passing through ffmpeg xfade filter not yet implemented (concat path used)\n' \
-    "${CROSSFADE}" >&2
-fi
-
 ffmpeg -loglevel error -y -f concat -safe 0 -i "${CONCAT_LIST}" \
   -c copy "${OUTPUT}" >/dev/null \
   || aiv_die 8 "ffmpeg concat failed (manifest=${MANIFEST}, output=${OUTPUT})"

package/src/scripts/before_complete_hook.ts

@@ -205,10 +205,17 @@ const _VACUOUS_PATTERNS: readonly RegExp[] = [
 export function isVacuousOutput(output: string): boolean {
   const text = output.trim();
   if (!text) {
-    // A verification command that printed nothing at all is not evidence either.
-    return true;
+    // Silence is the Unix convention for success: a clean `tsc --noEmit`,
+    // `eslint`, or `phpstan` prints nothing. Round 2 caught this reading empty
+    // output as vacuity, which quietly stopped counting the most common green
+    // signal in this repo. Genuinely unreadable CI polls are handled separately
+    // (`pendingCount` returns null and the poll counts for nothing).
+    return false;
   }
-  return _VACUOUS_PATTERNS.some((re) => re.test(text));
+  // Per RESULT LINE, not per blob: a composite run whose 812 tests passed and
+  // whose one empty sub-package printed "No test files found" is evidence.
+  const lines = text.split("\n").filter((l) => l.trim());
+  return lines.every((l) => _VACUOUS_PATTERNS.some((re) => re.test(l)));
 }
 
 /** Commands that poll CI state rather than produce a local result. */
@@ -228,8 +235,20 @@ export function pendingCount(output: string): number | null {
     return Number(m[1]);
   }
   // `gh pr checks` prints one row per check; count the in-progress markers.
+  // `gh pr checks` prints one row per check (`name\tpass\t1m2s\t…`). Count the
+  // in-flight rows; a table with rows but none pending IS a settle, which the
+  // first version could not see because it returned null and never counted.
   const rows = output.match(/^\S.*\b(pending|in_progress|queued)\b/gim);
-  return rows ? rows.length : null;
+  if (rows) {
+    return rows.length;
+  }
+  if (/\bno checks reported\b/i.test(output)) {
+    return null; // the push→registration gap — not a settle
+  }
+  if (/^\S+\s+(pass|fail|skipping|successful|failing)\b/im.test(output)) {
+    return 0; // a real result table with no in-flight rows
+  }
+  return null;
 }
 
 /**