@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/lint_svg_asset.ts

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+/**
+ * lint_svg_asset — the command-line surface over the SVG rule set.
+ *
+ * The rules live in `_lib/svg_rules.ts`, because the design pass imports them
+ * into the hook bundle and must not drag a CLI in with them (see that file's
+ * header for the measurement). Everything this module adds is the part only a
+ * command needs: argument parsing, the directory walk, the project config, the
+ * scanned-nothing refusal, and the step 1.2 preservation readout.
+ *
+ * Inline-ignore (same shape as `lint_design_quality`, works in XML comments):
+ *   svg-asset-disable <rule-id> [-- reason]            (file scope)
+ *   svg-asset-disable-next-line <rule-id> [-- reason]
+ *   svg-asset-disable-line <rule-id> [-- reason]
+ *
+ * Per-project config (`.svg-asset.json` in the project root):
+ *   { "ignoreRules": ["svg-a11y-generic-id"], "ignoreFiles": ["vendor/**"] }
+ *
+ * Usage:
+ *   lint_svg_asset --dir <path> [--delivery inline|img|css-bg|document]
+ *   lint_svg_asset --file <a.svg> [--file <b.svg>] [--delivery …]
+ *   lint_svg_asset --file <after.svg> --baseline <before.svg> --allow id,id
+ *
+ * Exit codes: 0 = clean, 2 = findings, 1 = internal error (including the
+ * scanned-nothing refusal — a gate that scanned no file is not a clean gate).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import {
+    DELIVERY_MODES,
+    parseElements,
+    scanHostHtml,
+    scanSvg,
+    type DeliveryMode,
+    type Finding,
+    type ProjectConfig,
+    type SvgElement,
+} from './_lib/svg_rules.js';
+
+export * from './_lib/svg_rules.js';
+
+// Step 1.2 — preservation readout for a surgical edit
+// ---------------------------------------------------------------------------
+
+export interface PreservationChange {
+    id: string;
+    element: string;
+    attribute: string;
+    before: string;
+    after: string;
+}
+
+/**
+ * Canonicalised attribute map — number formatting, attribute order and
+ * whitespace normalised away, so a re-serialisation that changed nothing reads
+ * as nothing changed.
+ */
+export function canonicalAttrs(attrs: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const key of Object.keys(attrs).sort()) {
+        const v = (attrs[key] ?? '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            // Numbers only where a number is what it is. A hex color is a
+            // TOKEN, not a quantity: normalising inside `#00ff00` collapses it
+            // onto `#0ff0`, and the readout then reports no change for a color
+            // edit outside the allowed ids — a surgical-edit witness that
+            // cannot see a recolour.
+            .replace(/#[0-9a-fA-F]+|-?\d+\.?\d*(?:[eE][-+]?\d+)?/g, (tok) => {
+                if (tok.startsWith('#')) return tok.toLowerCase();
+                const num = Number(tok);
+                return Number.isFinite(num) ? String(Number(num.toFixed(4))) : tok;
+            });
+        out[key] = v;
+    }
+    return out;
+}
+
+/**
+ * Every element outside the allowed set that changed between two revisions.
+ *
+ * NO PIXEL DIFF decides this. Anti-aliasing and font metrics would make a
+ * pixel comparison a per-machine verdict, and the discipline this witnesses —
+ * `design-fidelity-mechanics.md` § surgical edits — is about which elements
+ * the edit was allowed to touch, which is an attribute fact.
+ */
+export function preservationReadout(
+    beforeContent: string,
+    afterContent: string,
+    allowedIds: readonly string[],
+): PreservationChange[] {
+    const allow = new Set(allowedIds.map((s) => s.trim()).filter(Boolean));
+
+    /**
+     * A stable key per element, and the id chain above it.
+     *
+     * An element WITHOUT an id is keyed by its nearest id-bearing ancestor plus
+     * its tag and its ordinal INSIDE that ancestor — never by a document-wide
+     * index. A document-wide index shifts for every element after an allowed
+     * deletion, so removing one child of the allowed group reported every
+     * un-idded element after it as changed. Measured on the `grouped-transforms`
+     * triple: the correct edit reported `rect#7 (element)` and the readout could
+     * not tell a clean surgical edit from a dirty one.
+     */
+    const index = (content: string): Map<string, { el: SvgElement; chain: string[] }> => {
+        const map = new Map<string, { el: SvgElement; chain: string[] }>();
+        const stack: Array<{ name: string; id: string | null }> = [];
+        const ordinals = new Map<string, number>();
+        for (const el of parseElements(content)) {
+            if (el.closing) {
+                if (stack[stack.length - 1]?.name === el.name) stack.pop();
+                continue;
+            }
+            const chain = stack.map((f) => f.id).filter((x): x is string => x !== null);
+            const ownerId = [...stack].reverse().find((f) => f.id !== null)?.id ?? '';
+            const own = el.attrs['id'] ?? null;
+            let key: string;
+            if (own) {
+                key = own;
+            } else {
+                const bucket = `${ownerId}/${el.name}`;
+                const n = (ordinals.get(bucket) ?? 0) + 1;
+                ordinals.set(bucket, n);
+                key = `${bucket}#${n}`;
+            }
+            map.set(key, { el, chain: own ? [...chain, own] : chain });
+            if (!el.selfClosing) stack.push({ name: el.name, id: own });
+        }
+        return map;
+    };
+
+    const before = index(beforeContent);
+    const after = index(afterContent);
+    const changes: PreservationChange[] = [];
+    /** An element inside an allowed subtree is itself allowed. */
+    const permitted = (entry: { chain: string[] } | undefined): boolean =>
+        Boolean(entry && entry.chain.some((id) => allow.has(id)));
+
+    for (const [key, beforeEntry] of before) {
+        if (permitted(beforeEntry)) continue;
+        const afterEntry = after.get(key);
+        if (!afterEntry) {
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: '(element)',
+                before: 'present',
+                after: 'removed',
+            });
+            continue;
+        }
+        const a = canonicalAttrs(beforeEntry.el.attrs);
+        const b = canonicalAttrs(afterEntry.el.attrs);
+        for (const attr of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            if ((a[attr] ?? '') === (b[attr] ?? '')) continue;
+            changes.push({
+                id: key,
+                element: beforeEntry.el.name,
+                attribute: attr,
+                before: a[attr] ?? '(absent)',
+                after: b[attr] ?? '(absent)',
+            });
+        }
+    }
+    for (const [key, afterEntry] of after) {
+        if (permitted(afterEntry) || before.has(key)) continue;
+        changes.push({
+            id: key,
+            element: afterEntry.el.name,
+            attribute: '(element)',
+            before: 'absent',
+            after: 'added',
+        });
+    }
+    return changes;
+}
+
+export function loadConfig(dir: string): ProjectConfig {
+    const configPath = path.join(dir, '.svg-asset.json');
+    if (!fs.existsSync(configPath)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf-8')) as ProjectConfig;
+    } catch {
+        return {};
+    }
+}
+
+function* walkDir(dir: string, ext: RegExp): Generator<string> {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+        if (entry.isDirectory()) yield* walkDir(full, ext);
+        else if (ext.test(entry.name)) yield full;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function readFlag(args: string[], name: string): string | undefined {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+
+function readAll(args: string[], name: string): string[] {
+    const out: string[] = [];
+    for (let i = 0; i < args.length; i++) if (args[i] === name && args[i + 1]) out.push(args[i + 1] as string);
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = [...argv];
+    const jsonMode = args.includes('--json');
+    const quiet = args.includes('--quiet');
+    const deliveryRaw = readFlag(args, '--delivery');
+    if (deliveryRaw && !DELIVERY_MODES.includes(deliveryRaw as DeliveryMode)) {
+        process.stderr.write(
+            `[lint_svg_asset] unknown --delivery "${deliveryRaw}"; expected one of ${DELIVERY_MODES.join(', ')}\n`,
+        );
+        return 1;
+    }
+    const delivery = deliveryRaw as DeliveryMode | undefined;
+
+    // --- step 1.2: preservation readout -------------------------------------
+    const baseline = readFlag(args, '--baseline');
+    if (baseline) {
+        const files = readAll(args, '--file');
+        const after = files[0];
+        if (!after) {
+            process.stderr.write('[lint_svg_asset] --baseline needs a --file <after.svg> to compare against\n');
+            return 1;
+        }
+        if (!fs.existsSync(baseline) || !fs.existsSync(after)) {
+            process.stderr.write('[lint_svg_asset] --baseline or --file path not found\n');
+            return 1;
+        }
+        const allow = (readFlag(args, '--allow') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        const changes = preservationReadout(
+            fs.readFileSync(baseline, 'utf-8'),
+            fs.readFileSync(after, 'utf-8'),
+            allow,
+        );
+        if (jsonMode) {
+            process.stdout.write(`${JSON.stringify(changes, null, 2)}\n`);
+            return changes.length ? 2 : 0;
+        }
+        if (!changes.length) {
+            if (!quiet) {
+                process.stdout.write(
+                    `✅  lint_svg_asset --baseline: nothing changed outside ${allow.length} allowed id(s).\n`,
+                );
+            }
+            return 0;
+        }
+        for (const c of changes) {
+            process.stdout.write(
+                `❌ ${after} [svg-preserve-changed-outside-allowed] <${c.element} id="${c.id}"> ` +
+                    `${c.attribute}: "${c.before}" → "${c.after}"\n`,
+            );
+        }
+        process.stdout.write(
+            `\nlint_svg_asset: ${changes.length} element change(s) outside the allowed set. ` +
+                'A surgical edit touches only what it declared.\n',
+        );
+        return 2;
+    }
+
+    // --- scanning -----------------------------------------------------------
+    const explicit = readAll(args, '--file');
+    const dirArg = readFlag(args, '--dir');
+    const targets: string[] = [];
+    let roots: string[] = [];
+
+    if (explicit.length) {
+        targets.push(...explicit.map((f) => path.resolve(f)));
+        roots = targets;
+    } else {
+        const scanDir = dirArg ? path.resolve(dirArg) : path.resolve(process.cwd(), 'src');
+        roots = [scanDir];
+        if (!fs.existsSync(scanDir)) {
+            // The two cases are NOT the same, and collapsing them into exit 0
+            // made a renamed or mistyped `--dir` report success in CI. An
+            // ABSENT DEFAULT root is the opt-in escape — a consumer with no
+            // `src/` has nothing to scan and must not red. An EXPLICIT `--dir`
+            // that does not resolve is a broken invocation, and this module's
+            // own header already says a gate that scanned no file is not a
+            // clean gate.
+            if (!quiet) process.stderr.write(`[lint_svg_asset] scan directory not found: ${scanDir}\n`);
+            if (dirArg) return 1;
+            process.stderr.write(
+                'This linter is opt-in. Run with --dir <path> or --file <a.svg> pointing at your assets.\n',
+            );
+            return 0;
+        }
+        for (const f of walkDir(scanDir, /\.(svg|html|htm)$/i)) targets.push(f);
+    }
+
+    const config = loadConfig(process.cwd());
+    const ignoreRules = new Set((config.ignoreRules ?? []).map((r) => r.toLowerCase()));
+    const ignoreGlobs = config.ignoreFiles ?? [];
+    const scanned = targets.filter((f) => !ignoreGlobs.some((g) => f.includes(g.replace('**', ''))));
+
+    try {
+        assertScanned({ gate: 'lint_svg_asset', scanned: scanned.length, units: 'SVG/HTML file(s)', roots });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const all: Finding[] = [];
+    for (const abs of scanned) {
+        const rel = path.relative(process.cwd(), abs);
+        try {
+            const content = fs.readFileSync(abs, 'utf-8');
+            const findings = /\.svg$/i.test(abs)
+                ? scanSvg(content, rel, { delivery })
+                : scanHostHtml(content, rel, { delivery });
+            all.push(...findings.filter((f) => !ignoreRules.has(f.rule.toLowerCase())));
+        } catch (err) {
+            if (!quiet) process.stderr.write(`[lint_svg_asset] error: ${abs}: ${err}\n`);
+        }
+    }
+
+    if (jsonMode) {
+        process.stdout.write(`${JSON.stringify(all, null, 2)}\n`);
+        return all.length > 0 ? 2 : 0;
+    }
+    if (!all.length) {
+        if (!quiet) {
+            process.stdout.write(
+                `✅  lint_svg_asset: clean — ${scanned.length} file(s) checked, no violations.\n`,
+            );
+        }
+        return 0;
+    }
+    const errors = all.filter((f) => f.severity === 'error');
+    const warnings = all.filter((f) => f.severity === 'warning');
+    const inert = all.filter((f) => f.severity === 'inert');
+    for (const f of all) {
+        const icon = f.severity === 'error' ? '❌' : f.severity === 'warning' ? '⚠️ ' : 'ℹ️ ';
+        process.stdout.write(`${icon} ${f.file}:${f.line} [${f.rule}] ${f.snippet}\n`);
+    }
+    process.stdout.write(
+        `\nlint_svg_asset: ${errors.length} error(s), ${warnings.length} warning(s), ${inert.length} inert. ` +
+            'Use svg-asset-disable-next-line <rule> -- reason or .svg-asset.json to suppress; ' +
+            'svg-safety-* findings yield only to .svg-asset.json, never to a marker in the file. ' +
+            'Advisory: an "inert" row is not a clean row — the same file inlined tomorrow is an error.\n',
+    );
+    return 2;
+}
+
+/* c8 ignore start — entrypoint guard, exercised by the CLI not by the tests */
+const invokedDirectly =
+    typeof process !== 'undefined' &&
+    Array.isArray(process.argv) &&
+    /lint_svg_asset\.(ts|js)$/.test(process.argv[1] ?? '');
+if (invokedDirectly) process.exit(main());
+/* c8 ignore stop */

package/src/scripts/lint_ticked_unmet_criteria.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env tsx
+/**
+ * Reports an acceptance criterion ticked over its own "NOT met".
+ *
+ * A `- [x] AC-<n>` item whose own text says a half of it `is NOT met` is a
+ * contradiction a reader of the checkbox never sees: the glyph says done, the
+ * prose says not. The honest glyph is `[~]`, which carries the unmet half as a
+ * deferral rather than hiding it under a tick.
+ *
+ * The criterion's text is the bullet line plus its indented continuation lines,
+ * up to a blank line, a less-indented line or the next checkbox. Fenced code is
+ * skipped, so a quoted example is not a finding. The match is the literal
+ * `NOT met` — upper-case on purpose, because that is how an author marks the
+ * unmet half, and a lower-case "not met" inside an explanation is prose.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_ticked_unmet_criteria
+ *   ./scripts-run src/scripts/lint_ticked_unmet_criteria --root <repo>
+ *
+ * Scans every `*.md` under the roadmap tree, archive included: an archived
+ * roadmap is exactly where a contradictory tick outlives the session that
+ * made it.
+ *
+ * Exit codes: 0 no hit · 1 at least one hit · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { reportScanned } from './_lib/scan_scope.js';
+
+interface Hit {
+    file: string;
+    line: number;
+    criterion: string;
+}
+
+const TICKED_AC_RE = /^([ \t]*)[-*][ \t]+\[[xX]\][ \t]+(AC-[\w.-]+)/;
+const CHECKBOX_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]/;
+const FENCE_RE = /^[ \t]*(```|~~~)/;
+const UNMET = 'NOT met';
+
+function _indent(line: string): number {
+    return (/^[ \t]*/.exec(line)?.[0] ?? '').length;
+}
+
+function scanText(text: string, file: string): Hit[] {
+    const lines = text.split('\n');
+    const hits: Hit[] = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        if (FENCE_RE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+        const m = TICKED_AC_RE.exec(line);
+        if (!m) {
+            continue;
+        }
+        const base = (m[1] as string).length;
+        const block = [line];
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const next = lines[j] as string;
+            if (next.trim() === '' || CHECKBOX_RE.test(next) || FENCE_RE.test(next) || _indent(next) <= base) {
+                break;
+            }
+            block.push(next);
+        }
+        if (block.join('\n').includes(UNMET)) {
+            hits.push({ file, line: i + 1, criterion: m[2] as string });
+        }
+    }
+    return hits;
+}
+
+function _walk(dir: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            out.push(..._walk(full));
+        } else if (e.isFile() && e.name.endsWith('.md')) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+
+function scanTree(root: string): { hits: Hit[]; scanned: number } {
+    const files = _walk(path.join(root, 'agents', 'roadmaps'));
+    const hits: Hit[] = [];
+    for (const abs of files) {
+        const rel = path.relative(root, abs).split(path.sep).join('/');
+        hits.push(...scanText(fs.readFileSync(abs, 'utf8'), rel));
+    }
+    return { hits, scanned: files.length };
+}
+
+const _DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    let root = _DEFAULT_ROOT;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--root') {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                process.stderr.write('lint_ticked_unmet_criteria: --root requires a value\n');
+                return 2;
+            }
+            root = path.resolve(v);
+            i += 1;
+        } else {
+            process.stderr.write(`lint_ticked_unmet_criteria: unknown argument: ${String(arg)}\n`);
+            return 2;
+        }
+    }
+    const { hits, scanned } = scanTree(root);
+    reportScanned({
+        gate: 'lint_ticked_unmet_criteria',
+        scanned,
+        units: 'roadmap file(s)',
+        roots: ['agents/roadmaps'],
+        allowEmpty: 'EMPTY_VALID: a checkout with no roadmap has no criterion to tick',
+    });
+    if (hits.length === 0) {
+        process.stdout.write(`✅  lint_ticked_unmet_criteria: ${String(scanned)} roadmap file(s), no criterion ticked over "${UNMET}".\n`);
+        return 0;
+    }
+    process.stderr.write(
+        `❌  lint_ticked_unmet_criteria: ${String(hits.length)} criterion/criteria ticked [x] over their own "${UNMET}":\n`,
+    );
+    for (const h of hits) {
+        process.stderr.write(`  ${h.file}:${String(h.line)} · ${h.criterion}\n`);
+    }
+    process.stderr.write('\n    The unmet half is a deferral: use `[~]` and carry it, or meet it.\n');
+    return 1;
+}
+
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main());
+        }
+    } catch {
+        if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+            process.exit(main());
+        }
+    }
+}
+
+export { scanText, scanTree, main };
+export type { Hit };

