@event4u/agent-config 9.9.0 → 9.10.0

package/src/config/gate-coverage.yml

@@ -0,0 +1,127 @@
+# Gate coverage manifest — the input to `check_gate_coverage.ts`.
+#
+# WHY THIS EXISTS
+# ---------------
+# On 2026-07-29 a sweep found gates that scanned a tree emptied by the ADR-051
+# flat-`src/` migration, reported success, and were wired into CI. One printed
+# `TOTAL | 0 | 0 | 0 | 0%`; another printed "All 0 auto-rule descriptions ≤ 150
+# chars"; a third "clean (0 declarer(s))". Each exited 0. A gate that inspects
+# nothing does not pass — it certifies coverage that does not exist, which is
+# worse than having no gate, because the green is believed.
+#
+# Per-case retargeting does not close this: the next migration recreates it. This
+# manifest plus the guard closes it structurally.
+#
+# THE CONTRACT (three rules, each from a real failure)
+# ----------------------------------------------------
+# 1. MACHINE-READABLE COUNT. Every listed gate emits exactly one line
+#    `scanned: <N>` (stdout or stderr), N = artefacts it actually inspected. The
+#    guard never parses a gate's human output — that would make the guard itself
+#    fragile, and a fragile guard is the thing being replaced.
+#
+# 2. CI-IDENTICAL INVOCATION. `argv` MUST match how CI/Taskfile calls the gate.
+#    A bare probe produced a false alarm during the sweep: `skill_linter` looked
+#    blind when called with no arguments, but CI passes `--all` and it scans 429
+#    artefacts. The guard must reproduce the real call or it invents defects.
+#
+# 3. BASELINE, NOT `> 0`. `min_scanned` is a floor, not a zero-check. A gate that
+#    drops from 428 artefacts to 3 is as broken as one that drops to 0, and `> 0`
+#    cannot see it. Set the floor below the true corpus (room for legitimate
+#    deletions) but far above a collapse.
+#
+# FIELDS
+#   id           script stem under src/scripts/
+#   argv         CI-identical arguments (list; empty list = bare call)
+#   min_scanned  hard floor; guard fails when the reported count is below it
+#   corpus       what the count means — so a future reader can re-derive the floor
+#   status       enforced | pending
+#                pending = not yet emitting `scanned:`. The guard REPORTS these
+#                rather than skipping silently: its own partial coverage must be
+#                visible, or it repeats the sin it exists to catch.
+gates:
+  - id: check_condensation
+    argv: []
+    min_scanned: 380
+    corpus: "src/ ↔ dist/agent-src/ .md pairs (429 at baseline: 111 rules + 318 skills)"
+    status: enforced
+
+  - id: check_augment_description_cap
+    argv: []
+    min_scanned: 80
+    corpus: "auto-type rules carrying a description (98 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree (0 -> 98). It printed
+      "All 0 auto-rule descriptions" and exited 0 in CI. Retargeting surfaced 16
+      real violations (max 189 chars); all 16 were shortened under explicit
+      operator review, with every matching term programmatically verified as
+      preserved. The cap was deliberately NOT raised to fit the violations —
+      letting a gate adapt to the as-is state is the inversion that produced three
+      blind gates in the first place.
+
+  - id: lint_load_context
+    argv: []
+    min_scanned: 180
+    corpus: "md files inspected for a load_context block: src/rules + src/agent-src/contexts + agents/settings/contexts (231 at baseline, 17 declarers)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree: 0 -> 231 files, and it
+      immediately found a real violation the blindness had hidden
+      (src/rules/model-recommendation.md declared `../contexts/…`, a disallowed
+      relative root; normalised to the canonical `contexts/…` the rule's own prose
+      already used). The count is FILES INSPECTED, not declarers — "0 declarers"
+      over 400 files is legitimate, "0 files" is blindness, and reporting declarers
+      would have hidden exactly this dead root. LEGACY_PREFIX was deliberately NOT
+      retargeted: it detects stale pre-relocation entries and must keep
+      pointing at the old form.
+
+  - id: skill_linter
+    argv: ["--all"]
+    min_scanned: 380
+    corpus: "skills + rules under artefact_roots() (429 at baseline)"
+    status: enforced
+    note: >
+      NOT blind — the manifest's regression case for rule 2. The sweep's bare
+      probe made it look blind; `--all` scans 429. Enforced precisely so that
+      changing `argv` to a bare call fails the guard instead of silently
+      reproducing the false alarm.
+
+  - id: check_no_roadmap_refs
+    argv: []
+    min_scanned: 700
+    corpus: "stable artefacts across src/{rules,skills,agent-src/*} + docs/ + agents/settings/contexts (872 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29 from the ADR-051-emptied tree. It had been enforcing the
+      no-roadmap-references rule for docs/ only while the rule + skill layer went
+      unscanned — 0 -> 872 artefacts. No violation had slipped through (verified),
+      so this closed a latent gap, not a live breach.
+
+  - id: check_context_paths
+    argv: []
+    min_scanned: 900
+    corpus: "reference corpus: src/{rules,skills,agent-src/commands,agent-src/contexts,domains} + agents/roadmaps (1170 at baseline)"
+    status: enforced
+    note: >
+      Retargeted 2026-07-29. An empty reference corpus makes every "unreferenced
+      context" verdict vacuous, which is how the dead root stayed invisible.
+
+  - id: check_site_links
+    argv: []
+    min_scanned: 20
+    unavailable_exit: 2
+    corpus: "built HTML pages under site/dist (25 content sources at baseline)"
+    status: enforced
+    note: >
+      Registered 2026-07-30 after it was caught reporting green over a stale build —
+      6 pages against 25 content sources, every source newer than the newest page.
+      The missing-dist path already exited 2; the stale path did not, so the gate
+      could pass while inspecting a build that did not contain the pages under test.
+      It now exits 2 on stale, and the floor here catches the partial-build case the
+      guard exists for. The lesson of the find is the manifest, not the gate: the
+      guard never flagged this because the gate was never listed. A sibling
+      silent-green found in the same sweep — the per-pack lint matrix, whose path was
+      a double ADR-051 casualty and which exited 0 on an empty match across 17 CI
+      shards — is NOT listed here because it was deleted rather than repaired
+      (skill_linter --all already covers all 429 artefacts in 0.5s).
+

