@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -29,23 +29,11 @@
  * settings file is how it learns it is off, the same as the artefact-
  * engagement surface it mirrors.)
  *
- * THAT SENTENCE USED TO READ "no directory creation", UNQUALIFIED, AND IS
- * NARROWED RATHER THAN QUIETLY LEFT STANDING. The foreign-MCP recorder below
- * writes `agents/runtime/neighbour-tool-use.json` on an install that never
- * enabled telemetry, and creates that directory and a lock sentinel beside it.
- * That is deliberate — the store is a local census input, not telemetry, and
- * gating it on the org switch would print `0` everywhere (roadmap decision D9)
- * — but it IS a file operation, so the guarantee now says which operations it
- * covers. An unqualified claim this file's own code contradicts is worse than
- * the narrower one it is replaced by.
- *
- * NOT REACHED YET, AND SAYING SO HERE BECAUSE THIS IS WHERE A READER LOOKS.
- * The manifest entry for this concern carries `tools: [Skill]`, which the
- * dispatcher matches exactly, so it is not invoked for an MCP call at all and
- * the branch below is dead in production. Held as the
- * `mcp-recorder-unreachable-behind-the-tools-filter` blocker on
- * road-to-neighbours-that-pull-their-weight: the manifest is a gated
- * governance surface and the council split on the edit rather than converging.
+ * The foreign-MCP tool-name recorder that once branched here lives in its own
+ * concern, `mcp-usage-observation` (road-to-neighbours-that-pull-their-weight
+ * D12): this concern's `tools: [Skill]` filter meant the dispatcher never
+ * called that branch, and default-on local collection does not belong under an
+ * opt-in telemetry name.
  *
  * NO OUTBOUND CALL EXISTS HERE, DELIBERATELY. Transport is Phase 2 and is
  * blocked on `sink-choice`; org-wide enablement is Phase 3 and is blocked on
@@ -74,12 +62,7 @@ import {
     FLUSH_SESSION_END,
     spool_path_for,
 } from '../../agent-src/templates/scripts/telemetry/transport.js';
-import {
-    FOREIGN_TOOL_USE_REL,
-    MCP_TOOL_PREFIX,
-    usageDay,
-} from '../_lib/neighbour_tool_use.js';
-import { is_replay_mode, update_json_under_lock } from './state_io.js';
+import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW } from './exit_codes.js';
 