package/src/scripts/lint_workflow_security.ts

@@ -28,6 +28,9 @@
  * TIERS are untouched; only the description of what MEDIUM covers now matches
  * the code. Re-tiering the locked model is a separate decision, recorded as
  * unresolved in agents/evidence/analysis/workflow-security-net-degraded-decision.md.
+ * The CI INVOCATION is decided there too: since 2026-10-07 consistency.yml runs
+ * this gate under `--strict` (AI council, 2/2), so a HIGH fails a pull request;
+ * the tiers are unchanged.
  *
  * Script-injection detection (regex-based) is intentionally deferred — it
  * requires an AST-aware pass to avoid false positives on quoted / escaped
@@ -805,7 +808,9 @@ export function main(argv?: string[]): number {
         );
         if (high.length || medium.length) {
             process.stdout.write(
-                '  (warn-only — run with --strict to make HIGH findings block CI)\n',
+                args.strict
+                    ? '  (--strict — HIGH findings fail this run; MEDIUM stays advisory)\n'
+                    : '  (warn-only — run with --strict to make HIGH findings block CI)\n',
             );
         } else {
             process.stdout.write('  no non-allowlisted findings\n');
@@ -813,6 +818,12 @@ export function main(argv?: string[]): number {
     }
 
     if (args.strict && high.length) {
+        if (args.quiet) {
+            // --quiet suppresses the report; a failing run still names its cause.
+            process.stderr.write(
+                `workflow-security: ${high.length} HIGH under --strict — rerun without --quiet for the findings\n`,
+            );
+        }
         return 1;
     }
     return 0;

package/src/scripts/measure_skill_ranker_baseline.ts

@@ -495,6 +495,11 @@ export const RANKER_LABELS: Readonly<Record<string, RankOptions>> = {
     headings: { includeHeadings: true },
     idf: { idfWeighting: true },
     'idf+when-to-use': { idfWeighting: true, includeWhenToUse: true },
+    // `road-to-a-ranker-whose-ties-break-on-signal` Phase 3: the order inside a
+    // block of equal integer scores, alone and over the one weighting that
+    // makes the unrounded score vary.
+    ties: { tieBreakUnrounded: true },
+    'idf+ties': { idfWeighting: true, tieBreakUnrounded: true },
 };
 
 /**

package/src/scripts/model_rule_injection.ts

@@ -617,7 +617,7 @@ export function runEndpoints(corpusDir: string): EndpointResult[] {
     let deliveries = 0;
     let unequal = 0;
     for (const c of positives) {
-        const injection = buildInjection(REPO_ROOT, c.prompt, c.openFiles, null, new Set());
+        const injection = buildInjection(REPO_ROOT, c.prompt, c.openFiles, null, new Set(), false);
         if (injection === null) continue;
         for (const id of injection.rules) {
             const projected = loadRuleBody(REPO_ROOT, id);
@@ -803,12 +803,12 @@ export function runSelftest(corpusDir: string): SelftestCase[] {
     const probe = cases.find(
         (c) =>
             c.label === 'positive' &&
-            buildInjection(REPO_ROOT, c.prompt, c.openFiles, null, new Set()) !== null,
+            buildInjection(REPO_ROOT, c.prompt, c.openFiles, null, new Set(), false) !== null,
     );
     const injection =
         probe === undefined
             ? null
-            : buildInjection(REPO_ROOT, probe.prompt, probe.openFiles, null, new Set());
+            : buildInjection(REPO_ROOT, probe.prompt, probe.openFiles, null, new Set(), false);
     if (injection === null || injection.rules.length === 0) {
         out.push({
             endpoint: 'a-delivery',

package/src/scripts/onboarding_gate_hook.ts

@@ -10,7 +10,7 @@
  * deterministic state file the rule body can cite as the source of
  * truth for "do I need to prompt the user about /onboard?".
  *
- * Output is written to `agents/runtime/state/onboarding-gate.json` with:
+ * Output is written to `agents/state/onboarding-gate.json` with:
  *   {
  *     "required": <bool>,         // true → rule fires on first turn
  *     "reason":   "<string>",     // why this state was set
@@ -33,8 +33,9 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // Re-use the shared atomic-write helper so concerns honour the single
-// `agents/runtime/state/.dispatcher.lock` discipline (hook-architecture-v1.md
-// § Concurrency, Phase 7.4).
+// `agents/state/.dispatcher.lock` discipline (hook-architecture-v1.md,
+// Concurrency, Phase 7.4) — the lock sits beside THIS hook's own target, not
+// the fixed `agents/runtime/state/` path the discipline cites generally.
 import { atomic_write_json } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 
@@ -153,11 +154,11 @@ function _now_iso(): string {
 }
 
 /**
- * Write `agents/runtime/state/onboarding-gate.json` atomically.
+ * Write `agents/state/onboarding-gate.json` atomically.
  *
- * Uses the shared `agents/runtime/state/.dispatcher.lock` so concurrent
+ * Uses the shared `agents/state/.dispatcher.lock` so concurrent
  * dispatcher invocations across platforms cannot tear the file
- * (hook-architecture-v1.md § Concurrency, Phase 7.4).
+ * (hook-architecture-v1.md, Concurrency, Phase 7.4).
  */
 function _write_state(
   consumer_root: string,