package/src/config/preamble-payload-budget.json

@@ -0,0 +1,44 @@
+{
+    "_comment": "Per-spawn preamble payload ceiling (road-to-cache-economy Phase 3), unblocked by C-3 measuring 38.0% against a 15% bar. This is a RATCHET, not the roadmap's literal candidate numbers: those (median 40k / p95 50k) were anchored to an upstream ~37k baseline, while this package's own deterministic in-repo payload is ~102.5k tokens — a hard 40k gate would be red on the day it lands and would teach the reader to ignore it. The ratchet fails on GROWTH instead, so the number can only walk down, and the 40k/50k target stays recorded as the destination. Only the deterministic, in-repo buckets are gated: user-scope rules depend on what the developer happens to have installed globally and are therefore not CI-checkable.",
+    "schema_version": 1,
+    "registered_at": "2026-07-30",
+    "owner": "maintainer",
+    "review_by": "2027-07-30",
+    "metric": {
+        "basis": "chars/4 token estimate over the projected tree, produced by src/scripts/preamble_byte_census.ts",
+        "gated_buckets": [
+            "project-scope rules (dist/agent-src/rules/*.md)",
+            "preloaded skills catalog (name + description, dist/agent-src/skills)",
+            "CLAUDE.md hierarchy (project + project-local)"
+        ],
+        "excluded_buckets": [
+            "user-scope rules (~/.claude/rules/*.md) — machine-dependent, not CI-checkable",
+            "tool definitions + dispatch prompt — no local source carries the request payload; the census reports it as an explicit residual"
+        ]
+    },
+    "baseline_tokens": 102520,
+    "baseline_history": [
+        {
+            "tokens": 102599,
+            "at": "2026-07-30",
+            "why": "registered with the gate"
+        },
+        {
+            "tokens": 102520,
+            "at": "2026-07-31",
+            "why": "free tightening: the measured tree came in 79 tok under the registered baseline, so the ratchet walks down to meet it. Not a claimed reduction — nothing was optimised; the point of a ratchet is that a lower measurement becomes the new ceiling instead of becoming unused headroom."
+        }
+    ],
+    "headroom_pct": 5,
+    "target_tokens": {
+        "median": 40000,
+        "p95": 50000,
+        "_comment": "The roadmap's candidate numbers, kept as the destination. Reaching them needs reductions this package has not built yet; scope-dedup (C-3) removes a redundant COPY at the consumer, it does not shrink the suite itself."
+    },
+    "reference_measurements": {
+        "measured_cold_start_median_tokens": 230930,
+        "c3_scope_dedup_reduction_pct": 38,
+        "c3_condition": "FIXTURE-ONLY as of 2026-07-31: the 38% was measured on a byte-identical two-scope fixture, and that condition is currently unreachable for every consumer because install.ts:2723/2725 stamp package:/source_path: into every installed rule while the in-repo projection stamps nothing. Aligning versions yields 0/110 twins, not 110/110. The figure is the mechanism's ceiling, NOT a realised saving, and this baseline therefore assumes no dedup. Reachability is the subject of road-to-dedup-reachability; run measure_scope_dedup for the live split.",
+        "_comment": "The measured median comes from Claude Code transcripts (deduped by message.id + requestId) and is context for the ratchet, never the gated number — it moves with the developer's own session history."
+    }
+}