@@ -272,29 +255,7 @@ function processEnvelope(envelope: JsonValue, consumer_root: string): number {
 
         const payload = unwrapPayload(envelope);
         const tool = extractToolName(payload);
-        if (tool !== SKILL_TOOL_NAME) {
-            // The other half of this slot's observation, and the only half a
-            // `post_tool_use` envelope can supply: the tool's NAME. The MCP
-            // fingerprint store wants a tool DEFINITION, which this envelope
-            // never carries (roadmap decision D2), so what is recorded here is
-            // what was actually seen. Rooted at the settings directory, not at
-            // the session cwd, for the same reason the Class-A log below is.
-            if (tool !== null && tool.startsWith(MCP_TOOL_PREFIX)) {
-                // The mutator's cast is safe at the only place that matters:
-                // the reader in `neighbour_tool_use` drops any value that is
-                // not a string, so a hand-edited store cannot widen this.
-                // Kept OUT of the argument list below — esbuild preserves a
-                // comment in that position and it would cost the shared
-                // bundle ~190 bytes of prose nothing executes.
-                const day = usageDay(new Date());
-                update_json_under_lock<Record<string, string>>(
-                    path.join(readSettingsFor(consumer_root).root, FOREIGN_TOOL_USE_REL),
-                    (seen) => (seen[tool] === day ? null : ({ ...seen, [tool]: day } as Record<string, string>)),
-                    { blocking: false },
-                );
-            }
-            return EXIT_ALLOW;
-        }
+        if (tool !== SKILL_TOOL_NAME) return EXIT_ALLOW;
 
         const { settings, text, root } = readSettingsFor(consumer_root);
         if (!settings.active) return EXIT_ALLOW;

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -197,7 +197,8 @@ import {
     graphUntestedVerdict,
 } from '../_lib/graph_feeder_record.js';
 import { type GraphState, graphState } from '../code_graph/detect.js';
-import { isVerificationCommand } from '../_lib/verification_command.js';
+import { isVerificationAttempt, isVerificationCommand } from '../_lib/verification_command.js';
+import { openSvgObligation } from './svg_obligation.js';
 // Round 8 — the record path detector C prefers over its own regex. The regex
 // reads a command's TEXT and `echo test` matches it; these read what the run
 // exited with and what it printed.
@@ -761,7 +762,7 @@ export function detectUnverifiedEdit(
 
     for (let i = lastEdit + 1; i < toolCalls.length; i += 1) {
         const c = toolCalls[i]!;
-        if (c.name === 'Bash' && c.command !== undefined && isVerificationCommand(c.command)) {
+        if (c.name === 'Bash' && c.command !== undefined && isVerificationAttempt(c.command)) {
             return null;
         }
     }
@@ -772,7 +773,7 @@ export function detectUnverifiedEdit(
         evidence: edited,
         reason:
             'this turn changed a file and then ran no verification command — ' +
-            'no test, type-check, lint or build call follows the last edit ' +
+            'no test, type-check, lint, build or asset render follows the last edit ' +
             '(verify-before-complete: a claim without a fresh run is unverified)',
         mode: 'transcript',
     };
@@ -1281,6 +1282,7 @@ function runDetectors(inputs: DetectorInputs): Finding[] {
         // on a completion CLAIM, and a turn waiting on a subagent has not
         // finished — so its closing is not the claim F is about. Same slot,
         // opposite trigger, opposite treatment of `dispatchOpen`.
+        openSvgObligation(workspaceRoot, toolCalls),
         dispatchOpen ? null : detectUntestedChange(lastAssistant, toolCalls, runState),
     ]) {
         if (f) findings.push(f);
@@ -1333,6 +1335,7 @@ function recordGraphFeeder(
             inputs.workspaceRoot,
             inputs.sessionKey,
             buildFeederRow({
+                root: inputs.workspaceRoot,
                 turn: inputs.turnOrdinal,
                 layer,
                 state,

package/src/scripts/install-hooks.sh

@@ -70,9 +70,13 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # belongs here; resolution belongs to a step run with the result in front of
 # you. When this hook refuses for staleness, the thing that fixes it is
 #
-#     task push-ready          # fetch -> integrate the base SET -> regenerate
-#                              # -> verify -> re-check freshness -> push
-#     task push-ready DRY=1    # the same six steps, read-only
+#     task push-ready BASE=<base>          # fetch -> integrate the base SET -> regenerate
+#                                          # -> verify -> re-check freshness -> push
+#     task push-ready DRY=1 BASE=<base>    # the same six steps, read-only
+#
+# `<base>` is the base the refusal names. Without BASE the base comes from the
+# open pull request (gh pr view), and is the default branch only when there is
+# no open pull request or no gh.
 #
 # The base is a SET: a branch targeting a release line or a stacked parent may
 # also have to integrate the default branch, per the branch-convergence policy
@@ -141,23 +145,47 @@ fail=0
 # no useful second finding to collect from a tree that is about to move.
 #
 # It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
-# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
-# on a detached HEAD, or standing on the base itself it returns 0 and says so.
-# So an unreachable network cannot block a push, and a stale local tracking ref
-# cannot fake a green.
+# measured 4.5s) and returns 1 on a VERIFIED behind state, or when the remote
+# answered without the base at all (a misspelled or deleted base); offline, in
+# CI, on a detached HEAD, or standing on the base itself it returns 0 and says
+# so. So an unreachable network cannot block a push, and a stale local tracking
+# ref cannot fake a green. The refusal below names which of the two it was, read
+# from the gate's own lines, so a typo is never reported as staleness.
 echo "🔍 Base freshness — is this branch behind the base it will merge into?"
 if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
     echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
 elif [ ! -x ./scripts-run ]; then
     echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
-elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
-    echo ""
-    echo "   Push blocked — the branch is behind its base, and the gates you just"
-    echo "   passed were answered against a base that no longer exists."
+else
+    fresh_rc=0
+    fresh_out=$(./scripts-run src/scripts/check_branch_freshness --quiet 2>&1) || fresh_rc=$?
+    [ -z "$fresh_out" ] || printf '%s\n' "$fresh_out"
+fi
+if [ "${fresh_rc:-0}" -ne 0 ]; then
+    # The gate prints the base in the spelling `task push-ready` accepts.
+    base=$(printf '%s\n' "$fresh_out" | sed -n 's/^ *task push-ready BASE=\([^ ]*\).*/\1/p' | head -n 1)
+    absent=$(printf '%s\n' "$fresh_out" | sed -n 's/.*base `\([^`]*\)` does not exist on \([^ ]*\) .*/\2\/\1/p' | head -n 1)
     echo ""
-    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
-    echo "                             # → verify → re-check freshness, then push"
-    echo "     task push-ready DRY=1   # the same steps, read-only"
+    if [ -n "$base" ]; then
+        echo "   Push blocked — the branch is behind its base, and the gates you just"
+        echo "   passed were answered against a base that no longer exists."
+        echo ""
+        echo "     task push-ready BASE=$base         # fetch → integrate the base SET"
+        echo "                                         # → regenerate → verify → re-check"
+        echo "     task push-ready DRY=1 BASE=$base   # the same steps, read-only"
+    elif printf '%s\n' "$fresh_out" | grep -q 'branch is BEHIND'; then
+        # A strategy that does not merge gets no push-ready line; its remedy
+        # is printed by the gate itself.
+        echo "   Push blocked — the branch is behind its base. The remedy for this"
+        echo "   project's update strategy is printed above."
+    elif [ -n "$absent" ]; then
+        echo "   Push blocked — the base $absent does not exist on the remote: a"
+        echo "   misspelled or deleted base, not a stale branch. Name a branch the"
+        echo "   remote has (--base main and --base origin/main are the same branch)."
+    else
+        echo "   Push blocked — the freshness gate refused without a verdict line;"
+        echo "   its output is above."
+    fi
     echo ""
     echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
     echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."

package/src/scripts/install.ts

@@ -334,15 +334,10 @@ const LEGACY_RENAME_MAP: Record<string, string> = {
     open_edited_files: 'personal.open_edited_files',
     user_name: 'personal.user_name',
     rtk_installed: 'personal.rtk_installed',
-    minimal_output: 'personal.minimal_output',
-    play_by_play: 'personal.play_by_play',
-    pr_comment_bot_icon: 'project.pr_comment_bot_icon',
-    pr_template: 'project.pr_template',
     upstream_repo: 'project.upstream_repo',
     improvement_pr_branch_prefix: 'project.improvement_pr_branch_prefix',
     github_pr_reply_method: 'github.pr_reply_method',
     eloquent_access_style: 'eloquent.access_style',
-    skill_improvement_pipeline: 'pipelines.skill_improvement',
     subagent_implementer_model: 'subagents.implementer_model',
     subagent_judge_model: 'subagents.judge_model',
     subagent_max_parallel: 'subagents.max_parallel',
@@ -3032,7 +3027,7 @@ function _deploy_global_content(
                     warn(`claude-code: thinned rule layer not written — ${String(e)}`);
                 }
             }
-            if (!state.QUIET) for (const l of installReceiptBudgetLines(package_root)) info(l);
+            if (!state.QUIET) for (const l of installReceiptBudgetLines(package_root, undefined, { thisDeploy: new Map([[anchor, current_files]]) })) info(l);
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);
@@ -4773,27 +4768,11 @@ function _read_consumer_auto_switch(project_root: string): string {
 /**
  * Team-mode setup hint (road-to-team-mode Phase 1 Step 2) — a one-line
  * recommendation printed after a claude-code install/init pointing at the
- * doctor `team` section. Returns null when suppressed via
- * `ai_team.suppress_setup_hint: true` in `.agent-settings.yml` (default
- * false; the `ai_team` block may not exist in the schema yet — read
- * leniently). Pointer only: never auto-installs, never modifies
- * `~/.claude/plugins`.
+ * doctor `team` section. Always shown: the `ai_team.suppress_setup_hint` key
+ * that could silence it was retired with its default (false). Pointer only:
+ * never auto-installs, never modifies `~/.claude/plugins`.
  */
-function _team_setup_hint_line(project_root: string): string | null {
-    let data: Record<string, unknown>;
-    try {
-        data = load_agent_settings({ project_path: _resolve_settings_read(project_root) });
-    } catch {
-        data = {};
-    }
-    const ai_team = _isPlainObject(data) ? data['ai_team'] : null;
-    const flag = _isPlainObject(ai_team)
-        ? (ai_team as Record<string, unknown>)['suppress_setup_hint']
-        : null;
-    const suppressed =
-        flag === true ||
-        (typeof flag === 'string' && ['true', 'yes', 'on', '1'].includes(flag.trim().toLowerCase()));
-    if (suppressed) return null;
+function _team_setup_hint_line(): string {
     return (
         '  • Claude Code team mode (optional cross-model review via the official ' +
         'codex plugin): run `agent-config doctor --check team` for setup status.'
@@ -5006,11 +4985,8 @@ function _main_project_install(
         }
         mcp_consent.printResiduals(tools, state.QUIET);
         if (_is_tool_enabled(tools, 'claude-code')) {
-            const team_hint = _team_setup_hint_line(project_root);
-            if (team_hint !== null) {
-                process.stdout.write(team_hint + '\n');
-                process.stdout.write('\n');
-            }
+            process.stdout.write(_team_setup_hint_line() + '\n');
+            process.stdout.write('\n');
         }
     }
 

package/src/scripts/lint_blocker_citations.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env tsx
+/**
+ * Every `path:line` a roadmap blocker cites must still point at a line.
+ *
+ * A blocker's `What to do` and `Resolved when` lean on citations like
+ * `src/scripts/foo.ts:120-134`. Line numbers move with every edit above them,
+ * and nothing re-reads a citation once it is written — `check_references`
+ * resolves names, not line numbers. A cited range that now runs past the end
+ * of its file sends the reader of the blocker to nothing.
+ *
+ * Scope: the `## Blockers` section of every active roadmap and every stub.
+ * Checked: the file exists and the last cited line is within its length.
+ * Not checked: what the line says — a content check would red on every
+ * harmless edit above it.
+ *
+ * A citation is a repository-relative path with a file extension, `:`, a line
+ * number and an optional `-<line>` end. A bare `:354-359` with no path is
+ * relative to prose above it and is not read.
+ *
+ * Existing misses are ratcheted (`gate-violation-baselines.json`, gate
+ * `lint_blocker_citations`): line numbers drift, so a miss already in the tree
+ * is drift rather than a new defect, and the count may only fall.
+ *
+ * Exit codes: 0 within the ratchet · 1 above it · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+type MissKind = 'missing-file' | 'beyond-end';
+
+interface Citation {
+    roadmap: string;
+    line: number;
+    target: string;
+    first: number;
+    last: number;
+}
+
+interface Miss extends Citation {
+    kind: MissKind;
+    length: number | null;
+}
+
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const CITATION_RE = /(?<![\w./:-])((?:[\w.-]+\/)*[\w-][\w.-]*\.[A-Za-z0-9]+):(\d+)(?:-(\d+))?(?!\d)/g;
+
+/** Citations inside the `## Blockers` section, with their line in the roadmap. */
+function citationsIn(text: string, roadmap: string): Citation[] {
+    const m = BLOCKERS_SECTION_RE.exec(text);
+    if (!m) {
+        return [];
+    }
+    const start = m.index + m[0].length;
+    const rest = text.slice(start);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = h2 ? rest.slice(0, h2.index) : rest;
+    const lineOffset = text.slice(0, start).split('\n').length - 1;
+    const out: Citation[] = [];
+    section.split('\n').forEach((raw, i) => {
+        for (const c of raw.matchAll(CITATION_RE)) {
+            const first = Number(c[2]);
+            const last = c[3] === undefined ? first : Number(c[3]);
+            out.push({ roadmap, line: lineOffset + i + 1, target: c[1] as string, first, last });
+        }
+    });
+    return out;
+}
+
+/** Line count of the cited file, repo-relative first, then relative to the citing roadmap. */
+function _lengthOf(root: string, c: Citation): number | null {
+    for (const abs of [path.join(root, c.target), path.join(root, path.dirname(c.roadmap), c.target)]) {
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+            return fs.readFileSync(abs, 'utf8').replace(/\n$/, '').split('\n').length;
+        }
+    }
+    return null;
+}
+
+function checkCitation(root: string, c: Citation, lengths: Map<string, number | null>): Miss | null {
+    const key = `${path.dirname(c.roadmap)}\0${c.target}`;
+    let length = lengths.get(key);
+    if (length === undefined) {
+        length = _lengthOf(root, c);
+        lengths.set(key, length);
+    }
+    if (length === null) {
+        return { ...c, kind: 'missing-file', length };
+    }
+    return Math.max(c.first, c.last) > length ? { ...c, kind: 'beyond-end', length } : null;
+}
+
+function roadmapFiles(root: string): string[] {
+    const out: string[] = [];
+    for (const sub of ['', 'stubs']) {
+        const dir = path.join(root, 'agents', 'roadmaps', sub);
+        let names: string[];
+        try {
+            names = fs.readdirSync(dir);
+        } catch {
+            continue;
+        }
+        for (const n of names.sort()) {
+            const abs = path.join(dir, n);
+            if (n.endsWith('.md') && fs.statSync(abs).isFile()) {
+                out.push(path.relative(root, abs).split(path.sep).join('/'));
+            }
+        }
+    }
+    return out;
+}
+
+function scanTree(root: string): { misses: Miss[]; scanned: number; citations: number } {
+    const lengths = new Map<string, number | null>();
+    const files = roadmapFiles(root);
+    const misses: Miss[] = [];
+    let citations = 0;
+    for (const rel of files) {
+        for (const c of citationsIn(fs.readFileSync(path.join(root, rel), 'utf8'), rel)) {
+            citations += 1;
+            const miss = checkCitation(root, c, lengths);
+            if (miss) {
+                misses.push(miss);
+            }
+        }
+    }
+    return { misses, scanned: files.length, citations };
+}
+
+const _DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    let root = _DEFAULT_ROOT;
+    let baselineRoot = _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_blocker_citations: --root requires a value\n');
+                return 2;
+            }
+            root = path.resolve(v);
+            baselineRoot = root;
+            i += 1;
+        } else {
+            process.stderr.write(`lint_blocker_citations: unknown argument: ${String(arg)}\n`);
+            return 2;
+        }
+    }
+    const { misses, scanned, citations } = scanTree(root);
+    reportScanned({
+        gate: 'lint_blocker_citations',
+        scanned,
+        units: 'roadmap file(s)',
+        roots: ['agents/roadmaps', 'agents/roadmaps/stubs'],
+        allowEmpty: 'EMPTY_VALID: a checkout with no active roadmap cites nothing',
+    });
+    const verdict = checkRatchet({ gate: 'lint_blocker_citations', actual: misses.length, repoRoot: baselineRoot });
+    const lines = misses.map(
+        (m) =>
+            `  ${m.roadmap}:${String(m.line)} · ${m.target}:${String(m.first)}${m.last !== m.first ? `-${String(m.last)}` : ''} · ` +
+            (m.kind === 'missing-file' ? 'file does not exist' : `file has ${String(m.length)} line(s)`),
+    );
+    if (!verdict.ok) {
+        process.stderr.write(`❌  ${verdict.message}\n`);
+        process.stderr.write(`${lines.join('\n')}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  lint_blocker_citations: ${String(citations)} citation(s) in ${String(scanned)} roadmap file(s). ${verdict.message}\n`,
+    );
+    if (lines.length > 0) {
+        process.stdout.write(`${lines.join('\n')}\n`);
+    }
+    return 0;
+}
+
+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 { citationsIn, checkCitation, scanTree, main };
+export type { Citation, Miss };

package/src/scripts/lint_consolidation_lineage.ts

@@ -313,18 +313,21 @@ export function analyseFolder(
     surface: Surface = 'inbox',
 ): Finding[] {
     const findings: Finding[] = [];
-    let names: string[];
+    let entries: string[];
     try {
-        names = fs.readdirSync(dir).filter((n) => ROADMAP_RE.test(n)).sort();
+        entries = fs.readdirSync(dir);
     } catch {
         return findings;
     }
+    const names = entries.filter((n) => ROADMAP_RE.test(n)).sort();
     const artifacts: Artifact[] = names.map((n) => ({
         stem: n.replace(/\.md$/i, ''),
         file: n,
         decl: parseDeclaration(fs.readFileSync(path.join(dir, n), 'utf-8'), surface),
     }));
-    const present = new Set(artifacts.map((a) => a.stem));
+    // A parent need not be named road-to-*: a dated deep-dive plan is a parent
+    // too, and only its absence makes it missing.
+    const present = new Set(entries.filter((n) => /\.md$/i.test(n)).map((n) => n.replace(/\.md$/i, '')));
 
     for (const a of artifacts) {
         if (a.decl.unparseable) {

package/src/scripts/lint_design_quality.ts

@@ -13,7 +13,8 @@
  *   DQ1 contrast       — Text/background contrast < WCAG AA (4.5:1 normal, 3:1 large)
  *   DQ2 font-size      — Body font-size < 14px (floor; 16px strongly preferred)
  *   DQ3 line-length    — Prose line-length > 75ch without column constraint
- *   DQ4 reduced-motion — @keyframes / animation present without prefers-reduced-motion alt
+ *   DQ4 reduced-motion — @keyframes / animation present without prefers-reduced-motion alt,
+ *                        and (for INLINE SVG in HTML) SMIL with no route or a CSS-only one
  *   DQ5 heading-skip   — Heading levels skipped (h1 → h3 without h2)
  *   DQ6 focus-indicator— Interactive element with no :focus-visible indicator
  *
@@ -45,6 +46,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertScanned, DeadScopeError } from "./_lib/scan_scope.js";
+import { firstSmilLine, smilVerdict } from "./_lib/svg_motion.js";
 
 interface Finding {
   rule: string;
@@ -94,25 +96,71 @@ function checkFontSize(lines: string[], filePath: string): Finding[] {
   return findings;
 }
 
-/** DQ4: @keyframes / animation without @media (prefers-reduced-motion) */
+/**
+ * DQ4: animation without a reduced-motion route.
+ *
+ * Two halves. The CSS half is the original rule. The SMIL half (step 1.3 of
+ * `road-to-svg-with-a-witness`) covers INLINE SVG inside an HTML document and
+ * closes a measured blind spot: an HTML file whose only animation is an
+ * infinite `<animate>` read "clean — 1 file(s) checked" here, because
+ * `@keyframes` and `animation:` are the only two things the CSS half looks
+ * for, and SMIL is neither (R10).
+ *
+ * It also reports the subtler case: SMIL whose ONLY reduced-motion route is a
+ * CSS declaration. Under an emulated `reduce`, a page-level
+ * `svg * { animation: none !important }` left an `<animate>` moving `cx` from
+ * 20.2 to 76.8 in 700 ms (R4) — CSS animation properties do not reach SMIL, so
+ * the file looks covered and is not.
+ *
+ * STANDALONE `.svg` IS DELIBERATELY NOT HERE. A file cannot see its host's
+ * `<picture>` route, so judging the route from inside it would red correct
+ * assets and break this linter's zero-false-positive promise (line 12). That
+ * case belongs to `lint_svg_asset`, which knows it is reading a whole asset.
+ * Both halves read the same `_lib/svg_motion.ts`, so the two cannot drift.
+ */
 function checkReducedMotion(content: string, filePath: string, lines: string[]): Finding[] {
-  const hasAnimation = /@keyframes\s+\w+|animation\s*:/i.test(content);
-  if (!hasAnimation) return [];
+  const findings: Finding[] = [];
 
+  const hasAnimation = /@keyframes\s+\w+|animation\s*:/i.test(content);
   const hasReducedMotion = /@media\s*\([^)]*prefers-reduced-motion/i.test(content);
-  if (hasReducedMotion) return [];
-
-  // Find first animation declaration for the line number
-  const animLine = lines.findIndex((l) => /@keyframes\s+\w+|animation\s*:/.test(l));
-  return [
-    {
+  if (hasAnimation && !hasReducedMotion) {
+    const animLine = lines.findIndex((l) => /@keyframes\s+\w+|animation\s*:/.test(l));
+    findings.push({
       rule: "dq4-reduced-motion",
       file: filePath,
       line: animLine + 1,
       snippet: "@keyframes or animation present without @media (prefers-reduced-motion) alternative",
       severity: "error",
-    },
-  ];
+    });
+  }
+
+  // The SMIL half runs for documents that can HOST an inline graphic. A `.css`
+  // file cannot carry one, and a standalone `.svg` is the other linter's.
+  if (!/\.(html|htm|vue|svelte|astro)$/i.test(filePath)) return findings;
+
+  const verdict = smilVerdict(content);
+  if (verdict === "no-route") {
+    findings.push({
+      rule: "dq4-reduced-motion",
+      file: filePath,
+      line: firstSmilLine(content),
+      snippet:
+        "inline SVG animates with SMIL (<animate>/<animateTransform>/<set>) and the document carries " +
+        "no @media (prefers-reduced-motion) route at all",
+      severity: "error",
+    });
+  } else if (verdict === "css-only") {
+    findings.push({
+      rule: "dq4-reduced-motion",
+      file: filePath,
+      line: firstSmilLine(content),
+      snippet:
+        "inline SVG animates with SMIL and the only reduced-motion route is a CSS animation/transition " +
+        "declaration — CSS does not reach SMIL, so the animation keeps running under `reduce`",
+      severity: "error",
+    });
+  }
+  return findings;
 }
 
 /** DQ5: heading levels skipped (h1 → h3 without h2) in HTML */

package/src/scripts/lint_evidence_artifacts.ts

@@ -50,6 +50,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
+import { parseExecutionMode } from './_lib/repeated_run.js';
 import { reportScanned } from './_lib/scan_scope.js';
 import { parseHonestNull, parseMarkerLine, parseSkipDeclaration } from './check_completion_review.js';
 
@@ -257,6 +258,14 @@ export function checkFiles(root: string, files: readonly string[], ledger?: Gate
             });
             continue;
         }
+        // The contract's second axis (repeated-run / flaky), orthogonal to the
+        // type marker above — any artifact may declare it.
+        const mode = parseExecutionMode(contents);
+        if (mode.kind === 'invalid') {
+            ledger?.fail(rel, `invalid evidence-mode: ${mode.reason}`);
+            findings.push({ file: rel, reason: `evidence-mode: ${mode.reason}` });
+            continue;
+        }
         ledger?.complete(rel);
     }
     return findings;