@event4u/agent-config 16.4.0 → 16.5.0

package/src/scripts/_lib/svg_urls.ts

@@ -0,0 +1,72 @@
+/**
+ * How a browser reads the URLs and names in an SVG, for the safety rules in
+ * `svg_rules.ts`: references decoded, controls stripped, CSS escapes resolved,
+ * and an element prefix stripped only where it is bound to the SVG namespace.
+ * Its own module so `svg_rules.ts` stays under the source-size ceiling.
+ */
+
+/** Prefixes the document binds to the SVG namespace (`xmlns:svg="…/2000/svg"`). */
+export function svgPrefixes(content: string): Set<string> {
+    const out = new Set<string>();
+    const re = /xmlns:([\w.-]+)\s*=\s*["']http:\/\/www\.w3\.org\/2000\/svg["']/gi;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(content)) !== null) out.add((m[1] ?? '').toLowerCase());
+    return out;
+}
+
+/** The SVG local name: `svg:script` is a `script` where `svg` is bound to SVG; `foo:script` is not. */
+export function localName(name: string, prefixes: ReadonlySet<string>): string {
+    const colon = name.indexOf(':');
+    return colon !== -1 && prefixes.has(name.slice(0, colon)) ? name.slice(colon + 1) : name;
+}
+
+/** Attributes read from the raw tag, unquoted values included — HTML parses those. */
+export function rawAttrs(raw: string): Record<string, string> {
+    const out: Record<string, string> = {};
+    const re = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"'`=]+))/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(raw)) !== null) out[(m[1] ?? '').toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? '';
+    return out;
+}
+
+/** Attributes whose value is followed as a URL. */
+export const URL_ATTRS = new Set(['href', 'xlink:href', 'src']);
+
+
+/** A URL that executes or opens a document when followed. */
+export const isActiveUrl = (raw: string): boolean => /^(javascript:|data:text\/html)/i.test(resolvedUrl(raw));
+
+const NAMED_URL_ENTITIES: Record<string, string> = {
+    colon: ':', sol: '/', tab: '\t', newline: '\n', period: '.', lpar: '(', rpar: ')', amp: '&',
+};
+
+/**
+ * The URL a browser would actually resolve from an attribute value: character
+ * references decoded, leading/trailing C0 controls and spaces stripped, tab and
+ * newline removed anywhere. The trailing `;` of a reference is optional on
+ * purpose: an `.svg` parsed as XML needs it, but the same graphic inlined in an
+ * HTML host is parsed by the HTML tokenizer, which decodes `&#106avascript:`
+ * too — over-reading XML here costs precision, under-reading HTML costs a miss.
+ * The raw value is attacker-chosen, so a scheme test
+ * against it is a test of one spelling — ` https:`, `ht\ttps:`, `&#106;avascript:`
+ * all load, and all passed.
+ */
+export function resolvedUrl(raw: string): string {
+    const decoded = raw.replace(/&(?:#x([0-9a-f]+)|#(\d+)|([a-z]+));?/gi, (m, hex, dec, name) => {
+        const cp = hex ? parseInt(hex, 16) : dec ? parseInt(dec, 10) : NaN;
+        if (!Number.isNaN(cp)) return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+        return NAMED_URL_ENTITIES[(name as string).toLowerCase()] ?? m;
+    });
+    return decoded.replace(/^[\u0000- ]+|[\u0000- ]+$/g, '').replace(/[\t\n\r]/g, '');
+}
+
+/** CSS escapes decoded: `\\68 ` and `\\h` both read `h`. */
+export function cssUnescape(raw: string): string {
+    return raw.replace(/\\([0-9a-f]{1,6})\s?|\\(.)/gi, (m, hex, ch) => {
+        if (hex) {
+            const cp = parseInt(hex, 16);
+            return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+        }
+        return ch as string;
+    });
+}

package/src/scripts/_lib/verification_command.ts

@@ -271,6 +271,28 @@ function segmentVerifies(rawWords: readonly string[]): boolean {
             // the old token-anywhere regex accepted it by accident and neither
             // explicit list named it, so the union seeding missed it too.
             return rest.some((a) => a === 'test' || a.startsWith('--test'));
+        case 'agent-config':
+            // NEITHER `ui:render` NOR `xmllint` verifies here, and the first
+            // half of that was true, then false, and is true again.
+            //
+            // Step 3.5 of `road-to-svg-with-a-witness` taught this predicate
+            // `ui:render --profile asset`, reasoning that it is the one
+            // subcommand which opens the delivered file in a real engine. Step
+            // 2.1(b) of `road-to-svg-review-followups` removed it again on
+            // review claim C2, which is narrower than the first argument and
+            // refutes it: the turn-end gate's TRANSCRIPT path matches a command
+            // and never sees an exit code, so a call that rendered nothing —
+            // the ordinary case on a machine with no Playwright, where the
+            // command also exited 0 until the same day — discharged the
+            // obligation from its text alone.
+            //
+            // What replaces it reads the RENDER instead of the call:
+            // `hooks/svg_obligation.ts` matches a manifest to the file's own
+            // digest, and accepts a renderer-absent manifest only together with
+            // a clean static witness on those same bytes. `xmllint --noout`
+            // stays out for its original reason (S6): a file can parse and
+            // still be the wrong picture.
+            return false;
         case 'scripts-run': {
             // `./scripts-run src/scripts/lint_x` verifies; `…/rule_activation_census`
             // writes a report and asserts nothing, which is why this keys on the
@@ -322,3 +344,40 @@ const _WIDE_CANDIDATE_RE =
 export function mightBeVerification(command: string): boolean {
     return _WIDE_CANDIDATE_RE.test(command);
 }
+
+/**
+ * `agent-config ui:render … --profile asset`, by shape.
+ *
+ * Moved here from `hooks/svg_obligation.ts` by finding 3 of this change's
+ * SECOND completion review: two detectors need it and one of them is in
+ * `_lib`, so a hook module was the wrong home. Re-exported there, so no
+ * caller moved.
+ */
+export function isAssetRenderCommand(command: string): boolean {
+    return /\bui:render\b/.test(command) && /--profile[= ]\s*asset\b/.test(command);
+}
+
+/**
+ * Did this command ATTEMPT to verify something — as opposed to: did it produce
+ * a verdict this gate may read?
+ *
+ * The distinction is the whole point, and the first review round and the
+ * second each saw one half of it. Round one (claim C2) was right that
+ * `isVerificationCommand` must NOT learn the asset render: the transcript path
+ * never sees an exit code, so the command's TEXT would have discharged the SVG
+ * obligation on a machine where the render produced nothing. Round two
+ * (finding 3) was right that removing it left detector C — "did any
+ * verification command follow the last edit" — unable to see the one command
+ * this package PRESCRIBES for an `.svg`, so the prescribed turn was refused.
+ *
+ * Both hold because they are about different detectors. Detector C asks
+ * whether the author tried; it is satisfied by `eslint` and must be satisfied
+ * by a render too. The SVG obligation asks what the render FOUND, and still
+ * reads the manifest and the file's digest — an attempt that produced nothing
+ * discharges nothing there, with a far better reason than detector C's.
+ *
+ * So: one predicate per question, and `isVerificationCommand` is unchanged.
+ */
+export function isVerificationAttempt(command: string): boolean {
+    return isVerificationCommand(command) || isAssetRenderCommand(command);
+}

package/src/scripts/_lib/verify_clause.ts

@@ -126,25 +126,35 @@ function lastMatch(re: RegExp, text: string): RegExpExecArray | null {
  * carries `(?!`)`: a label followed by a backtick is the delimited form, which
  * branch one already owns.
  *
- * The tail is capped at a single non-space token on purpose. A caller may hand
- * this parser a whole step BLOCK already joined into one line, so "the rest of
- * the line" can mean "the rest of the step" — and a step that continues after
- * its verify clause would then push the expectation away from the end anchor
- * and lose it silently. The cost is that a regex expectation here may not
- * contain a space; `/[1-9]/` and `/unfalsifiable-verify/` are the shapes in
- * use, and a space-bearing expectation loses its arrow loudly (it parses as no
- * expectation) rather than half-matching.
+ * The tail is bounded by the EXPECTATION'S OWN DELIMITERS, not by the end of
+ * the line. A caller may hand this parser a whole step BLOCK already joined
+ * into one line, so "the rest of the line" can mean "the rest of the step": an
+ * end-anchored tail would lose the expectation of any step that carries prose
+ * after its clause. A slash-delimited regex therefore runs to the first
+ * UNESCAPED closing `/` — one not preceded by an odd number of backslashes —
+ * that is followed by whitespace or the end of the text, and an exit code is
+ * one non-space token; both self-terminating, so the step may continue and
+ * `-> /[1-9]/ and then note the result` still yields `[1-9]`.
  *
- * THE CAP IS THIS FORM'S, NOT THE GRAMMAR'S — said plainly because an earlier
- * revision of this comment implied otherwise. The annotation form is
- * `$`-anchored through {@link VERIFY_ARROW_SOURCE} and DOES keep `-> /a b/`;
- * this form does not. The two agree on every space-free expectation, which is
- * every expectation in the tree. Both directions are pinned by test, so closing
- * the gap is a deliberate act against a failing assertion rather than a silent
- * drift — which is the failure the WHY ONE PARSER note above exists to prevent,
- * and it applies to this module's own two readers first.
+ * The word UNESCAPED is load-bearing and was added on 2026-10-11 (step 1.1 of
+ * `road-to-svg-review-followups`, review claim C4). The tail used to be a lazy
+ * `\/.*?\/(?=\s|$)`, which stops at ANY `/` followed by a space — so a clause
+ * ending in ``-> /a\/ b/`` was cut at the escaped slash and parsed to the
+ * regex source `a\`. A pattern that deliberately matches a path separator is
+ * exactly the case that spells it `\/`, and the truncation was silent: a
+ * shorter regex is still a regex, so nothing reported the loss.
+ *
+ * It was capped at a single non-space token until 2026-10-11, which cost this
+ * form every expectation containing a space: `-> /Icon-only button/` parsed as
+ * a clause with NO expectation, and nothing reported the loss — the step simply
+ * read as unfalsifiable. The two forms now agree on every expectation rather
+ * than only the space-free ones; {@link VERIFY_ARROW_SOURCE} stays the single
+ * `$`-anchored decision about what an expectation IS, and this regex decides
+ * only where the tail ENDS. A bare word stays refused by the constant, so
+ * widening the boundary widened no grammar.
  */
-const BACKTICKED_RE = /(?:`verify:`|verify:(?!`))\s*`([^`]+)`[ \t]*((?:->|→)[ \t]*\S+)?/g;
+const BACKTICKED_RE =
+    /(?:`verify:`|verify:(?!`))\s*`([^`]+)`[ \t]*((?:->|→)[ \t]*(?:\/(?:[^\\/]|\\.)*\/(?=\s|$)|\S+))?/g;
 
 /** Prose after the label. The MANUAL form; the body is bounded separately. */
 const PROSE_RE = /(?:`verify:`|verify:(?!`))[ \t]*/g;