package/src/scripts/_cli/cmd_doctor.ts

@@ -31,7 +31,7 @@
  * offline-readiness · python-runtime · humanizer-runtime · tier-usage-readiness ·
  * council-cli · team ·
  * unsupported-combos · wizard-state · settings-review-pending ·
- * memory-merge-union.
+ * memory-merge-union · duplicate-scope-rules.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
  * `✅` / `⚠️` / `❌` / `⏭️`). `--check <id>` runs a single check.
@@ -89,6 +89,7 @@ import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
+import { censusDuplicateScope } from '../_lib/duplicate_scope_census.js';
 import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
     PROJECT_ROOT_ENV,
@@ -511,7 +512,7 @@ function splitlines(text: string): string[] {
 
 /** Python `str.rstrip()` (default whitespace, ASCII+Unicode). */
 function rstrip(s: string): string {
-    return s.replace(/[\s… ]+$/u, '');
+    return s.replace(/[\s\u0085 ]+$/u, '');
 }
 
 /** Python `value.strip().strip("'\"")` tail (after `.strip()` already done). */
@@ -762,6 +763,7 @@ const CHECK_IDS = [
     'wizard-state',
     'settings-review-pending',
     'memory-merge-union',
+    'duplicate-scope-rules',
 ] as const;
 
 /** Checks that need only the project root and run regardless of a lockfile. */
@@ -786,6 +788,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'wizard-state',
     'settings-review-pending',
     'memory-merge-union',
+    'duplicate-scope-rules',
 ]);
 
 /** Checks that genuinely cannot run without the project manifest. */
@@ -1739,6 +1742,76 @@ function _check_rule_scope_drift(project_root: string): Dict {
     };
 }
 
