@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/_lib/skill_estate.ts

@@ -0,0 +1,115 @@
+/**
+ * The skill corpus, measured — the two dimensions `check_estate_count` ratchets.
+ *
+ * WHY TWO. A file count is what a `one_in_one_out` lint can express; it is not
+ * what a skill COSTS. Merging four large skills into one file satisfies a count
+ * ratchet while the description payload a host must carry stays put or grows.
+ * AI council 2/2 (2026-08-24) asked for both dimensions in one gate for exactly
+ * that reason, over the roadmap's own recommendation of a count plus an
+ * informational companion figure: "that supports treating tokens as a coarse
+ * secondary budget — not leaving the only cost-sensitive metric informational
+ * forever."
+ *
+ * WHY NOT THE OTHER TWO CANDIDATES, measured before asking rather than argued:
+ *
+ * - **Catalogue bytes** via `_lib/skill_catalogue.ts` read **0** on this
+ *   checkout. `readProjectedCatalogue` walks `.claude/skills`, which is empty in
+ *   any tree where `task generate-tools` cannot complete — it fails under
+ *   `projection.mode=scoped` without the config package. A ratchet whose reading
+ *   depends on whether a generator ran is a ratchet that reds for the
+ *   environment.
+ * - **Host-listing slots** are the host's decision, not the repository's. A
+ *   measured install published its own budget event stating it had stripped
+ *   every description and dropped 402 entries.
+ *
+ * DEPRECATED SKILLS ARE EXCLUDED, and that is load-bearing rather than tidy:
+ * with them counted, deprecating a skill would create no headroom and the
+ * retirement mechanism would be unusable against its own gate. (Currently 0
+ * skills carry it, so the exclusion is a no-op today and a correctness property
+ * tomorrow.)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { gpt_tokens } from './token_count.js';
+
+/** Where the corpus lives, POSIX — the same string a base-tree subtree takes. */
+export const SKILLS_POSIX = 'src/skills';
+
+export interface SkillEstate {
+    /** Maintained `SKILL.md` files — `lifecycle: deprecated` excluded. */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across the maintained skills' `description:` fields.
+     *
+     * `null` when the tokeniser could not resolve. A ratchet must never compare
+     * an exact reading against a proxy one — the numbers differ by more than the
+     * growth a gate is trying to catch, so the metric is reported UNRESOLVED
+     * rather than measured with whatever was available.
+     */
+    skill_description_tokens: number | null;
+    /** Excluded from both figures, reported so the exclusion is visible. */
+    deprecated_count: number;
+}
+
+/** `description:` from a `SKILL.md` frontmatter block, unquoted. */
+export function descriptionOf(text: string): string {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return '';
+    const m = /^description:\s*(.+)$/m.exec(fm[1]!);
+    if (m === null) return '';
+    return m[1]!.trim().replace(/^["']|["']$/g, '');
+}
+
+/** `lifecycle: deprecated` in the frontmatter — the retirement transition state. */
+export function isDeprecated(text: string): boolean {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return false;
+    return /^lifecycle:\s*["']?deprecated["']?\s*$/m.test(fm[1]!);
+}
+
+/**
+ * Measure the corpus under `root`.
+ *
+ * `root` is a repository root OR a materialised base-ref tree holding
+ * `src/skills/...`, so the floor side runs this exact function over the base
+ * ref's own tree — the property `check_estate_count` already has for the roadmap
+ * estate, and the reason the "before" side cannot be rewritten by the change
+ * under review.
+ */
+export function measureSkillEstate(root: string): SkillEstate {
+    const base = path.join(root, ...SKILLS_POSIX.split('/'));
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+        return { skill_count: 0, skill_description_tokens: null, deprecated_count: 0 };
+    }
+    let count = 0;
+    let deprecated = 0;
+    let tokens = 0;
+    let exact = true;
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.isDirectory()) continue;
+        const p = path.join(base, e.name, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        if (isDeprecated(text)) {
+            deprecated += 1;
+            continue;
+        }
+        count += 1;
+        const r = gpt_tokens(descriptionOf(text));
+        if (!r.exact) exact = false;
+        tokens += r.tokens;
+    }
+    return {
+        skill_count: count,
+        skill_description_tokens: exact ? tokens : null,
+        deprecated_count: deprecated,
+    };
+}

package/src/scripts/_lib/transcript_reads.ts

@@ -0,0 +1,207 @@
+/**
+ * Re-read measurement over Claude Code transcript legs.
+ *
+ * `road-to-role-scoped-spawn-profiles` Phase 3 Step 3 requires a re-read
+ * measurement BEFORE any suppression: *"A suppression built without this
+ * measurement is suppressing whatever the author happened to notice."* This
+ * module is that measurement, and it is deliberately a sibling of
+ * `cc_transcript.ts` rather than a widening of it — `scanTranscripts` keeps
+ * only `type: "assistant"` records carrying a `usage` block, which is exactly
+ * the population a `tool_result` is NOT in.
+ *
+ * **What a "leg" is, stated because every count below depends on it.** One
+ * `.jsonl` file is one leg. Claude Code writes the main session to
+ * `<project>/<sessionId>.jsonl` and each subagent to
+ * `<project>/<sessionId>/subagents/agent-*.jsonl`, so a leg is a single
+ * conversation whose context window is its own. A file read once in the main
+ * leg and once inside a subagent is NOT a re-read — the second leg never had
+ * the first one's context — and {@link computeRereads} counts per leg for that
+ * reason.
+ *
+ * **The wasted-token figure is a `chars / 4` PROXY, not a measurement.** The
+ * transcript records no per-tool-result token count, so the size of a
+ * duplicate read is estimated from the JSON-encoded length of its
+ * `tool_result` body. Every caller must label it as a proxy; this module names
+ * the field `wasted_tokens_proxy` so the label cannot be dropped by accident.
+ *
+ * Read-only: no writes, no network, no spawn.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * Tools whose result is a file body the model already holds after the first
+ * call. Deliberately narrow: `Edit` and `Write` also carry a `file_path`, but
+ * re-reading after a mutation is correct behaviour, not waste, so counting
+ * them would manufacture "re-reads" out of the loop this measurement exists to
+ * distinguish from.
+ */
+export const READ_SHAPED_TOOLS: ReadonlySet<string> = new Set(['Read', 'NotebookRead']);
+
+/** One observed read-shaped tool call inside one leg. */
+export interface ReadEvent {
+    filePath: string;
+    /** JSON-encoded length of the matching `tool_result` body; 0 when no result was recorded. */
+    resultChars: number;
+}
+
+/** Per-path rollup across every leg that read it more than once. */
+export interface RereadFile {
+    file_path: string;
+    /** Total read-shaped calls on this path, across all legs. */
+    total_reads: number;
+    /** Reads beyond the first WITHIN a leg, summed over legs. */
+    duplicate_reads: number;
+    /** Number of legs in which this path was read at least twice. */
+    legs_with_reread: number;
+    /** `chars / 4` proxy over the duplicate reads only — never a measurement. */
+    wasted_tokens_proxy: number;
+}
+
+export interface RereadResult {
+    legs_scanned: number;
+    total_reads: number;
+    duplicate_reads: number;
+    wasted_tokens_proxy: number;
+    /** Only paths with at least one duplicate, ranked by `wasted_tokens_proxy` desc. */
+    files: RereadFile[];
+}
+
+function parseLine(line: string): Record<string, unknown> | null {
+    const t = line.trim();
+    if (t.length === 0) return null;
+    try {
+        const v = JSON.parse(t) as unknown;
+        return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+    } catch {
+        return null;
+    }
+}
+
+function contentBlocks(rec: Record<string, unknown>): Array<Record<string, unknown>> {
+    const msg = rec.message;
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return [];
+    const content = (msg as Record<string, unknown>).content;
+    if (!Array.isArray(content)) return [];
+    return content.filter((c): c is Record<string, unknown> => !!c && typeof c === 'object' && !Array.isArray(c));
+}
+
+function readPathOf(input: unknown): string | null {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+    const o = input as Record<string, unknown>;
+    for (const key of ['file_path', 'filePath', 'notebook_path', 'notebookPath']) {
+        const v = o[key];
+        if (typeof v === 'string' && v.length > 0) return v;
+    }
+    return null;
+}
+
+/**
+ * Every read-shaped call in one leg, in call order, each paired with the size
+ * of its result.
+ *
+ * Two passes on purpose: a `tool_result` can only be matched by
+ * `tool_use_id`, and nothing guarantees it appears after its `tool_use` in
+ * file order once a transcript has been resumed or replayed. An unreadable or
+ * malformed file yields `[]` — this is instrumentation, and a measurement that
+ * throws on one bad leg reports nothing about the other two thousand.
+ */
+export function collectReadEvents(file: string): ReadEvent[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+
+    const order: Array<{ id: string | null; filePath: string }> = [];
+    const sizes = new Map<string, number>();
+
+    for (const line of text.split('\n')) {
+        const rec = parseLine(line);
+        if (!rec) continue;
+        for (const block of contentBlocks(rec)) {
+            if (block.type === 'tool_use') {
+                if (typeof block.name !== 'string' || !READ_SHAPED_TOOLS.has(block.name)) continue;
+                const filePath = readPathOf(block.input);
+                if (filePath === null) continue;
+                order.push({ id: typeof block.id === 'string' ? block.id : null, filePath });
+            } else if (block.type === 'tool_result') {
+                const id = block.tool_use_id ?? block.toolUseId;
+                if (typeof id !== 'string') continue;
+                let chars = 0;
+                try {
+                    chars = JSON.stringify(block.content ?? '').length;
+                } catch {
+                    chars = 0;
+                }
+                sizes.set(id, chars);
+            }
+        }
+    }
+
+    return order.map((o) => ({
+        filePath: o.filePath,
+        resultChars: o.id === null ? 0 : (sizes.get(o.id) ?? 0),
+    }));
+}
+
+const CHARS_PER_TOKEN_PROXY = 4;
+
+/**
+ * Roll every leg up into a per-path re-read ranking.
+ *
+ * The duplicate count is per leg: the first read of a path in a leg is the
+ * cost of knowing it, every later read in the SAME leg is the waste. Legs are
+ * never joined, so a path read once in each of two legs contributes zero
+ * duplicates — see the module doc.
+ */
+export function computeRereads(files: readonly string[]): RereadResult {
+    const acc = new Map<string, RereadFile>();
+    let legsScanned = 0;
+    let totalReads = 0;
+
+    for (const file of files) {
+        const events = collectReadEvents(file);
+        legsScanned += 1;
+        if (events.length === 0) continue;
+
+        const seenInLeg = new Map<string, number>();
+        for (const ev of events) {
+            totalReads += 1;
+            const priorInLeg = seenInLeg.get(ev.filePath) ?? 0;
+            seenInLeg.set(ev.filePath, priorInLeg + 1);
+
+            const row = acc.get(ev.filePath) ?? {
+                file_path: ev.filePath,
+                total_reads: 0,
+                duplicate_reads: 0,
+                legs_with_reread: 0,
+                wasted_tokens_proxy: 0,
+            };
+            row.total_reads += 1;
+            if (priorInLeg >= 1) {
+                row.duplicate_reads += 1;
+                row.wasted_tokens_proxy += Math.round(ev.resultChars / CHARS_PER_TOKEN_PROXY);
+                if (priorInLeg === 1) row.legs_with_reread += 1;
+            }
+            acc.set(ev.filePath, row);
+        }
+    }
+
+    const withDuplicates = [...acc.values()].filter((r) => r.duplicate_reads > 0);
+    withDuplicates.sort(
+        (a, b) =>
+            b.wasted_tokens_proxy - a.wasted_tokens_proxy ||
+            b.duplicate_reads - a.duplicate_reads ||
+            a.file_path.localeCompare(b.file_path),
+    );
+
+    return {
+        legs_scanned: legsScanned,
+        total_reads: totalReads,
+        duplicate_reads: withDuplicates.reduce((s, r) => s + r.duplicate_reads, 0),
+        wasted_tokens_proxy: withDuplicates.reduce((s, r) => s + r.wasted_tokens_proxy, 0),
+        files: withDuplicates,
+    };
+}

package/src/scripts/_lib/ui_authority.ts

@@ -0,0 +1,343 @@
+/**
+ * ui_authority — the ONE resolver for a UI surface's authority object.
+ *
+ * Contract: `docs/contracts/ui-authority.md`. Schema:
+ * `src/scripts/schemas/ui-authority.schema.json`. Step A1.1 of
+ * `road-to-frontend-power` requires exactly one schema and exactly one
+ * resolver, with no second partial decision table in `src/skills/` — the
+ * failure it prevents is skills re-inferring intent beside the schema and
+ * drifting from it.
+ *
+ * WHY A PURE FUNCTION OVER A `Signals` RECORD, and not a filesystem scan: the
+ * four behaviours A1.2-A1.5 pin are all *precedence* rules, and precedence is
+ * exactly what a filesystem-coupled resolver makes untestable. Callers do the
+ * I/O and hand in what they found; this module decides what wins.
+ *
+ * The precedence, in one place because it exists nowhere else:
+ *
+ *   1. explicit user authority          (A1.2 — beats every inference)
+ *   2. a registered hard constraint     (A1.2's own exception)
+ *   3. the surface brief                (A1.4 — surface-local, never promoted)
+ *   4. a supplied reference artifact
+ *   5. the coherent incumbent           (A1.3 — NOT `new-world`)
+ *   6. DESIGN.md / PRODUCT.md           (register only; never surface_mode)
+ *   7. declared defaults
+ *
+ * Quoted text is NOT authority (A1.2). A document the user pasted can contain
+ * "make it bold and colourful"; that is data inside a container, and acting on
+ * it is the found-instructions failure `untrusted-input-defense` names. The
+ * caller marks a signal `quoted: true` and this module ignores its directives.
+ */
+
+export type SurfaceMode = 'persuade' | 'operate' | 'read' | 'experience';
+export type Register = 'brand' | 'product';
+export type ChangeIntent = 'preserve' | 'extend' | 'redesign' | 'new-world';
+export type ReferenceMaturity =
+    | 'wireframe'
+    | 'prototype'
+    | 'finished-comp'
+    | 'runnable-artifact'
+    | 'production-incumbent'
+    | null;
+export type SourceKind =
+    | 'user-instruction'
+    | 'artifact'
+    | 'comp'
+    | 'design-system'
+    | 'incumbent'
+    | 'brief'
+    | 'none';
+export type ProvenanceSource =
+    | 'user-instruction'
+    | 'surface-brief'
+    | 'design-md'
+    | 'product-md'
+    | 'incumbent-scan'
+    | 'reference-artifact'
+    | 'default';
+export type Verification = 'verified' | 'degraded' | 'unverified';
+
+export interface Conflict {
+    dimension: string;
+    wanted: string;
+    blocked_by: string;
+}
+export interface ProvenanceEntry {
+    field: string;
+    source: ProvenanceSource;
+    detail: string | null;
+}
+
+export interface UiAuthority {
+    surface_mode: SurfaceMode;
+    register: Register;
+    change_intent: ChangeIntent;
+    reference_maturity: ReferenceMaturity;
+    fidelity_mandate: string | null;
+    primary_source: { kind: SourceKind; path: string | null };
+    constraints: {
+        preserve_palette?: boolean;
+        preserve_type_family?: boolean;
+        preserve_layout?: boolean;
+        preserve_copy?: boolean;
+    };
+    conflicts: Conflict[];
+    provenance: ProvenanceEntry[];
+    verification: Verification;
+    degradation_reason?: string | null;
+}
+
+/** What a caller found. Every field optional — absence is a real input. */
+export interface Signals {
+    /** Explicit, unquoted user authority. Beats every inference (A1.2). */
+    user?: {
+        surface_mode?: SurfaceMode;
+        register?: Register;
+        change_intent?: ChangeIntent;
+        /** True when the text came from INSIDE a supplied document (A1.2). */
+        quoted?: boolean;
+    };
+    /** A surface-local brief. Never mutates DESIGN.md / PRODUCT.md (A1.4). */
+    brief?: { surface_mode?: SurfaceMode; register?: Register; path?: string };
+    /** A supplied reference and how finished it is. */
+    reference?: { maturity: Exclude<ReferenceMaturity, null>; path?: string };
+    /** Result of an incumbent scan — typically from `ui:audit`. */
+    incumbent?: { coherent: boolean; palette?: string[]; type_families?: string[] };
+    /** Presence and register of the repo-level documents. */
+    design_md?: { present: boolean; register?: Register };
+    product_md?: { present: boolean; register?: Register };
+    /** Carried from the fidelity roadmap's Phase 0, never derived here. */
+    fidelity_mandate?: string | null;
+    /** A registered hard constraint outranks even explicit user authority. */
+    hard_constraints?: Array<keyof UiAuthority['constraints']>;
+}
+
+/** Declared defaults, in one place so "where did this come from" has an answer. */
+export const DEFAULTS = {
+    surface_mode: 'operate' as SurfaceMode,
+    register: 'product' as Register,
+    change_intent: 'extend' as ChangeIntent,
+} as const;
+
+/**
+ * A1.5's threshold, pre-registered in `internal/bench/frontend-power-PREREG.md`
+ * § A1.5's delta threshold and NOT chosen here. Palette and type family only —
+ * spacing, radius, weight, size and layout are deliberately excluded so
+ * `polish` and `refine` can move them under `preserve`, which is the whole
+ * point of those verbs.
+ */
+export const PRESERVE_DELTA_DIMENSIONS = ['palette', 'type_family'] as const;
+/** Colour keywords that are never a palette delta. */
+const PALETTE_NEUTRALS = new Set(['transparent', 'currentcolor', 'inherit', 'unset', 'initial']);
+
+export function resolveUiAuthority(signals: Signals = {}): UiAuthority {
+    const provenance: ProvenanceEntry[] = [];
+    const conflicts: Conflict[] = [];
+    const note = (field: string, source: ProvenanceSource, detail: string | null = null): void => {
+        provenance.push({ field, source, detail });
+    };
+
+    // A1.2 — quoted text inside a supplied document is data, not authorisation.
+    const user = signals.user?.quoted ? undefined : signals.user;
+
+    // surface_mode: user → brief → default. DESIGN.md/PRODUCT.md never supply
+    // it (A2.1: the surface job is per-surface, persisted in the brief).
+    let surface_mode: SurfaceMode;
+    if (user?.surface_mode) {
+        surface_mode = user.surface_mode;
+        note('surface_mode', 'user-instruction');
+    } else if (signals.brief?.surface_mode) {
+        surface_mode = signals.brief.surface_mode;
+        note('surface_mode', 'surface-brief', signals.brief.path ?? null);
+    } else {
+        surface_mode = DEFAULTS.surface_mode;
+        note('surface_mode', 'default', 'no user or brief signal');
+    }
+
+    // register: user → brief → DESIGN.md → PRODUCT.md → default. The brief
+    // outranks PRODUCT.md, which is the `surface-mode-not-product-mode` case:
+    // a brand surface inside a product repo must not inherit `product`.
+    let register: Register;
+    if (user?.register) {
+        register = user.register;
+        note('register', 'user-instruction');
+    } else if (signals.brief?.register) {
+        register = signals.brief.register;
+        note('register', 'surface-brief', signals.brief.path ?? null);
+    } else if (signals.design_md?.present && signals.design_md.register) {
+        register = signals.design_md.register;
+        note('register', 'design-md');
+    } else if (signals.product_md?.present && signals.product_md.register) {
+        register = signals.product_md.register;
+        note('register', 'product-md');
+    } else {
+        register = DEFAULTS.register;
+        note('register', 'default', 'no register signal');
+    }
+
+    // change_intent: user → (incumbent coherence) → default.
+    //
+    // A1.3 is the load-bearing branch: a MISSING DESIGN.md is not `new-world`.
+    // A coherent incumbent resolves to `extend` with incumbent authority, and
+    // only a genuinely empty surface — no incumbent, no reference — is
+    // `new-world`.
+    let change_intent: ChangeIntent;
+    if (user?.change_intent) {
+        change_intent = user.change_intent;
+        note('change_intent', 'user-instruction');
+    } else if (signals.incumbent?.coherent) {
+        change_intent = 'extend';
+        note('change_intent', 'incumbent-scan', 'coherent incumbent — not new-world (A1.3)');
+    } else if (!signals.incumbent && !signals.reference && !signals.design_md?.present) {
+        change_intent = 'new-world';
+        note('change_intent', 'default', 'no incumbent, no reference, no DESIGN.md');
+    } else {
+        change_intent = DEFAULTS.change_intent;
+        note('change_intent', 'default', 'incumbent present but incoherent');
+    }
+
+    const reference_maturity: ReferenceMaturity = signals.reference?.maturity ?? null;
+    note(
+        'reference_maturity',
+        signals.reference ? 'reference-artifact' : 'default',
+        signals.reference?.path ?? 'no reference supplied',
+    );
+
+    // primary_source — which authority the run builds FROM.
+    let kind: SourceKind = 'none';
+    let sourcePath: string | null = null;
+    if (signals.reference) {
+        kind =
+            signals.reference.maturity === 'runnable-artifact'
+                ? 'artifact'
+                : signals.reference.maturity === 'finished-comp'
+                  ? 'comp'
+                  : signals.reference.maturity === 'production-incumbent'
+                    ? 'incumbent'
+                    : 'brief';
+        sourcePath = signals.reference.path ?? null;
+    } else if (signals.incumbent?.coherent) {
+        kind = 'incumbent';
+    } else if (signals.design_md?.present) {
+        kind = 'design-system';
+    } else if (signals.brief) {
+        kind = 'brief';
+        sourcePath = signals.brief.path ?? null;
+    } else if (user) {
+        kind = 'user-instruction';
+    }
+    note('primary_source', signals.reference ? 'reference-artifact' : 'incumbent-scan', kind);
+
+    // constraints — `preserve` implies the visual world is locked. A hard
+    // constraint is additive and, per A1.2, outranks explicit user authority.
+    const constraints: UiAuthority['constraints'] = {};
+    if (change_intent === 'preserve') {
+        constraints.preserve_palette = true;
+        constraints.preserve_type_family = true;
+    }
+    for (const c of signals.hard_constraints ?? []) {
+        if (constraints[c] === false) {
+            conflicts.push({
+                dimension: c,
+                wanted: 'released by user instruction',
+                blocked_by: 'registered hard constraint',
+            });
+        }
+        constraints[c] = true;
+    }
+
+    return {
+        surface_mode,
+        register,
+        change_intent,
+        reference_maturity,
+        fidelity_mandate: signals.fidelity_mandate ?? null,
+        primary_source: { kind, path: sourcePath },
+        constraints,
+        conflicts,
+        provenance,
+        verification: 'verified',
+    };
+}
+
+/** Mark an object degraded. Refuses a reason-free degrade by construction. */
+export function degrade(a: UiAuthority, reason: string, state: Exclude<Verification, 'verified'> = 'degraded'): UiAuthority {
+    if (!reason.trim()) throw new Error('degrade() requires a non-empty degradation_reason');
+    return { ...a, verification: state, degradation_reason: reason };
+}
+
+export interface WorldSnapshot {
+    palette: readonly string[];
+    type_families: readonly string[];
+}
+
+const norm = (s: string): string => s.trim().toLowerCase();
+
+/**
+ * A1.5 — the intent-aware gate. Returns the dimensions that changed and are
+ * NOT authorised by `change_intent`. Empty array = the write may proceed.
+ *
+ * Under `preserve` a palette or type-family delta blocks; under `redesign` and
+ * `new-world` nothing here blocks. `extend` sits in between and is treated as
+ * permissive on this axis deliberately: extending a surface routinely adds a
+ * semantic colour, and blocking that would make the verb unusable.
+ */
+export function preserveViolations(
+    authority: UiAuthority,
+    incumbent: WorldSnapshot,
+    proposed: WorldSnapshot,
+): string[] {
+    if (authority.change_intent !== 'preserve') return [];
+    const out: string[] = [];
+
+    if (authority.constraints.preserve_palette) {
+        const known = new Set(incumbent.palette.map(norm));
+        const added = proposed.palette.map(norm).filter((c) => !known.has(c) && !PALETTE_NEUTRALS.has(c));
+        if (added.length) out.push(`palette: ${[...new Set(added)].sort().join(', ')}`);
+    }
+    if (authority.constraints.preserve_type_family) {
+        const known = new Set(incumbent.type_families.map(norm));
+        const added = proposed.type_families.map(norm).filter((f) => !known.has(f));
+        if (added.length) out.push(`type_family: ${[...new Set(added)].sort().join(', ')}`);
+    }
+    return out;
+}
+
+/**
+ * A4.1 — the six intervention operations as values of ONE field rather than as
+ * six commands. Each declares the dimensions it may touch, so a collision with
+ * a constraint is decidable instead of a judgement call.
+ */
+export const OPERATIONS = {
+    polish: ['spacing', 'rhythm', 'alignment'],
+    quieter: ['spacing', 'weight', 'contrast_within_palette'],
+    bolder: ['palette', 'type_family', 'weight', 'scale'],
+    distill: ['content_density', 'spacing'],
+    harden: ['a11y', 'focus', 'contrast_within_palette'],
+    clarify: ['hierarchy', 'copy', 'labels'],
+} as const;
+export type Operation = keyof typeof OPERATIONS;
+
+/** Maps an operation dimension onto the constraint that would forbid it. */
+const DIMENSION_CONSTRAINT: Readonly<Record<string, keyof UiAuthority['constraints']>> = {
+    palette: 'preserve_palette',
+    type_family: 'preserve_type_family',
+    hierarchy: 'preserve_layout',
+    copy: 'preserve_copy',
+    labels: 'preserve_copy',
+};
+
+/**
+ * A4.1 — does `op` collide with the authority's constraints? A collision is
+ * returned as conflicts to APPEND; the caller performs no write. `bolder`
+ * under `preserve` is the pinned case.
+ */
+export function operationConflicts(authority: UiAuthority, op: Operation): Conflict[] {
+    const out: Conflict[] = [];
+    for (const dim of OPERATIONS[op] as readonly string[]) {
+        const c = DIMENSION_CONSTRAINT[dim];
+        if (!c || authority.constraints[c] !== true) continue;
+        out.push({ dimension: dim, wanted: `${op} may move ${dim}`, blocked_by: c });
+    }
+    return out;
+}

package/src/scripts/ai-video/adapters/fal.sh

@@ -288,9 +288,14 @@ aiv_fal_capability() {
     jq -e --arg m "${model}" '.models[$m]' "${FAL_MANIFEST}" >/dev/null 2>&1 \
       || aiv_die 7 "${ADAPTER_ID}: model not in manifest: ${model}"
     _fal_warn_unverified "${model}"
-    jq --arg m "${model}" \
-      '.models[$m] | {audio: (if .audio_sync then "native" else "none" end), model: $m} + .' \
-      "${FAL_MANIFEST}"
+    # Emission goes through the shared helper so the decay markers
+    # (`verified_at` / `recheck_by`, derived from the trace index) appear here
+    # too. fal is the adapter that actually CARRIES smoke_trace ids, so a
+    # capability path that skipped them would leave the only traced adapter as
+    # the one place the dates are invisible. Model validation, the
+    # manifest-missing check and the unverified warning stay above — this
+    # replaces the JSON emission only.
+    aiv_capability_recheck "${ADAPTER_ID}" "${model}" "${FAL_MANIFEST}"
     return 0
   fi
   if [ -f "${FAL_MANIFEST}" ] && command -v jq >/dev/null 2>&1; then