package/src/scripts/hooks/block_speaking_inbox_dir.ts

@@ -149,11 +149,26 @@ function isGlobOverAcceptableInboxDir(name: string): boolean {
     if (!/[*?[\]]/.test(name)) {
         return false;
     }
-    const literal = name.replace(/[*?]|\[[^\]]*\]/g, '');
+    // Only a generic class is stripped. Any other bracket payload stays in the
+    // literal and is judged: `[acme]` names a source, and so does a run of
+    // singleton ranges like `[a-a][c-c]`.
+    const literal = name.replace(/[*?]|\[(?:a-z|0-9|a-f|0-9a-f|a-z0-9)\]/gi, '');
+    if (OPAQUE_FAMILY_WILDCARD_RE.test(name)) {
+        return true;
+    }
     const trimmed = literal.replace(/-+$/, '');
     return trimmed !== '' && isAcceptableInboxDir(trimmed);
 }
 
+/**
+ * The fixed head of an opaque identifier family followed by wildcards only.
+ * `round-*` lists hex rounds; as a literal it would create `round-*`, which
+ * carries no source. Brackets are excluded because their payload survives as
+ * literal text: `round-[acme]-*` must not pass by stripping to `round`.
+ */
+const OPAQUE_FAMILY_WILDCARD_RE =
+    /^(?:(?:inbox|round|src-set|source-set)(?:-\d{4}(?:-\d{2})?)?|set)-[*?]+$/i;
+
 /**
  * The paths a redirect inside one segment would create.
  *

package/src/scripts/hooks/design_pass_hook.ts

@@ -48,6 +48,37 @@
  * reason instead of passing silently. `src/rules/design-review-after-ui-write.md`
  * already required that in prose with nothing to read it; this emits it.
  *
+ * SVG ROUTING, AND HOW TO REVERT IT. Step 1.3 of
+ * `road-to-svg-rules-in-the-dispatch-path`. An `.svg` write reaches
+ * `lint_svg_asset`'s rules from here, inside or outside a UI tree, through
+ * `svg_rules_loader` — a CJS chunk beside the dispatch bundle, required only
+ * for a path ending in `.svg`. The review that withdrew the first attempt
+ * named the gap plainly: a statically bundled rule set has no off switch, so
+ * the triggers and the mechanism are written down before they are needed.
+ *
+ *   REVERT WHEN any of these is read:
+ *     · the composition gate exceeds its ceiling attributable to this routing
+ *       (`check_hook_bundle_composition`; measured 2,128 B on 2026-10-11, with
+ *       16,910 B of headroom left);
+ *     · a non-`.svg` hook event is observed failing with a stack that passes
+ *       through the chunk — the containment case
+ *       `design_pass_svg.test.ts > rule-failure-does-not-reach-an-unrelated-event`
+ *       exists to make impossible, so one observation is enough;
+ *     · an operator reports SVG false positives on files they accept, at a rate
+ *       that would make them switch the carrier off — Risk 1 of the parent
+ *       roadmap, and the failure this whole concern is shaped around.
+ *
+ *   THE MECHANISM, in increasing order of blast radius:
+ *     1. Delete `dist/hooks/svg_rules.chunk.cjs`. The loader returns `null`,
+ *        the pass reports `verification: degraded` naming the missing file,
+ *        and every other finding family is unaffected. This is the per-install
+ *        off switch the static import could not have had.
+ *     2. Drop `isSvgAsset` from `isPassSurface` below. An `.svg` outside a UI
+ *        tree stops reaching the pass at all; one inside it reads as it did
+ *        before this step.
+ *     3. Turn the concern off entirely (`hooks.design_pass.enabled: false`),
+ *        which was already the default.
+ *
  * Default-OFF (`hooks.design_pass.enabled`), fail_closed: false.
  *
  * Exit codes (dispatcher contract): 0 allow · 1 block · 2 warn + JSON reason.
@@ -62,6 +93,7 @@ import { trigger_matches, type Trigger } from '../_lib/router_match.js';
 import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
+import { CHUNK_BASENAME, loadSvgScan } from './svg_rules_loader.js';
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = '.agent-settings.yml';
@@ -129,8 +161,42 @@ export function enabled(root: string, key = 'design_pass'): boolean {
     return false;
 }
 
+/**
+ * True for a path this pass should look at.
+ *
+ * `.svg` is admitted HERE and nowhere else — step 1.2 of
+ * `road-to-svg-rules-in-the-dispatch-path`. The obvious way to reach an `.svg`
+ * from this pass was to add `svg` to `UI_EXTENSIONS`, and that is the thing the
+ * parent roadmap's decision E10 and `design_pass_svg.test.ts` forbid: the same
+ * predicate backs `ui_route_nudge_hook`'s `isUiWrite`, so widening it would
+ * draw a UI routing nudge and its tokens on every icon dropped into `public/`.
+ * A local disjunct reaches the asset without touching the shared predicate, in
+ * either direction.
+ */
+export const isSvgAsset = (p: string): boolean => /\.svg$/i.test(p);
+
+/**
+ * UNCHANGED, and that is the point of the predicate below it.
+ *
+ * Finding 6 of this change's own completion review: widening THIS predicate to
+ * admit every `.svg` would have moved the UI-turn denominator the
+ * consultation-rate measurement is defined against — which the
+ * `HANDOVER_TRIGGERS` note further down reserves, in writing, as a different
+ * decision than any routing change. It was widened and is widened no longer.
+ */
 export const isUiSurface = (p: string): boolean => isUiPath(p) || isUiTreePath(p);
 
