@event4u/agent-config 9.13.0 → 9.15.0

package/src/scripts/lint_framework_leakage.ts

@@ -224,7 +224,19 @@ function _is_carve_out_pointer_line(line: string): boolean {
 const SHAPE_EXAMPLE_RE =
     /\((?:Laravel|Symfony|Django|Rails|Next\.js)[^)]*\b(?:shape|example)\b|\b(?:Laravel|Symfony|Django|Rails) (?:shape|example):/i;
 
-const FRONTMATTER_FRAMEWORK_RE = /^---\s*\n([\s\S]*?)\n---/m;
+/**
+ * Real frontmatter only — the block that OPENS the file, not any `---` fence.
+ *
+ * This carried `/m` with no start-of-file guard, the only such parser in the
+ * suite (every sibling anchors at index 0). With `/m`, a file that has no
+ * leading frontmatter latched onto the first `---`-delimited span anywhere in
+ * its body — and since a non-null match makes the caller `continue`, the whole
+ * file was then exempted from leakage scanning. What collides with it is the
+ * house convention of quoting a `---`-fenced frontmatter EXAMPLE in prose: one
+ * such example carrying a `framework:` line silently disarms the gate for that
+ * file (road-to-gates-that-can-fail Phase 6.2, finding 4).
+ */
+const FRONTMATTER_FRAMEWORK_RE = /^---[ \t]*\n([\s\S]*?)\n---/;
 const FRAMEWORK_KEY_RE = /^(?:framework|\s+framework)\s*:\s*(\S+)/m;
 
 export function is_carve_out(p: string): boolean {
@@ -246,11 +258,12 @@ export function is_inventory_file(p: string): boolean {
     if (parts.includes('contexts')) {
         return true;
     }
-    if (
-        path.basename(rel) === 'README.md' &&
-        parts.length === 2 &&
-        (parts[0] === '.agent-src.uncondensed' || parts[0] === 'dist/agent-src')
-    ) {
+    // DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1). Both comparisons
+    // were unreachable: `.agent-src.uncondensed` was deleted by ADR-051, and
+    // `'dist/agent-src'` can never equal a single `/`-split segment. So the
+    // inventory-README exemption never fired for any file, and the real
+    // inventory file (`src/agent-src/README.md`) got no exemption at all.
+    if (path.basename(rel) === 'README.md' && parts.length === 3 && parts[0] === 'src') {
         return true;
     }
     return false;
@@ -504,8 +517,13 @@ export function main(argv?: readonly string[]): number {
     const file_hits: Array<[string, Hit[]]> = [];
     let total_hits = 0;
     let allowlisted_total = 0;
+    // gate-coverage contract (src/config/gate-coverage.yml): files actually
+    // inspected. NOTE the "N files" in the human summary is files WITH HITS —
+    // reading that as coverage is exactly how a blind gate looks healthy.
+    let scannedFiles = 0;
 
     for (const f of iter_md_files(args.paths)) {
+        scannedFiles += 1;
         if (is_carve_out(f)) {
             continue;
         }
@@ -580,6 +598,7 @@ export function main(argv?: readonly string[]): number {
         `\n${total_hits} hits across ${file_hits.length} files ` +
             `(${allowlisted_total} allowlisted)\n`,
     );
+    process.stderr.write(`scanned: ${String(scannedFiles)}\n`);
     return total_hits ? 1 : 0;
 }
 

package/src/scripts/lint_handoffs.ts

@@ -16,9 +16,20 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const SKILLS_DIR = path.join(REPO, '.agent-src.uncondensed', 'skills');
+/**
+ * ADR-051 moved skill authoring to `src/skills`. Until 2026-08-02 this default
+ * still named the retired pre-ADR-051 source container, so the CLI walked a
+ * missing directory and printed "no violations under <that root>" while
+ * reading zero files. Resolved through the shared resolver so the next root
+ * move updates every consumer at once.
+ */
+const SKILLS_DIR = SRC_SKILLS();
 
 /** Mirror `QUIET = "--quiet" in sys.argv` (computed at import). */
 const QUIET = process.argv.slice(2).includes('--quiet');
@@ -369,11 +380,32 @@ export function main(argv?: readonly string[]): number {
     if (args.length > 0) {
         skills_dir = _resolve(args[0] as string);
     }
+    const isDefaultRoot = skills_dir === SKILLS_DIR;
+
+    // Scope assertion: zero skill files means the root moved, not that the
+    // corpus is clean. This is the state the gate shipped in until 2026-08-02.
+    const scanned = _rglobSkillMd(skills_dir).length;
+    try {
+        assertScanned({
+            gate: 'lint_handoffs',
+            scanned,
+            units: 'skill file(s)',
+            roots: [_relTo(skills_dir, REPO)],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
+
     const violations = lint(skills_dir);
     if (violations.length === 0) {
         if (!QUIET) {
             process.stdout.write(
-                `✅  lint_handoffs: no violations under ${_relTo(skills_dir, REPO)}\n`,
+                `✅  lint_handoffs: no violations under ${_relTo(skills_dir, REPO)} ` +
+                    `(${scanned} skill file(s) scanned)\n`,
             );
         }
         return 0;
@@ -381,6 +413,21 @@ export function main(argv?: readonly string[]): number {
     for (const v of violations) {
         process.stdout.write(_render(v, REPO) + '\n');
     }
+    // Ratchet applies to the repo corpus only — an explicit fixture root is
+    // judged on its own findings, never against the repo's recorded debt.
+    if (isDefaultRoot) {
+        const verdict = checkRatchet({
+            gate: 'lint_handoffs',
+            actual: violations.length,
+            repoRoot: REPO,
+        });
+        if (verdict.ok) {
+            process.stdout.write(`\n⚠️   ${verdict.message}\n`);
+            return 0;
+        }
+        process.stderr.write(`\n❌  ${verdict.message}\n`);
+        return 1;
+    }
     process.stderr.write(`\n❌  lint_handoffs: ${violations.length} violation(s)\n`);
     return 1;
 }

package/src/scripts/lint_media_policy_linkage.ts

@@ -6,35 +6,57 @@
  * Phase 4 / Wave 4b). The CLI contract is pinned — `--quiet`
  * flag read from argv at module load, scan roots + policy ordering (policies
  * sorted; scan files via rglob), finding messages, output channel (all on
- * stdout except the final orphan summary on stderr), exit codes. No
- * behaviour changes — historical quirks preserved (consumers pin the exact behaviour). (note: `POLICY_DIR` /
- * `SCAN_ROOTS` point at `agents/policies/media`, matching the .py).
+ * stdout except the final orphan summary on stderr), exit codes.
  *
- * Every policy file under `agents/policies/media/` (except README) must be
- * linked from at least one of a skill SKILL.md, a routing rule, or a sibling
- * policy file. A policy that no surface references is a silent — failed — policy.
+ * Every policy file under `agents/settings/policies/media/` (except README)
+ * must be linked from at least one of a skill SKILL.md, a routing rule, or a
+ * sibling policy file. A policy that no surface references is a silent —
+ * failed — policy.
  *
- * Exit codes: 0 all policies linked, 1 one or more orphan policies.
+ * The inherited `POLICY_DIR` and `SCAN_ROOTS` were faithful ports of the .py's
+ * paths, and every one of them was stale: the policy root was a level too
+ * shallow and the referrer roots named the pre-ADR-051 container. Repaired
+ * 2026-08-02; see the constants below.
+ *
+ * Exit codes: 0 all policies linked, 1 one or more orphan policies, 2 dead scope.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.includes('--quiet');
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const POLICY_DIR = path.join(REPO, 'agents', 'policies', 'media');
+/**
+ * The policies whose reachability is being checked.
+ *
+ * This named `agents/policies/media` while the policies have always lived one
+ * level deeper, under `agents/settings/policies/media` — the gate's own
+ * "…/settings/policies/media/ missing" message named the right path while the
+ * constant named the wrong one. Result: `main()` took the missing-dir early
+ * return and exited 0 without checking a single policy.
+ */
+const POLICY_DIR = path.join(REPO, 'agents', 'settings', 'policies', 'media');
 const EXEMPT_STEMS: ReadonlySet<string> = new Set(['README']);
 
-// Surfaces scanned for inbound references to policy files.
+/**
+ * Surfaces scanned for inbound references to policy files.
+ *
+ * Three of these named the pre-ADR-051 source container and a fourth named
+ * `.claude/skills`, a generated projection absent from this repo — so the
+ * reference scan read nothing either. Now the real authoring roots (a command
+ * is `src/domains/<pack>/<subpath>/command.md`, hence the domains root) plus
+ * the policy directory itself, since a sibling policy is a valid referrer.
+ */
 const SCAN_ROOTS: readonly string[] = [
-    path.join(REPO, '.agent-src.uncondensed', 'skills'),
-    path.join(REPO, '.agent-src.uncondensed', 'rules'),
-    path.join(REPO, '.agent-src.uncondensed', 'commands'),
-    path.join(REPO, '.claude', 'skills'),
-    path.join(REPO, 'agents', 'policies', 'media'),
+    path.join(REPO, 'src', 'skills'),
+    path.join(REPO, 'src', 'rules'),
+    path.join(REPO, 'src', 'domains'),
+    POLICY_DIR,
 ];
 
 function _exists(p: string): boolean {
@@ -165,24 +187,34 @@ function referrers_for(policy: string, scanFiles: readonly string[]): string[] {
 }
 
 function main(): number {
-    if (!_exists(POLICY_DIR)) {
-        emit(
-            'media-policy-linkage: agents/settings/policies/media/ missing — ' +
-                'nothing to lint.',
-        );
-        return 0;
-    }
-
+    // Scope assertions replace the two silent early returns this gate used to
+    // take. Both are deliberately WITHOUT `allowEmpty`: "the policy directory
+    // is missing" was not a benign optional-surface case here, it was the bug —
+    // the constant pointed one level too shallow and the gate green-lit an
+    // unchecked policy set for as long as it has existed.
     const policies = collect_policies();
-    if (policies.length === 0) {
-        emit(
-            'media-policy-linkage: agents/settings/policies/media/ has no policy ' +
-                'files — nothing to lint.',
-        );
-        return 0;
+    const scanFiles = collect_scan_files();
+    try {
+        assertScanned({
+            gate: 'lint_media_policy_linkage',
+            scanned: policies.length,
+            units: 'policy file(s)',
+            roots: [_relToPosix(POLICY_DIR, REPO)],
+        });
+        assertScanned({
+            gate: 'lint_media_policy_linkage',
+            scanned: scanFiles.length,
+            units: 'referrer-candidate file(s)',
+            roots: SCAN_ROOTS.map((r) => _relToPosix(r, REPO)),
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
     }
 
-    const scanFiles = collect_scan_files();
     const orphans: string[] = [];
     for (const policy of policies) {
         const referrers = referrers_for(policy, scanFiles);
@@ -209,7 +241,7 @@ function main(): number {
 
     emit(
         `media-policy-linkage: ${policies.length} policy file(s) — all ` +
-            `linked.`,
+            `linked (${scanFiles.length} file(s) scanned for referrers).`,
     );
     return 0;
 }

package/src/scripts/lint_namespace.ts

@@ -18,10 +18,18 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import {
+    SRC_AGENT,
+    SRC_RULES,
+    SRC_SKILLS,
+    iter_commands,
+    logical_relpath,
+} from './_lib/agent_src.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const SRC = path.join(ROOT, '.agent-src.uncondensed');
 
 // Source-of-truth regex; mirrored in docs/contracts/namespace.md § 1.
 const NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -44,14 +52,65 @@ interface Target {
     subVerb: boolean;
 }
 
+/**
+ * ADR-051 moved every one of these roots out of the pre-ADR-051 source
+ * container. Until 2026-08-02 the table still named it, so `scan()` skipped
+ * all four `_isDir` checks and reported `BASELINE: 0 issues · 0 name(s)
+ * checked` — a green verdict over an empty corpus.
+ *
+ * Commands are NOT in this table: they no longer live in one flat directory.
+ * `src/domains/<pack>/<subpath>/command.md` is walked by `_command_targets()`
+ * below, which reconstructs the same name/sub-verb semantics from the logical
+ * command path.
+ */
 const TARGETS: Target[] = [
-    { kind: 'skill', root: path.join(SRC, 'skills'), glob: '*/SKILL.md', depth: 1, subVerb: false },
-    { kind: 'rule', root: path.join(SRC, 'rules'), glob: '*.md', depth: 0, subVerb: false },
-    { kind: 'command', root: path.join(SRC, 'commands'), glob: '*.md', depth: 0, subVerb: false },
-    { kind: 'command', root: path.join(SRC, 'commands'), glob: '*/*.md', depth: 0, subVerb: true },
-    { kind: 'persona', root: path.join(SRC, 'personas'), glob: '*.md', depth: 0, subVerb: false },
+    { kind: 'skill', root: SRC_SKILLS(), glob: '*/SKILL.md', depth: 1, subVerb: false },
+    { kind: 'rule', root: SRC_RULES(), glob: '*.md', depth: 0, subVerb: false },
+    {
+        kind: 'persona',
+        root: path.join(SRC_AGENT(), 'personas'),
+        glob: '*.md',
+        depth: 0,
+        subVerb: false,
+    },
 ];
 
+/** One command name to check, plus the physical file that carries it. */
+interface CommandTarget {
+    fullPath: string;
+    name: string;
+    subVerb: boolean;
+}
+
+/**
+ * Command names, reconstructed from the `src/domains` layout.
+ *
+ * The retired flat layout globbed `commands/*.md` (top-level verb, sub_verb
+ * false) and `commands/​*​/*.md` (sub-verb, sub_verb true — reserved words are
+ * legal there). The logical path of a domains command is the same
+ * `commands/<subpath>.md`, so the mapping is exact: the LAST segment is the
+ * name, and anything nested below the top level is a sub-verb.
+ */
+function _command_targets(): CommandTarget[] {
+    const out: CommandTarget[] = [];
+    for (const physical of iter_commands()) {
+        let logical: string;
+        try {
+            logical = logical_relpath(physical);
+        } catch {
+            continue;
+        }
+        const segments = logical.slice('commands/'.length).replace(/\.md$/, '').split('/');
+        const name = segments[segments.length - 1] as string;
+        if (!name) {
+            continue;
+        }
+        out.push({ fullPath: physical, name, subVerb: segments.length > 1 });
+    }
+    out.sort((a, b) => (a.fullPath < b.fullPath ? -1 : a.fullPath > b.fullPath ? 1 : 0));
+    return out;
+}
+
 function _isDir(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -205,6 +264,14 @@ function scan(): [number, number] {
             }
         }
     }
+    for (const { fullPath, name, subVerb } of _command_targets()) {
+        checked += 1;
+        for (const e of _shape_errors(name, subVerb, 'command')) {
+            const rel2 = path.relative(ROOT, fullPath).split(path.sep).join('/');
+            process.stderr.write(`❌ ${rel2}: ${e}\n`);
+            issues += 1;
+        }
+    }
     return [checked, issues];
 }
 
@@ -261,6 +328,25 @@ function main(argv?: readonly string[]): number {
         return check_single(args.name);
     }
     const [checked, issues] = scan();
+    // Scope assertion: 0 names checked means every root moved, not that every
+    // name is valid. That was this gate's shipped state until 2026-08-02.
+    try {
+        assertScanned({
+            gate: 'lint_namespace',
+            scanned: checked,
+            units: 'name(s)',
+            roots: [
+                ...TARGETS.map((t) => path.relative(ROOT, t.root).split(path.sep).join('/')),
+                'src/domains/**/command.md',
+            ],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
     if (issues) {
         process.stderr.write(`BASELINE: ${issues} issue(s) across ${checked} name(s)\n`);
         return 1;
@@ -299,7 +385,6 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 
 export {
     ROOT,
-    SRC,
     NAME_RE,
     RESERVED,
     NON_ARTEFACTS,

package/src/scripts/lint_new_skill_gate.ts

@@ -33,6 +33,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import YAML from 'yaml';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // Path(__file__).resolve().parent.parent.parent — repo root (three dirs up).
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -86,36 +89,19 @@ function _exists(p: string): boolean {
     }
 }
 
-/** Mirror `_skill_roots()`. */
+/**
+ * Mirror `_skill_roots()`.
+ *
+ * ADR-051 moved skill authoring to `src/skills`; a later commit deleted the
+ * per-package source trees this used to enumerate FIRST. That preferred branch
+ * has resolved to [] on every checkout since, so the 2026-07-29 repair's
+ * `src/skills` fallback is the only one that has ever fired. The dead
+ * preference is removed rather than left as a trap that would silently take
+ * precedence again if a `packages/` directory reappeared for another reason.
+ */
 function _skill_roots(): string[] {
-    const pkgs = path.join(ROOT, 'packages');
-    let roots: string[] = [];
-    if (_isDir(pkgs)) {
-        let entries: string[];
-        try {
-            entries = fs.readdirSync(pkgs);
-        } catch {
-            entries = [];
-        }
-        entries.sort();
-        for (const name of entries) {
-            const cand = path.join(pkgs, name, '.agent-src.uncondensed', 'skills');
-            if (_isDir(cand)) {
-                roots.push(cand);
-            }
-        }
-    }
-    // ADR-051 moved skill authoring to `src/skills`; a later commit deleted
-    // `packages/` entirely. Until 2026-07-29 the only fallback was the retired
-    // container, so this resolved to [] and the overlap gate silently passed
-    // every new skill.
-    if (roots.length === 0) {
-        const cand = path.join(ROOT, 'src', 'skills');
-        if (_isDir(cand)) {
-            roots = [cand];
-        }
-    }
-    return roots;
+    const cand = SRC_SKILLS();
+    return _isDir(cand) ? [cand] : [];
 }
 
 /** Mirror `_keyword_vector(text)`. */
@@ -378,16 +364,38 @@ export function main(argv?: string[]): number {
     }
     const { baseline, quiet } = parsed;
 
+    // Scope assertion FIRST, before the no-new-skills early return: the dedupe
+    // half of this gate compares a new skill against the existing corpus, so an
+    // empty corpus does not mean "nothing to check", it means every new skill
+    // is waved through as unique. Asserting only on the diff would miss that.
+    const allSkills = collect();
+    try {
+        assertScanned({
+            gate: 'lint_new_skill_gate',
+            scanned: allSkills.length,
+            units: 'existing skill(s)',
+            roots: _skill_roots().map((r) => path.relative(ROOT, r).split(path.sep).join('/')),
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 2;
+    }
+
     const added = added_skill_files(baseline);
     if (added.length === 0) {
         if (!quiet) {
-            process.stdout.write(`✅  No new skills added (baseline: ${baseline}).\n`);
+            process.stdout.write(
+                `✅  No new skills added (baseline: ${baseline}; ` +
+                    `${allSkills.length} existing skill(s) scanned).\n`,
+            );
         }
         return 0;
     }
 
     const addedSet = new Set(added);
-    const allSkills = collect();
     const existing = allSkills.filter((s) => !addedSet.has(s.relpath));
 
     const violations: string[] = [];

package/src/scripts/lint_originality_shingles.ts

@@ -104,7 +104,13 @@ function _collect(): Doc[] {
             push(`skill:${d.name}`, path.join(skillsDir, d.name, 'SKILL.md'));
         }
     }
-    const personasDir = path.join(REPO, 'src', 'personas');
+    // `src/agent-src/personas`, not `src/personas` — the latter has never existed
+    // since ADR-051 moved the container, so the `existsSync` guard below silently
+    // dropped all 30 personas from a comparison whose own header promises to cover
+    // them. Same dead-root class the rest of this roadmap repairs; it escaped the
+    // class-A sweep only because the literal does not carry a retired-container
+    // prefix (road-to-gates-that-can-fail Phase 1).
+    const personasDir = path.join(REPO, 'src', 'agent-src', 'personas');
     if (fs.existsSync(personasDir)) {
         const walk = (dir: string, prefix: string): void => {
             for (const d of fs.readdirSync(dir, { withFileTypes: true })) {

package/src/scripts/lint_override_kernel_guard.ts

@@ -65,10 +65,28 @@ export interface OverrideRow {
     violations: string[];
 }
 
-/** `**Mode:** \`extend\`` — the header form the override contract specifies. */
+/**
+ * `**Mode:** \`extend\`` — the header form the override contract specifies.
+ *
+ * Reads EVERY `**Mode:**` line, not the first. A non-global `exec` took
+ * whichever declaration appeared earliest, and the override contract doc itself
+ * carries two example `**Mode:**` lines — so a file whose real declaration is
+ * `replace` could be read as `extend` from an example sitting above it. On a
+ * safety-floor rule that is the difference between a blocked override and a
+ * silently permitted one, which makes first-match-wins a bypass rather than a
+ * parsing nit (road-to-gates-that-can-fail Phase 6.2, finding 5).
+ *
+ * Disagreeing declarations resolve to `unknown`, which the caller already
+ * treats as a violation — fail closed. A guard that cannot tell which mode a
+ * file declares must say so, never pick one.
+ */
 export function parse_mode(text: string): 'extend' | 'replace' | 'unknown' {
-    const m = /^\s*\*\*Mode:\*\*\s*`?(extend|replace)`?\s*$/im.exec(text);
-    return m ? (m[1] as 'extend' | 'replace') : 'unknown';
+    const found = new Set<string>();
+    const re = /^\s*\*\*Mode:\*\*\s*`?(extend|replace)`?\s*$/gim;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text)) !== null) found.add(m[1] as string);
+    if (found.size !== 1) return 'unknown';
+    return [...found][0] as 'extend' | 'replace';
 }
 
 /** `> Overrides: <rule> §<section> — <reason>` — the citation obligation. */