@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/credential_files.ts

@@ -0,0 +1,367 @@
+/**
+ * Which files hold credentials by construction, and which commands print the
+ * process environment — the one list the `pre_tool_use` read guard
+ * (`hooks/block_credential_reads.ts`) and the installer's native deny tier read
+ * (road-to-one-detector-and-the-senders-we-own 1.1, 1.2).
+ *
+ * Prevention is the only fail-closed layer the egress work has: a value that is
+ * never read cannot leak through any later bug. So the classes are file KINDS,
+ * decided from the path alone, never from content — the guard runs before the
+ * file is opened.
+ *
+ * What a path-text guard cannot see, and so does not catch: a glob or an
+ * expansion that names the file only after the shell runs (`cat .e*`,
+ * `cat .e[n]v`, `$(echo .env)`), a recursive search that never names it, and
+ * an interpreter that prints the environment (`node -e 'console.log(process.env)'`,
+ * `python -c …`). Those reach the egress stage as tool output, not here.
+ *
+ * Pure: no I/O. The one import is `node:path`'s POSIX normaliser.
+ */
+import * as path from 'node:path';
+
+export type CredentialFileClass =
+    | 'env-file'
+    | 'private-key'
+    | 'cloud-credentials'
+    | 'registry-credentials'
+    | 'process-environment';
+
+/** What each class is, for a refusal a reader can act on. */
+export const CREDENTIAL_CLASS_LABEL: Readonly<Record<CredentialFileClass, string>> = {
+    'env-file': 'an environment file (.env)',
+    'private-key': 'a private key',
+    'cloud-credentials': 'a cloud or CLI credential file',
+    'registry-credentials': 'a package-registry credential file',
+    'process-environment': 'a process environment',
+};
+
+/** `.env.<suffix>` names that document keys rather than hold values. */
+const ENV_TEMPLATE_SUFFIXES: ReadonlySet<string> = new Set(['example', 'sample', 'template', 'dist', 'defaults', 'schema']);
+
+const KEY_EXTENSIONS: readonly string[] = ['.key', '.p12', '.pfx', '.ppk', '.jks', '.keystore'];
+/**
+ * `.pem` holds public certificates as often as private keys, so it counts only
+ * when the name says key: `server-key.pem`, `private.pem`, `id_rsa.pem` refuse;
+ * `ca.pem`, `cert.pem`, `chain.pem` pass. The cost, accepted: a private key named
+ * like a certificate is not caught by name.
+ */
+const KEY_PEM_NAME = /(?:^|[-_.])(?:key|private|secret)(?:$|[-_.])|^id_/i;
+const SSH_KEY = /^id_(?:rsa|dsa|ecdsa|ed25519)(?:_sk)?$/;
+
+/** Path tails (after a `/` or at the start) of cloud, CLI and registry credential files. */
+const CREDENTIAL_TAILS: ReadonlyArray<readonly [string, CredentialFileClass]> = [
+    ['.aws/credentials', 'cloud-credentials'],
+    ['.config/gcloud/application_default_credentials.json', 'cloud-credentials'],
+    // cache-invalidation: not a cache this package writes — gcloud's own credential store, named only to refuse reading it
+    ['.config/gcloud/credentials.db', 'cloud-credentials'],
+    ['.azure/accessTokens.json', 'cloud-credentials'],
+    ['.azure/msal_token_cache.json', 'cloud-credentials'],
+    ['.kube/config', 'cloud-credentials'],
+    ['.docker/config.json', 'cloud-credentials'],
+    ['.config/gh/hosts.yml', 'cloud-credentials'],
+    ['.git-credentials', 'cloud-credentials'],
+    ['.my.cnf', 'registry-credentials'],
+    ['.pgpass', 'registry-credentials'],
+    ['.npmrc', 'registry-credentials'],
+    ['.pypirc', 'registry-credentials'],
+    ['.netrc', 'registry-credentials'],
+    ['_netrc', 'registry-credentials'],
+    ['.gem/credentials', 'registry-credentials'],
+    ['.cargo/credentials', 'registry-credentials'],
+    ['.cargo/credentials.toml', 'registry-credentials'],
+    ['.composer/auth.json', 'registry-credentials'],
+    ['.config/composer/auth.json', 'registry-credentials'],
+];
+
+/** A process's environment, and each of its threads' (`/proc/self/task/<tid>/environ`). */
+const PROC_ENVIRON = /^\/proc\/[^/]+(?:\/task\/[^/]+)?\/environ$/;
+
+/**
+ * The host whose filesystem decides what a path names. A backslash separates
+ * path segments on Windows only: on a POSIX host it is a filename character, so
+ * `'dir\\.env'` — and `'C:\\project\\.env'` too — is one file there, not `.env`.
+ * Read from the platform, never from the path's spelling; callers that judge a
+ * path for another host pass it.
+ */
+export type PathHost = 'posix' | 'windows';
+export const HOST: PathHost = process.platform === 'win32' ? 'windows' : 'posix';
+
+const separated = (p: string, host: PathHost): string => (host === 'windows' ? p.replace(/\\/g, '/') : p);
+
+/** The credential class of a path, or null. Decided from the path alone. */
+export function credentialFileClass(rawPath: string, host: PathHost = HOST): CredentialFileClass | null {
+    const trimmed = separated(rawPath.trim(), host).replace(/\/+$/, '');
+    if (trimmed === '') return null;
+    // `.` and `..` segments resolved, so `/proc/self/../self/environ` is the file it names.
+    const p = path.posix.normalize(trimmed);
+    if (PROC_ENVIRON.test(p)) return 'process-environment';
+    // Compared case-folded: on the default macOS and Windows filesystems `.ENV`
+    // and `ID_RSA` open the same file. On a case-sensitive one this refuses a
+    // differently-cased neighbour too, which is the side a read guard errs on.
+    const lp = p.toLowerCase();
+    const lower = lp.slice(lp.lastIndexOf('/') + 1);
+    if (lower === '.env' || lower === '.envrc') return 'env-file';
+    if (lower.startsWith('.env.')) {
+        // The LAST suffix decides: `.env.local.example` documents keys, `.env.local` holds values.
+        const last = lower.slice(lower.lastIndexOf('.') + 1);
+        return ENV_TEMPLATE_SUFFIXES.has(last) ? null : 'env-file';
+    }
+    if (SSH_KEY.test(lower)) return 'private-key';
+    if (KEY_EXTENSIONS.some((ext) => lower.endsWith(ext) && lower.length > ext.length)) return 'private-key';
+    if (lower.endsWith('.pem') && KEY_PEM_NAME.test(lower.slice(0, -4))) return 'private-key';
+    for (const [tail, cls] of CREDENTIAL_TAILS) {
+        const t = tail.toLowerCase();
+        if (lp === t || lp.endsWith(`/${t}`)) return cls;
+    }
+    return null;
+}
+
+/**
+ * Command words that act on a path without printing or executing what it holds.
+ * A credential path given to any other command is treated as a read, because
+ * the set of commands that print a file is open and the set that do not is
+ * small. `cp`, `mv`, `source` and `.` are NOT here: `cp .env /dev/stdout` prints
+ * it, `source .env` runs it, and a copy or a rename launders the path for the
+ * next command.
+ */
+const NON_READING_COMMANDS: ReadonlySet<string> = new Set([
+    'ls', 'stat', 'test', '[', 'touch', 'rm', 'chmod', 'chown', 'mkdir', 'wc',
+]);
+
+/**
+ * Words that run the command after them: `sudo`, `nice`, `timeout`, …. Their
+ * option grammars differ and clustering (`sudo -nu root`) defeats any table of
+ * them, so a segment that starts with one is judged conservatively instead of
+ * parsed: any credential path anywhere in it refuses, and so does an `env` or a
+ * `printenv` anywhere in it.
+ */
+const WRAPPERS: ReadonlySet<string> = new Set([
+    'command', 'builtin', 'exec', 'nohup', 'sudo', 'doas', 'nice', 'timeout', 'stdbuf', 'time', 'xargs', 'watch', 'unbuffer',
+]);
+
+/** `git` subcommands that name a path without printing its content. */
+const NON_READING_GIT: ReadonlySet<string> = new Set(['add', 'rm', 'mv', 'check-ignore', 'ls-files', 'status']);
+
+/**
+ * Split one command segment into words the way the shell joins them: quoted
+ * and unquoted runs with no space between them are one word (`-S'cat .env'` is
+ * `-Scat .env`), quotes are removed, and a backslash escapes the next character.
+ */
+export function commandWords(segment: string): string[] {
+    const words: string[] = [];
+    let word = '';
+    let inWord = false;
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i] as string;
+        if (/\s/.test(ch)) {
+            if (inWord) words.push(word);
+            word = '';
+            inWord = false;
+            continue;
+        }
+        inWord = true;
+        if (ch === "'") {
+            const end = segment.indexOf("'", i + 1);
+            word += segment.slice(i + 1, end === -1 ? segment.length : end);
+            i = end === -1 ? segment.length : end;
+        } else if (ch === '"') {
+            // Inside double quotes a backslash escapes only $ ` " \ and a newline.
+            let j = i + 1;
+            for (; j < segment.length && segment[j] !== '"'; j += 1) {
+                if (segment[j] === '\\' && segment[j + 1] === '\n') {
+                    j += 1; // a line continuation: both characters go
+                    continue;
+                }
+                if (segment[j] === '\\' && j + 1 < segment.length && '$`"\\'.includes(segment[j + 1] as string)) j += 1;
+                word += segment[j];
+            }
+            i = j;
+        } else if (ch === '\\' && i + 1 < segment.length) {
+            // An escaped character joins the word; an escaped newline is a continuation and adds nothing.
+            if (segment[i + 1] !== '\n') word += segment[i + 1];
+            i += 1;
+        } else {
+            word += ch;
+        }
+    }
+    if (inWord) words.push(word);
+    return words;
+}
+
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+type Verdict = { class: CredentialFileClass; what: string } | null;
+
+/** The basename a refusal may name: backslashes read as separators, so no Windows path leaks whole. */
+export function credentialBasename(p: string): string {
+    return path.posix.basename(p.replace(/\\/g, '/'));
+}
+
+const named = (cls: CredentialFileClass, p: string): Verdict => ({ class: cls, what: `\`${credentialBasename(p)}\`` });
+const base = (w: string): string => w.replace(/^.*\//, '');
+
+/**
+ * The first credential path mentioned anywhere in `text`, read from the raw
+ * characters rather than from parsed words: the text is cut at every character
+ * a path cannot hold unquoted — whitespace, quotes, redirections, pipes,
+ * separators, parentheses, `=`, `,`, backticks — so `cat<.env`, `--config=.env`
+ * and `<(cat .env)` all expose the path, and an attached short option
+ * (`xargs -a.env`) is read both whole and without its `-x` prefix. On a Windows
+ * host a backslash path is a path: `credentialFileClass` separates on it there.
+ */
+export function credentialMention(text: string, host: PathHost = HOST): Verdict {
+    // Two readings of one segment, because neither alone matches the shell: the
+    // raw text (an attached `cat<.env`, `--config=.env`), and each word the shell
+    // would build — quotes joined, escapes applied only where the shell applies
+    // them (`cat .e''nv`, an unquoted `cat .e\nv`) — each cut at the same
+    // characters. In the raw text a backslash is still the shell's to consume,
+    // so it never separates there; the host decides only for a built word, where
+    // a surviving backslash is a filename character the filesystem reads.
+    //
+    // One exception, conservative on purpose: the segment arrives with the quotes
+    // of its command word already removed (`invokedSegments` strips them so
+    // `np''m` is npm), so `cat<"C:\x\.env"` and `cat<C:\x\.env` reach here as the
+    // same text. A redirection attached to the command word is therefore judged
+    // as the filesystem would read it, uncooked: on a Windows host it refuses
+    // both, the second a false positive this guard accepts rather than miss the first.
+    const head = /^\S*[<>]\S*/.exec(text.trimStart())?.[0];
+    const readings: ReadonlyArray<readonly [string, PathHost]> = [
+        [text, 'posix'],
+        ...(head === undefined ? [] : [[head, host] as const]),
+        ...commandWords(text).map((w) => [w, host] as const),
+    ];
+    for (const [reading, readingHost] of readings) {
+        const v = mentionIn(reading, readingHost);
+        if (v !== null) return v;
+    }
+    return null;
+}
+
+function mentionIn(text: string, host: PathHost): Verdict {
+    for (const raw of text.split(/[\s'"<>|;&()`=,]+/)) {
+        if (raw === '') continue;
+        const candidates = raw.startsWith('-') ? [raw, raw.replace(/^-+[A-Za-z]?/, '')] : [raw];
+        for (const c of candidates) {
+            const cls = c === '' ? null : credentialFileClass(c, host);
+            if (cls !== null) return named(cls, c);
+        }
+    }
+    return null;
+}
+
+/** The first credential path among words the shell already built — judged as data, never re-parsed. */
+function credentialAmong(words: readonly string[], host: PathHost): Verdict {
+    for (const w of words) {
+        const v = mentionIn(w, host);
+        if (v !== null) return v;
+    }
+    return null;
+}
+
+/**
+ * `env`'s arguments with each `-S`/`--split-string` value spliced in as the
+ * arguments it stands for, then its options and assignments skipped. Returns the
+ * command it runs, or an empty list when it runs none and prints the
+ * environment. A short option cluster ending in `u`, `C` or `S` takes the next
+ * word, `--unset`/`--chdir` take the next word, and a `NAME` operand after them
+ * is the variable they name.
+ */
+export function envCommand(args: readonly string[]): string[] {
+    const stream: string[] = [];
+    for (let k = 0; k < args.length; k += 1) {
+        const a = args[k] as string;
+        if (a === '-S' || a === '--split-string') {
+            stream.push(...commandWords(args[k + 1] ?? ''));
+            k += 1;
+        } else if (/^--split-string=/.test(a) || /^-[a-zA-Z]*S.+$/.test(a)) {
+            stream.push(...commandWords(a.startsWith('--') ? a.slice('--split-string='.length) : a.slice(a.indexOf('S') + 1)));
+        } else {
+            stream.push(a);
+        }
+    }
+    let i = 0;
+    while (i < stream.length) {
+        const w = stream[i] as string;
+        if (w === '--') {
+            i += 1;
+            break;
+        }
+        if (w.startsWith('-') && w !== '-') {
+            i += w === '--unset' || w === '--chdir' || /^-[a-zA-Z]*[uC]$/.test(w) ? 2 : 1;
+            continue;
+        }
+        if (ASSIGNMENT.test(w)) {
+            i += 1;
+            continue;
+        }
+        break;
+    }
+    while (i < stream.length && ASSIGNMENT.test(stream[i] as string)) i += 1;
+    return stream.slice(i);
+}
+
+/**
+ * The sources of a `cp` or `mv`: every operand but the destination, or every
+ * operand when a target directory is named (`-t DIR`, a cluster ending in `t`,
+ * `-tDIR`, `--target-directory[=DIR]`). `-S`/`--suffix` take the next word.
+ */
+export function copySources(args: readonly string[]): string[] {
+    const operands: string[] = [];
+    let targetGiven = false;
+    for (let k = 0; k < args.length; k += 1) {
+        const a = args[k] as string;
+        if (a === '--target-directory' || /^-[a-zA-Z]*t$/.test(a)) {
+            targetGiven = true;
+            k += 1;
+        } else if (/^--target-directory=/.test(a) || /^-[a-zA-Z]*t.+$/.test(a)) {
+            targetGiven = true;
+        } else if (a === '-S' || a === '--suffix') {
+            k += 1;
+        } else if (!a.startsWith('-') || a === '-') {
+            operands.push(a);
+        }
+    }
+    return targetGiven ? operands : operands.slice(0, -1);
+}
+
+/** Why a command segment is refused, or null. `segment` starts at its command word. */
+export function segmentVerdict(segment: string, host: PathHost = HOST, depth = 0): Verdict {
+    const words = commandWords(segment);
+    let i = 0;
+    while (i < words.length && ASSIGNMENT.test(words[i] as string)) i += 1;
+    const cmd = base(words[i] ?? '');
+    const args = words.slice(i + 1);
+
+    if (WRAPPERS.has(cmd)) {
+        if (args.some((a) => base(a) === 'env' || base(a) === 'printenv')) {
+            return { class: 'process-environment', what: `\`${cmd} … env\`` };
+        }
+        return credentialMention(segment, host);
+    }
+    if (cmd === 'env') {
+        const ran = envCommand(args);
+        if (ran.length === 0) return { class: 'process-environment', what: '`env`' };
+        if (depth >= 3) return credentialAmong(ran, host);
+        return segmentVerdict(ran.map((w) => (/\s/.test(w) ? `'${w}'` : w)).join(' '), host, depth + 1) ?? credentialAmong(args, host);
+    }
+
+    const operands = args.filter((a) => !a.startsWith('-'));
+    // Printing the whole environment: `printenv` with no name, `export` with no
+    // name, a bare `set` (`set -e` only sets options), and `declare -x|-p` with
+    // no name.
+    const dumpsEnv =
+        (cmd === 'printenv' && !operands.some((a) => VARIABLE_NAME.test(a))) ||
+        (cmd === 'export' && operands.length === 0) ||
+        (cmd === 'set' && args.length === 0) ||
+        ((cmd === 'declare' || cmd === 'typeset') && operands.length === 0 && args.some((a) => /^-[a-zA-Z]*[xp]/.test(a)));
+    if (dumpsEnv) return { class: 'process-environment', what: `\`${cmd}\`` };
+
+    // A copy or a rename reads its sources and only writes its destination:
+    // `cp .env.example .env` creates the file, while `cp .env /dev/stdout` prints
+    // it and `cp .env x` or `mv .env x` launders it for the next command.
+    if (cmd === 'cp' || cmd === 'mv') return credentialAmong(copySources(args), host);
+
+    const reads = !(NON_READING_COMMANDS.has(cmd) || (cmd === 'git' && NON_READING_GIT.has(operands[0] ?? '')));
+    return reads ? credentialMention(segment, host) : null;
+}

package/src/scripts/_lib/delivery_arm_experiment.ts

@@ -3,7 +3,7 @@
  *
  * WHAT 6.1 ASKS, AND WHY IT IS NOT THE PRICE GRID. Step 6.1 says: measure
  * `eager-all` against `thin` against `delivery` — the three values
- * `_lib/lean_projection_mode.ts:19` already declares — BEFORE any new retrieval
+ * `_lib/lean_projection_mode.ts` `LeanProjectionMode` already declares — BEFORE any new retrieval
  * component is written. `model_rule_injection.ts` already prices those three
  * shapes, and a price grid is a cost model rather than a delivery measurement:
  * it reports what each shape COSTS and never what each shape DELIVERS. The
@@ -236,7 +236,7 @@ export function renderArmExperiment(rows: readonly ArmRow[], capBytes: number):
 
     push('── three-arm delivery experiment (road-to-governed-harness-evolution 6.1) ──');
     push(
-        `arms = LeanProjectionMode (_lib/lean_projection_mode.ts:19) · ` +
+        `arms = LeanProjectionMode (_lib/lean_projection_mode.ts) · ` +
             `one corpus · one matcher (_lib/router_match.ts) · cap ${capBytes} B`,
     );
     push('');

package/src/scripts/_lib/depth_flip.ts

@@ -0,0 +1,141 @@
+/**
+ * Where a lowered ceremony depth may apply, and when it must stop applying.
+ *
+ * The owner's decision of 2026-10-21 (option (d) of the
+ * `class-depth-flip-reopens-the-risk-null` blocker) allows a lower depth only
+ * on steps whose every changed path is structurally safe — prose about the work
+ * rather than the work, or a test fixture — and only once the shadow reading
+ * clears the pre-registered threshold. A sampled full-depth audit then keeps
+ * reading each lowered class, and a class whose sampled escapes exceed the same
+ * threshold returns to full depth without anyone having to notice.
+ */
+import { createHash } from 'node:crypto';
+
+import type { RiskClass } from '../classify_change_risk.js';
+
+/**
+ * Paths whose risk the path itself bounds.
+ *
+ * Narrower than R0 on purpose: R0 admits every `.md`, and in this repository a
+ * rule, a skill, a contract, a guideline agents read before coding, or a record
+ * that grants authority (an owner directive, a ratification) is markdown that
+ * changes what agents do. Those stay at full depth whatever their extension.
+ */
+export const SAFE_PATH_PATTERNS: readonly RegExp[] = [
+    /^agents\/roadmaps\/.+\.md$/,
+    /^agents\/evidence\/(?!owner-directives\/|ratifications\/).+\.md$/,
+    /^docs\/(?!contracts\/|decisions\/|guidelines\/).+\.md$/,
+    /^README\.md$/,
+    /(^|\/)tests?\/(.+\/)?fixtures?\//,
+];
+
+export function isStructurallySafe(paths: readonly string[]): boolean {
+    return paths.length > 0 && paths.every((p) => SAFE_PATH_PATTERNS.some((re) => re.test(p.replace(/^\.\//, ''))));
+}
+
+export interface FlipThreshold {
+    /** Steps (or audit samples) a class needs before its figures are read. */
+    min_steps: number;
+    /** Escaped high/critical findings tolerated across those steps. */
+    max_escaped: number;
+    max_critical: number;
+}
+
+export interface FlipBlock {
+    scope: 'structurally-safe-paths';
+    classes: RiskClass[];
+    requires: FlipThreshold;
+    /** Repo-relative path of the committed reading that cleared `requires`; null until then. */
+    reading: string | null;
+}
+
+export interface AuditSample {
+    step: string;
+    cls: RiskClass;
+    escaped: boolean;
+    critical: boolean;
+    date: string;
+}
+
+export interface ParsedReceipt {
+    cls: RiskClass;
+    mode: 'shadow' | 'active';
+    /** The receipt was written for a step whose every path is structurally safe. */
+    safe: boolean;
+}
+
+const RECEIPT_LINE = /<!--\s*receipt:\s*class=(R[0-3])\s*·\s*(shadow|active)\b([^>]*)-->/;
+
+export function parseReceipt(line: string): ParsedReceipt | null {
+    const m = RECEIPT_LINE.exec(line);
+    if (m === null) return null;
+    return { cls: m[1] as RiskClass, mode: m[2] as 'shadow' | 'active', safe: /·\s*scope=safe\b/.test(m[3] ?? '') };
+}
+
+/** Ticked steps of `cls` whose receipt reads `active` — the lowered steps so far, from the roadmaps themselves. */
+export function lowersSoFar(roadmapTexts: readonly string[], cls: RiskClass): number {
+    let n = 0;
+    for (const text of roadmapTexts) {
+        for (const line of text.split('\n')) {
+            if (!/^\s*-\s\[x\]\s/.test(line)) continue;
+            const r = parseReceipt(line);
+            if (r !== null && r.cls === cls && r.mode === 'active') n += 1;
+        }
+    }
+    return n;
+}
+
+/**
+ * Whether the step is audited at full depth after merge: 1 in 4 of a class's
+ * first `min_steps` lowered steps, 1 in 10 after. Seeded by the step key alone,
+ * so anyone re-running it on the same key gets the same answer.
+ */
+export function sampledForAudit(stepKey: string, lowersSoFar: number, threshold: FlipThreshold): boolean {
+    const every = lowersSoFar < threshold.min_steps ? 4 : 10;
+    const digest = createHash('sha256').update(`depth-audit-v1:${stepKey}`).digest();
+    return digest.readUInt32BE(0) % every === 0;
+}
+
+/**
+ * Classes whose audit samples have broken the threshold, read over the latest
+ * `min_steps` samples. A window still filling up is read too: a second escape
+ * or a critical among fewer samples has already broken the threshold, and
+ * waiting for thirty would keep a class lowered after it failed.
+ */
+export function rolledBackClasses(samples: readonly AuditSample[], threshold: FlipThreshold): RiskClass[] {
+    const byClass = new Map<RiskClass, AuditSample[]>();
+    for (const s of [...samples].sort((a, b) => a.date.localeCompare(b.date))) {
+        byClass.set(s.cls, [...(byClass.get(s.cls) ?? []), s]);
+    }
+    const out: RiskClass[] = [];
+    for (const [cls, all] of byClass) {
+        const window = all.slice(-threshold.min_steps);
+        const escaped = window.filter((s) => s.escaped).length;
+        const critical = window.filter((s) => s.critical).length;
+        if (escaped > threshold.max_escaped || critical > threshold.max_critical) out.push(cls);
+    }
+    return out.sort();
+}
+
+/**
+ * The depth a step actually runs at: lowered only inside the owner's scope,
+ * only once a committed reading has cleared `requires`, and never for a
+ * rolled-back class. An `active` table with no reading recorded stays at full
+ * depth: the owner decision allows the lowering on the reading, not on the flag.
+ */
+export function effectiveMode(
+    tableMode: 'shadow' | 'active',
+    cls: RiskClass,
+    paths: readonly string[],
+    flip: FlipBlock,
+    rolledBack: readonly RiskClass[],
+): 'shadow' | 'active' {
+    const cleared = typeof flip.reading === 'string' && flip.reading.trim() !== '';
+    const lowered =
+        tableMode === 'active' &&
+        cleared &&
+        flip.classes.includes(cls) &&
+        isStructurallySafe(paths) &&
+        !rolledBack.includes(cls);
+    return lowered ? 'active' : 'shadow';
+}

package/src/scripts/_lib/design_lock.ts

@@ -0,0 +1,117 @@
+/**
+ * The carrier for a declared Consistency Lock (road-to-a-canvas-the-code-owns
+ * step 8.2).
+ *
+ * `design-system-capture` lets a project declare, in `DESIGN.md` § Consistency
+ * Locks, a Colour Lock (one accent family), a Shape Lock (one radius set) and,
+ * when it chooses, a Spacing Lock. It said a value outside a Lock "is
+ * off-system" and gets flagged — and nothing flagged it: `lint_design_slop`
+ * knows no project's Locks and `lint_design_quality` excludes palette opinions by
+ * design. This is the narrow, Lock-scoped form of that check.
+ *
+ * **Flags, never blocks.** A finding is rebuttable — the author states why in the
+ * diff or records it in a baseline. A brownfield project records its existing
+ * drift once with `--write-baseline`; after that only NEW drift is reported.
+ * A Lock line still carrying the template's `[placeholder]` declares nothing.
+ */
+
+export interface Locks {
+    /** Hue ranges in degrees, [centre, tolerance]. Empty = no Colour Lock. */
+    hues: Array<[number, number]>;
+    radius: Set<number> | null;
+    spacing: Set<number> | null;
+}
+
+export interface LockFinding {
+    file: string;
+    line: number;
+    lock: 'colour' | 'shape' | 'spacing';
+    value: string;
+    message: string;
+}
+
+const FAMILY_HUE: Record<string, [number, number]> = {
+    red: [0, 15], orange: [28, 13], amber: [42, 10], yellow: [55, 10], lime: [80, 15], green: [125, 30],
+    emerald: [155, 15], teal: [175, 18], cyan: [190, 12], sky: [200, 12], blue: [220, 18], indigo: [240, 12],
+    violet: [260, 12], purple: [275, 12], fuchsia: [295, 15], pink: [325, 18], rose: [348, 14],
+};
+
+function hexToHsl(hex: string): { h: number; s: number; l: number } | null {
+    let h = hex.replace('#', '');
+    if (h.length === 3 || h.length === 4) h = h.slice(0, 3).split('').map((c) => c + c).join('');
+    if (h.length !== 6 && h.length !== 8) return null;
+    const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255) as [number, number, number];
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    const d = max - min;
+    if (d === 0) return { h: 0, s: 0, l };
+    const s = d / (1 - Math.abs(2 * l - 1));
+    const hue = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    return { h: (hue * 60 + 360) % 360, s, l };
+}
+
+const lockLine = (md: string, name: RegExp): string | null => {
+    const m = new RegExp(`^\\s*-\\s*${name.source}\\s*:(.*)$`, 'im').exec(md);
+    if (m === null) return null;
+    const body = (m[1] as string).trim();
+    return /^\[.*\]/.test(body) ? null : body;
+};
+
+const pxSet = (line: string | null): Set<number> | null => {
+    if (line === null) return null;
+    const nums = [...line.matchAll(/(\d+(?:\.\d+)?)(?=\s*(?:\/|px|,|$))/g)].map((m) => Number(m[1]));
+    return nums.length > 0 ? new Set([0, ...nums]) : null;
+};
+
+export function parseLocks(designMd: string): Locks {
+    const hues: Array<[number, number]> = [];
+    const colour = lockLine(designMd, /Colou?r Lock/);
+    if (colour !== null) {
+        for (const word of colour.toLowerCase().match(/[a-z]+/g) ?? []) {
+            const f = FAMILY_HUE[word];
+            if (f !== undefined) hues.push(f);
+        }
+        for (const m of colour.matchAll(/#[0-9a-f]{3,8}\b/gi)) {
+            const hsl = hexToHsl(m[0]);
+            if (hsl !== null) hues.push([Math.round(hsl.h), 15]);
+        }
+    }
+    return { hues, radius: pxSet(lockLine(designMd, /Shape Lock/)), spacing: pxSet(lockLine(designMd, /Spacing Lock/)) };
+}
+
+const hueDistance = (a: number, b: number): number => Math.min(Math.abs(a - b), 360 - Math.abs(a - b));
+
+/** Every value in one UI file that lies outside a declared Lock. */
+export function checkFile(file: string, text: string, locks: Locks): LockFinding[] {
+    const out: LockFinding[] = [];
+    text.split('\n').forEach((lineText, i) => {
+        const line = i + 1;
+        if (locks.hues.length > 0) {
+            for (const m of lineText.matchAll(/#[0-9a-fA-F]{3,8}\b/g)) {
+                const hsl = hexToHsl(m[0]);
+                if (hsl === null || hsl.s * (1 - Math.abs(2 * hsl.l - 1)) < 0.08) continue; // low chroma: a neutral is never an accent
+                if (locks.hues.some(([c, tol]) => hueDistance(hsl.h, c) <= tol)) continue;
+                out.push({ file, line, lock: 'colour', value: m[0], message: `${m[0]} (hue ${Math.round(hsl.h)}°) lies outside the declared Colour Lock` });
+            }
+        }
+        const prop = /(border(?:-[a-z]+)*-radius|radius)\s*:\s*([^;]+)|(margin|padding|gap|row-gap|column-gap)(?:-[a-z]+)?\s*:\s*([^;]+)/i.exec(lineText);
+        if (prop === null) return;
+        const isRadius = prop[1] !== undefined;
+        const set = isRadius ? locks.radius : locks.spacing;
+        if (set === null) return;
+        for (const m of (prop[2] ?? prop[4] ?? '').matchAll(/(\d+(?:\.\d+)?)px/g)) {
+            const n = Number(m[1]);
+            if (set.has(n) || (isRadius && n >= 999)) continue;
+            const lock = isRadius ? 'shape' : 'spacing';
+            out.push({ file, line, lock, value: `${m[1]}px`, message: `${m[1]}px is not in the declared ${isRadius ? 'Shape' : 'Spacing'} Lock set` });
+        }
+    });
+    return out;
+}
+
+/** Drop findings a brownfield baseline already records — only new drift counts. */
+export function newDrift(findings: LockFinding[], baseline: ReadonlyArray<{ file: string; value: string }>): LockFinding[] {
+    const known = new Set(baseline.map((b) => `${b.file}\0${b.value.toLowerCase()}`));
+    return findings.filter((f) => !known.has(`${f.file}\0${f.value.toLowerCase()}`));
+}