+/**
+ * What this PASS looks at — a UI surface, or any `.svg`.
+ *
+ * The routing step 1.2 of `road-to-svg-rules-in-the-dispatch-path` asked for,
+ * in the one place it belongs: the pass's own entry gate. Keeping it out of
+ * `isUiSurface` leaves every other reading that predicate feeds — the
+ * conformance verdict's noteworthy test, the denominator above — reading
+ * exactly what it read before.
+ */
+export const isPassSurface = (p: string): boolean => isUiSurface(p) || isSvgAsset(p);
+
 /**
  * The shadow read of `ui-conformance.json` — Phase 5 of
  * `road-to-behaviour-evidence-over-pixels`.
@@ -441,6 +507,53 @@ function renderAvailable(root: string): boolean {
     }
 }
 
+/**
+ * SVG severity → this pass's severity.
+ *
+ * `error` and `warning` become P1 and P2; `inert` is dropped. Deliberately NOT
+ * P0: the P0 set above is a closed list of objective floors and it is the only
+ * thing that computes a block at stop. Routing a new rule family into it would
+ * change the block surface, which is a different decision than making the
+ * findings visible — and the one Risk 1 of the parent roadmap warns about.
+ */
+export function svgSeverity(s: 'error' | 'warning' | 'inert'): Finding['severity'] | null {
+    if (s === 'error') return 'P1';
+    if (s === 'warning') return 'P2';
+    return null;
+}
+
+export interface SvgRuleFinding {
+    rule: string;
+    file: string;
+    line: number;
+    snippet: string;
+    severity: 'error' | 'warning' | 'inert';
+}
+
+/**
+ * Map the SVG rule set's findings onto this pass's shape.
+ *
+ * Pure, and exported, so the routing can be proven without building a bundle:
+ * the half that is expensive to exercise end-to-end is the chunk load, and that
+ * has its own test in `svg_rules_loader`.
+ */
+export function svgFindings(raw: readonly SvgRuleFinding[], rel: string): Finding[] {
+    const out: Finding[] = [];
+    for (const f of raw) {
+        const severity = svgSeverity(f.severity);
+        if (severity === null) continue;
+        out.push({
+            file: rel,
+            severity,
+            catalogId: 'SVG',
+            rule: f.rule,
+            line: f.line,
+            message: `${f.rule}${f.snippet ? ` — ${f.snippet}` : ''}`,
+        });
+    }
+    return out;
+}
+
 /** Extracts the written path from a tool payload, whichever key the host uses. */
 export function targetPath(payload: unknown): string | null {
     if (typeof payload !== 'object' || payload === null) return null;
@@ -499,7 +612,7 @@ function main(): number {
         targets = state.touched;
     } else {
         const t = targetPath(payload);
-        if (!t || !isUiSurface(t)) return EXIT_ALLOW;
+        if (!t || !isPassSurface(t)) return EXIT_ALLOW;
         targets = [t];
         if (!state.touched.includes(t)) state.touched.push(t);
     }
@@ -508,6 +621,7 @@ function main(): number {
     // Findings come from the shipped registry, via the same entrypoint CI uses.
     const findings: Finding[] = [];
     let scanFailed: string | null = null;
+    let svgRulesUnavailable = false;
     try {
         const ctx = loadDesignContext(root);
         for (const rel of targets) {
@@ -517,6 +631,17 @@ function main(): number {
             // itself rather than handing over a path, which is also what lets a
             // post-write pass see the bytes that were just written.
             const content = fs.readFileSync(abs, 'utf-8');
+            if (isSvgAsset(rel)) {
+                // The conditional chunk. Loaded only here, so a hook event that
+                // never touched an `.svg` pays none of its bytes and runs none
+                // of its code — the containment `design_pass_svg.test.ts` pins.
+                // A null load is reported through `svgRulesUnavailable`, never
+                // thrown: a consumer whose install is missing the chunk must
+                // lose the SVG findings, not the whole dispatch.
+                const scan = loadSvgScan();
+                if (scan === null) svgRulesUnavailable = true;
+                else findings.push(...svgFindings(scan(content, rel) as SvgRuleFinding[], rel));
+            }
             for (const f of scanFile(content, rel, ctx)) {
                 findings.push({
                     file: rel,
@@ -532,11 +657,40 @@ function main(): number {
         scanFailed = String(err);
     }
 
-    const auditMissing = targets.filter((t) => !auditIsFresh(root, t));
-    recordAuditDischarge(root, targets, auditMissing);
+    // The audit question is asked of UI SURFACES, never of the pass surface.
+    // Findings 1 and 2 of the third completion review, both reproduced by
+    // running the hook: round one split the entry gate from the UI predicate,
+    // and `targets` carried the `.svg` past the split anyway. So a clean
+    // conformant icon write exited WARN with "no ui-audit.json newer than
+    // public/icon.svg" — an asset has no component inventory to be audited
+    // against — and, worse, `recordAuditDischarge` returns early on a non-empty
+    // `auditMissing`, so writing ONE `.svg` in a turn silently suppressed the
+    // ui-audit discharge row for every real UI file in that same turn.
+    const auditTargets = targets.filter((t) => isUiSurface(t));
+    const auditMissing = auditTargets.filter((t) => !auditIsFresh(root, t));
+    recordAuditDischarge(root, auditTargets, auditMissing);
     let result = decide(slot, findings, auditMissing, new Set(state.surfaced), renderAvailable(root));
     if (scanFailed) {
         result = { ...result, verification: 'unverified', degradation_reason: `detector unavailable: ${scanFailed}` };
+    } else if (svgRulesUnavailable) {
+        // Degraded, not unverified: the rest of the pass ran. An absent chunk
+        // is reported rather than silently producing a clean SVG verdict —
+        // "absent is not clean" is the same rule the conformance verdict keeps.
+        // APPENDED, never overwritten. Finding 6 of the fourth completion
+        // review: `decide` may already have set a reason — the renderer being
+        // absent is the one it sets — and assigning here threw it away, so a
+        // turn where both degradations held reported only the newer one. Two
+        // degradations are two facts; the operator needs both or they fix one
+        // and are surprised by the other.
+        const svgReason = `the SVG rule set could not be loaded (expected dist/hooks/${CHUNK_BASENAME} beside the dispatch bundle) — the .svg files in this turn were not checked`;
+        result = {
+            ...result,
+            verification: 'degraded',
+            degradation_reason:
+                result.degradation_reason === undefined || result.degradation_reason === ''
+                    ? svgReason
+                    : `${result.degradation_reason}; ${svgReason}`,
+        };
     }
 
     for (const f of result.findings) state.surfaced.push(`${f.file}::${f.rule}::${f.line}`);