+/**
+ * Duplicate-scope rule detection (road-to-cache-economy Phase 3, C-2 —
+ * confirmed at 38.5% of subagent write volume on this maintainer's own
+ * checkout). When the same `.md` rule filenames are installed at BOTH the
+ * user-scope Claude Code config (`~/.claude/rules`) and the project scope,
+ * every session AND every subagent spawn injects two near-identical copies
+ * of the same rule set. This check is DETECTION ONLY: it reports the
+ * measured redundant-token estimate and names which copy is authoritative —
+ * it never deletes, rewrites, or otherwise touches a user's files (per
+ * `non-destructive-by-default`).
+ *
+ * Project scope resolves the same way the census in
+ * `cache_realization_report.ts` does: `dist/agent-src/rules` in this
+ * source repo itself (the only place the ~37% finding was measured), or the
+ * first populated {@link _RULE_PROJECTION_DIRS} entry in a consumer install.
+ * `userRulesDirOverride` exists solely so tests never touch the real
+ * `~/.claude/rules` on the machine running the suite.
+ */
+function _check_duplicate_scope_rules(project_root: string, userRulesDirOverride?: string): Dict {
+    const user_rules_dir = userRulesDirOverride ?? path.join(os.homedir(), '.claude', 'rules');
+
+    let project_rules_dir: string | null = null;
+    if (_is_source_repo(project_root)) {
+        const cand = path.join(project_root, 'dist', 'agent-src', 'rules');
+        if (isDir(cand)) project_rules_dir = cand;
+    } else {
+        for (const rel of _RULE_PROJECTION_DIRS) {
+            const cand = path.join(project_root, rel);
+            if (isDir(cand)) {
+                project_rules_dir = cand;
+                break;
+            }
+        }
+    }
+
+    if (project_rules_dir === null) {
+        return {
+            id: 'duplicate-scope-rules',
+            status: 'skipped',
+            message: 'no project-scope rule tree found (dist/agent-src/rules, .augment/rules, …) — nothing to compare against the user-scope copy',
+            remedy: '',
+        };
+    }
+
+    const census = censusDuplicateScope(user_rules_dir, project_rules_dir);
+    if (!census.evaluable) {
+        return {
+            id: 'duplicate-scope-rules',
+            status: 'ok',
+            message: census.reason ?? 'no duplicate-scope rule install detected',
+            remedy: '',
+        };
+    }
+
+    const tokens = Math.round(census.duplicate_chars / 4);
+    const rel_project = relativeTo(project_rules_dir, project_root) ?? project_rules_dir;
+    return {
+        id: 'duplicate-scope-rules',
+        status: 'warn',
+        message:
+            `${census.shared_filenames.length} rule(s) installed at BOTH user scope (${user_rules_dir}) and ` +
+            `project scope (${rel_project}) — an estimated ${tokens} redundant tokens are injected on every ` +
+            'session AND every subagent spawn (both copies are always-loaded). Project scope is authoritative ' +
+            'for this checkout.',
+        remedy:
+            'detection only — no file is modified. If the duplication is unwanted, refresh the user-scope copy ' +
+            '(e.g. `agent-config global`) to re-sync it with the project-scope version.',
+    };
+}
+
 function _check_python_runtime(): Dict {
     // Post-teardown: the package runtime is TypeScript-on-`tsx`. python3 is no
     // longer a runtime dependency, so this check no longer probes for an
@@ -2751,6 +2824,7 @@ function _run_checks(
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
         'memory-merge-union': () => _check_memory_merge_union(project_root),
+        'duplicate-scope-rules': () => _check_duplicate_scope_rules(project_root),
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2826,6 +2900,7 @@ function _run_checks_no_manifest(
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
         'memory-merge-union': () => _check_memory_merge_union(project_root),
+        'duplicate-scope-rules': () => _check_duplicate_scope_rules(project_root),
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -3308,6 +3383,7 @@ export {
     _check_offline_readiness,
     _check_stale_orphans,
     _check_rule_scope_drift,
+    _check_duplicate_scope_rules,
     _check_python_runtime,
     _check_humanizer_runtime,
     _check_mcp_beta_readiness,