@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/lint_consolidation_lineage.ts

@@ -44,6 +44,15 @@
  *                       parent set does not name.
  * - `missing-parent`    a declared parent with no matching file — the lineage
  *                       names something nobody can open.
+ * - `unresolvable-parent`  a declared parent named only in prose: no slug, so
+ *                       no file could ever match it. Distinct from
+ *                       `missing-parent`, which sends the reader looking for a
+ *                       file.
+ *
+ * A sibling that declares itself DOWNSTREAM of the consolidating file
+ * (`supersedes:`, `supersedes_proposals:`, or a `relates:` entry with
+ * `relation: extends`) is a successor, not an omission, and is not reported
+ * as `omitted-sibling`.
  * - `overlapping-sets`  two artifacts in one folder declaring overlapping parent
  *                       sets while neither names the other: an artifact that
  *                       reads as the settled answer while a peer of equal
@@ -121,7 +130,7 @@ export interface Declaration {
 }
 
 export interface Finding {
-    code: 'omitted-sibling' | 'missing-parent' | 'overlapping-sets' | 'claims-without-field';
+    code: 'omitted-sibling' | 'missing-parent' | 'unresolvable-parent' | 'overlapping-sets' | 'claims-without-field';
     folder: string;
     file: string;
     detail: string;
@@ -134,16 +143,23 @@ export interface Finding {
  * with or without `.md`, with a download-collision `(1)` suffix, and followed by
  * arbitrary prose (`road-to-gated-self-evolution` v3 (Claude-Session) — P0–P7).
  * Everything after the first token is commentary.
+ *
+ * A YAML scalar may also arrive quoted. One matching pair of wrapping quotes is
+ * removed — around the whole input and around the selected token — and nothing
+ * else, so an apostrophe inside a slug survives (D6 of
+ * road-to-gates-that-read-what-was-written). Callers pass the raw value.
  */
 export function normalizeParent(raw: string): string {
     let s = raw.trim();
     s = s.replace(/^[-*]\s+/, '');
+    s = unwrapQuotes(s, true);
     const tick = /`([^`]+)`/.exec(s);
     if (tick) {
         s = tick[1] as string;
     } else {
         s = (s.split(/[\s—–,;|]/)[0] ?? '').trim();
     }
+    s = unwrapQuotes(s, false);
     s = s.replace(/^.*\//, '');
     s = s.replace(/\.md$/i, '');
     s = s.replace(/\(\d+\)$/, '');
@@ -154,6 +170,19 @@ export function normalizeParent(raw: string): string {
     return s;
 }
 
+/**
+ * Remove one matching pair of wrapping quotes. With `whole`, the pair must be
+ * the only occurrence of that quote character: `"a" — "b"` is two quoted
+ * strings, not one, and unwrapping it would glue a quote onto the first token.
+ */
+function unwrapQuotes(s: string, whole: boolean): string {
+    const q = s[0];
+    if (s.length < 2 || (q !== '"' && q !== "'") || s[s.length - 1] !== q) return s;
+    const inner = s.slice(1, -1);
+    if (whole && inner.includes(q)) return s;
+    return inner.trim();
+}
+
 function frontmatterList(fm: string, key: string): string[] | null {
     const lines = fm.split(/\r?\n/);
     const head = new RegExp(`^${key}:\\s*(.*)$`);
@@ -165,7 +194,7 @@ function frontmatterList(fm: string, key: string): string[] | null {
             return inline
                 .slice(1, inline.lastIndexOf(']') === -1 ? undefined : inline.lastIndexOf(']'))
                 .split(',')
-                .map((x) => normalizeParent(x.replace(/["']/g, '')))
+                .map((x) => normalizeParent(x))
                 .filter(Boolean);
         }
         const out: string[] = [];
@@ -185,6 +214,82 @@ function frontmatterList(fm: string, key: string): string[] | null {
     return null;
 }
 
+/**
+ * The `relates:` entries of a frontmatter block that carry a DOWNSTREAM
+ * relation, as `{slug}` stems.
+ *
+ * Only `extends` is directional by declaration in the measured corpus; a
+ * generic `relates` names a neighbour without saying which came first, and
+ * reading it as succession would suppress real omissions. AI council
+ * 2026-10-16 (anthropic + openai, convergent): an allowlist of one, widened
+ * only on evidence that another relation value states a direction.
+ */
+const DOWNSTREAM_RELATIONS: ReadonlySet<string> = new Set(['extends']);
+
+function downstreamRelates(fm: string): string[] {
+    const lines = fm.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^relates:\s*$/.test(l));
+    if (start === -1) return [];
+    const out: string[] = [];
+    let slug: string | null = null;
+    const flush = (relation: string | null): void => {
+        if (slug && relation && DOWNSTREAM_RELATIONS.has(relation)) out.push(normalizeParent(slug));
+    };
+    let relation: string | null = null;
+    for (let j = start + 1; j < lines.length; j += 1) {
+        const line = lines[j] as string;
+        if (line.trim() === '' || /^\s*#/.test(line)) continue;
+        if (!/^\s/.test(line)) break;
+        const head = /^\s+-\s+(.*)$/.exec(line);
+        const body = head ? (head[1] as string) : line.trim();
+        if (head) {
+            flush(relation);
+            slug = null;
+            relation = null;
+        }
+        const kv = /^(slug|relation):\s*(.*)$/.exec(body);
+        if (!kv) continue;
+        const value = unwrapQuotes((kv[2] as string).replace(/#.*$/, '').trim(), false);
+        if (kv[1] === 'slug') slug = value;
+        else relation = value;
+    }
+    flush(relation);
+    return out.filter(Boolean);
+}
+
+/**
+ * The stems this artifact declares itself DOWNSTREAM of: a supersession key
+ * (`supersedes:`, `supersedes_proposals:`) or a `relates:` entry with a
+ * directional relation. A sibling that names the consolidating file here was
+ * written knowing it, so it is a successor, never an undiscussed parent.
+ * Keyed on explicit declaration only — never on dates or file order.
+ */
+export function downstreamOf(text: string): string[] {
+    const fmMatch = FM_RE.exec(text);
+    if (!fmMatch) return [];
+    const fm = fmMatch[1] as string;
+    return [
+        ...(frontmatterList(fm, 'supersedes') ?? []),
+        ...(frontmatterList(fm, 'supersedes_proposals') ?? []),
+        ...downstreamRelates(fm),
+    ];
+}
+
+/**
+ * Whether a declared parent that resolves to no file is at least slug-shaped.
+ *
+ * A separator-joined name (`road-to-x`, `deep-plan-2026-09-30`) is a file
+ * somebody can be sent to look for: `missing-parent`. A single word — the
+ * first word of a prose title, `AC` — names no file at all, and reporting it as
+ * missing sends the reader hunting for one: `unresolvable-parent`.
+ *
+ * The council suggested a lowercase `road-to-*` grammar. It is widened on two
+ * measured facts: a non-roadmap parent is a supported shape (see
+ * analyseFolder's `present`), and the archived estate carries roadmap names
+ * with dots and capitals (`road-to-6.0.0-…`, `…-HUMAN-MEASUREMENT`).
+ */
+const SLUG_RE = /^[A-Za-z0-9._]+(?:[-_][A-Za-z0-9._]+)+$/;
+
 /** A prose `**Label:**` heading followed by a `- ` bullet list. */
 function proseList(body: string, label: RegExp): string[] | null {
     const lines = body.split(/\r?\n/);
@@ -276,6 +381,8 @@ interface Artifact {
     stem: string;
     file: string;
     decl: Declaration;
+    /** Stems this artifact declares itself a successor of — see downstreamOf. */
+    downstream: string[];
 }
 
 /**
@@ -320,11 +427,15 @@ export function analyseFolder(
         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 artifacts: Artifact[] = names.map((n) => {
+        const text = fs.readFileSync(path.join(dir, n), 'utf-8');
+        return {
+            stem: n.replace(/\.md$/i, ''),
+            file: n,
+            decl: parseDeclaration(text, surface),
+            downstream: downstreamOf(text),
+        };
+    });
     // 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, '')));
@@ -342,18 +453,35 @@ export function analyseFolder(
         if (a.decl.parents.length === 0) continue;
 
         for (const p of a.decl.parents) {
-            if (!present.has(p)) {
-                findings.push({
-                    code: 'missing-parent',
-                    folder: folderLabel,
-                    file: a.file,
-                    detail: `declares parent \`${p}\` but no such file is present`,
-                });
-            }
+            if (present.has(p)) continue;
+            findings.push(
+                SLUG_RE.test(p)
+                    ? {
+                          code: 'missing-parent',
+                          folder: folderLabel,
+                          file: a.file,
+                          detail: `declares parent \`${p}\` but no such file is present`,
+                      }
+                    : {
+                          code: 'unresolvable-parent',
+                          folder: folderLabel,
+                          file: a.file,
+                          detail: `declares a parent named only in prose (normalised to \`${p}\`) — no slug, so no file can match; name it by slug`,
+                      },
+            );
         }
         const omitted =
             surface === 'inbox'
-                ? artifacts.filter((b) => b.stem !== a.stem && !a.decl.parents.includes(b.stem)).map((b) => b.stem)
+                ? artifacts
+                      .filter(
+                          (b) =>
+                              b.stem !== a.stem
+                              && !a.decl.parents.includes(b.stem)
+                              // A sibling declaring itself downstream of `a` is
+                              // a successor: `a` could not have discussed it.
+                              && !b.downstream.includes(a.stem),
+                      )
+                      .map((b) => b.stem)
                 : [];
         if (omitted.length > 0) {
             findings.push({

package/src/scripts/lint_consumer_internal_refs.ts

@@ -31,18 +31,18 @@
  *
  * Scope: every `dist/agent-src/skills/<name>/SKILL.md` — the consumer projection
  * actually shipped in the npm package (mirrors the reviewer's own vantage
- * point: `npm i` + read the installed skills).
+ * point: `npm i` + read the installed skills) — plus, for the skill-script
+ * form alone, `references/*.md` beside it.
  *
- * Carve-outs:
+ * The twenty-skill `SCRIPTS_RUN_ALLOWLIST` this gate used to carry is GONE.
+ * It exempted the one form that most needed the finding: a line telling a
+ * consumer to type a wrapper the package does not ship. The skills now teach
+ * `node <skills-root>/<name>/scripts/<tool>.mjs`, which an install can start,
+ * so the exemption has nothing left to exempt.
+ *
+ * Carve-out:
  *   - Skill frontmatter `workspaces: [agent-config-maintainer]` (exclusive)
  *     — entirely exempt, per the mechanism above.
- *   - `SCRIPTS_RUN_ALLOWLIST` below — the `corpus-grounding` engine's own
- *     documented consumer-runtime CLI convention (`./scripts-run
- *     <skills-root>/<name>/scripts/<tool> …`, skill-bundled assets per
- *     `docs/contracts/skill-bundled-assets.md`) — the invoked PATH is real
- *     and reachable in every install; only the wrapper name is inherited
- *     from the maintainer dispatcher. Tracked as a separate, larger-scope
- *     naming-consistency item; out of scope for this lint's 17-skill sweep.
  *
  * Exit codes: 0 clean · 1 findings · 2 internal error.
  */
@@ -57,38 +57,6 @@ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const SKILLS_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'skills');
 
-/**
- * Skills using `corpus-grounding`'s documented `./scripts-run
- * <skills-root>/<name>/scripts/<tool>` consumer-runtime CLI convention
- * (skill-bundled assets, `docs/contracts/skill-bundled-assets.md`) — the
- * path is real and reachable once installed; only the wrapper name drifted
- * from the contract's prescribed `node_modules/.bin/tsx` form. A single,
- * uniform, cross-skill convention — renaming it is a separate, larger-scope
- * follow-up, not one of this sweep's 17 leaky skills.
- */
-const SCRIPTS_RUN_ALLOWLIST = new Set([
-    'accessibility-auditor',
-    'api-design',
-    'api-endpoint',
-    'authz-review',
-    'blade-ui',
-    'brand',
-    'brand-identity',
-    'brand-strategy',
-    'brand-to-tokens',
-    'corpus-grounding',
-    'dashboard-design',
-    'database',
-    'design-intelligence',
-    'design-tokens',
-    'flux',
-    'livewire',
-    'react-shadcn-ui',
-    'sql-writing',
-    'threat-modeling',
-    'typography-system',
-]);
-
 interface PatternDef {
     readonly re: RegExp;
     readonly label: string;
@@ -120,10 +88,73 @@ const PATTERNS: readonly PatternDef[] = [
     {
         re: /\.\/scripts-run\b/,
         label: 'invocation of the maintainer-only `./scripts-run` dispatcher (not in `package.json` `files`, never reaches a consumer install)',
-        allowlist: SCRIPTS_RUN_ALLOWLIST,
+    },
+    {
+        re: /node_modules\/\.bin\/tsx\b/,
+        label: 'invocation through `node_modules/.bin/tsx` (a devDependency binary; an install carries `node`, not a TypeScript loader)',
     },
 ];
 
+/**
+ * The skill-script form: `<runner> <skills-root>/<skill>/scripts/<tool>`.
+ *
+ * Checked apart from PATTERNS because the runner is not always on the line
+ * that carries the path — a wrapped command leaves it at the end of the line
+ * above, and a per-line regex reading only its own line reports every wrapped
+ * invocation in the tree.
+ *
+ * It is also the one form checked inside `references/`. A blanket widening
+ * would red on the reference files that name `./scripts-run src/scripts/…`,
+ * which is a different class — a maintainer script, invoked while working on
+ * this package — and this gate is not the place that decides those.
+ */
+const SKILL_SCRIPT_RE = /<skills-root>\/([A-Za-z0-9._-]+)\/scripts\/([A-Za-z0-9._-]+)/;
+const SKILL_SCRIPT_RUNNER = 'node';
+
+/** The last shell-ish token of a markdown fragment, decoration stripped. */
+function lastToken(fragment: string): string {
+    const cleaned = fragment.replace(/\\\s*$/, '').replace(/[`\s]+$/, '').trim();
+    if (cleaned === '') return '';
+    return (cleaned.split(/\s+/).pop() ?? '').replace(/^[`>*_(]+/, '').replace(/[`*_)]+$/, '');
+}
+
+/** The runner a taught line names: its own, or the one the line above ends with. */
+function runnerFor(lines: readonly string[], idx: number, col: number): string {
+    const before = (lines[idx] as string).slice(0, col);
+    const own = lastToken(before.replace(/^[\s>]*(?:[-*+]\s+|\d+\.\s+)?/, ''));
+    if (own !== '') return own;
+    if (idx === 0) return '';
+    const above = lines[idx - 1] as string;
+    if (/^\s*(?:```|~~~)/.test(above)) return '';
+    return lastToken(above);
+}
+
+/** Findings for taught skill-script lines that a node-only install cannot start. */
+export function scanSkillScriptForm(relPath: string, text: string): string[] {
+    const findings: string[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = SKILL_SCRIPT_RE.exec(lines[i] as string);
+        if (!m) continue;
+        const tool = m[2] as string;
+        const runner = runnerFor(lines, i, m.index);
+        if (runner !== SKILL_SCRIPT_RUNNER) {
+            findings.push(
+                `${relPath}:${i + 1}: skill-script line whose runner is ` +
+                    `${runner === '' ? 'absent' : `\`${runner}\``}, not \`node\` — ` +
+                    'an install carries the runtime and the bundle, nothing else',
+            );
+        }
+        if (!tool.endsWith('.mjs')) {
+            findings.push(
+                `${relPath}:${i + 1}: skill-script line naming \`${tool}\` — ` +
+                    'the shipped entry point is the `.mjs` beside the source',
+            );
+        }
+    }
+    return findings;
+}
+
 /** `workspaces:` frontmatter list of a skill file ([] when untagged). */
 function skillWorkspaces(skillPath: string): string[] {
     const src = fs.readFileSync(skillPath, 'utf-8');
@@ -191,6 +222,23 @@ export function main(): number {
         }
         const relPath = path.relative(REPO_ROOT, abs);
         findings.push(...scanText(name, relPath, text));
+        findings.push(...scanSkillScriptForm(relPath, text));
+
+        // `references/` is read for the skill-script form only — see the note
+        // above `SKILL_SCRIPT_RE` for why the other patterns stop at SKILL.md.
+        const refsDir = path.join(SKILLS_DIR, name, 'references');
+        if (!fs.existsSync(refsDir) || !fs.statSync(refsDir).isDirectory()) continue;
+        for (const ref of fs.readdirSync(refsDir).sort()) {
+            if (!ref.endsWith('.md')) continue;
+            const refAbs = path.join(refsDir, ref);
+            let refText: string;
+            try {
+                refText = fs.readFileSync(refAbs, 'utf-8');
+            } catch {
+                continue;
+            }
+            findings.push(...scanSkillScriptForm(path.relative(REPO_ROOT, refAbs), refText));
+        }
     }
 
     // Counted BEFORE the maintainer-exclusive skip, so an all-maintainer

package/src/scripts/lint_context_spine_usage.ts

@@ -18,6 +18,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { validateBrandVoiceSlotFile } from './_lib/brand_voice_slot.js';
 import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -43,6 +44,7 @@ const VALID_SLOTS = [
     'channel-stage',
     'funnel-stage',
     'customer-segment',
+    'brand-voice',
     'fiscal-period',
     'org-stage',
     'regulatory-regime',
@@ -116,6 +118,13 @@ function lint_skill(p: string): string[] {
     return problems;
 }
 
+/** The brand-voice slot is the one slot validated as data (adr-gtm-context-spine-brand-voice). */
+const BRAND_VOICE_SLOT = path.join('agents', 'context-spine', 'brand-voice.md');
+
+function lint_brand_voice_slot(p: string): string[] {
+    return validateBrandVoiceSlotFile(p).map((i) => `brand_voice_slot: ${i.field}: ${i.message}`);
+}
+
 /** Recursively list `SKILL.md` files under `dir`, sorted (mirrors sorted(rglob)). */
 function _rglobSkillSorted(dir: string): string[] {
     const out: string[] = [];
@@ -187,6 +196,17 @@ function main(): number {
             }
         }
     }
+    const slotPath = path.join(REPO_ROOT, BRAND_VOICE_SLOT);
+    if (fs.existsSync(slotPath)) {
+        const problems = lint_brand_voice_slot(slotPath);
+        if (problems.length) {
+            failed += 1;
+            process.stderr.write(`❌  ${_relPosix(slotPath, REPO_ROOT)}\n`);
+            for (const pb of problems) {
+                process.stderr.write(`    - ${pb}\n`);
+            }
+        }
+    }
     if (failed) {
         process.stderr.write(
             `\n❌  ${failed} skill(s) failed context-spine usage lint ` +
@@ -239,5 +259,6 @@ export {
     _read_spine,
     _slot_cited,
     lint_skill,
+    lint_brand_voice_slot,
     main,
 };

package/src/scripts/lint_design_antipattern_parity.ts

@@ -14,8 +14,9 @@
  *   A. every non-`Q*` catalog entry appears exactly once in § Detector status
  *   B. every § Detector status row names a catalog entry that exists
  *   C. the set of `backed` rows equals the registry's `catalogId` set
- *   D. every status is one of the five allowed values
+ *   D. every status is one of the six allowed values
  *   E. every non-`backed` row carries a reason
+ *   H. every `witness` row names a rule the rendered witness emits
  *
  * `Q*` entries are out of scope by construction: they are objective floors owned
  * by `lint_design_quality`, not aesthetic tells, and the status table says so.
@@ -38,8 +39,21 @@ const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 const CATALOG = path.join(REPO, 'docs', 'guidelines', 'design-antipatterns.md');
 const REGISTRY = path.join(REPO, 'src', 'scripts', 'design_slop_rules.ts');
 
-/** The five statuses § Detector status may use. */
-export const STATUSES = ['backed', 'floor', 'judgment-only', 'deferred', 'candidate'] as const;
+/** The six statuses § Detector status may use. */
+export const STATUSES = ['backed', 'floor', 'judgment-only', 'deferred', 'candidate', 'witness'] as const;
+
+/**
+ * Where a `witness` row's rule must exist: the asset witness's sources
+ * (road-to-type-with-a-witness 2.1). A `witness` entry is read from the
+ * rendered asset rather than from text, so its detector lives here and not in
+ * the slop registry.
+ */
+export const WITNESS_SOURCES = [
+    'src/cli/commands/uiRenderAsset.ts',
+    'src/cli/commands/uiRenderAssetFonts.ts',
+] as const;
+
+const WITNESS_RULE = /`((?:geometry|structure|accessibility|motion)\/[a-z0-9-]+)`/;
 export type Status = (typeof STATUSES)[number];
 
 export interface ParityFinding {
@@ -119,8 +133,12 @@ export function registryCatalogIds(registryTs: string): string[] {
     return [...registryTs.matchAll(CATALOG_ID)].map((m) => m[1] as string);
 }
 
-/** Pure invariant check over both documents. */
-export function parityFindings(catalogMd: string, registryTs: string): ParityFinding[] {
+/**
+ * Pure invariant check over both documents, plus the witness source text a
+ * `witness` row is checked against. Omitting it fails every `witness` row
+ * rather than passing it unread.
+ */
+export function parityFindings(catalogMd: string, registryTs: string, witnessTs = ''): ParityFinding[] {
     const out: ParityFinding[] = [];
 
     if (STATUS_SECTION.exec(catalogMd) === null) {
@@ -166,6 +184,19 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
         if (row.status !== 'backed' && row.note === '') {
             out.push({ kind: 'missing-reason', id, msg: `${id}: status '${row.status}' carries no reason` });
         }
+        // H — a witness row names its rendered rule, and the witness emits it.
+        if (row.status === 'witness') {
+            const rule = WITNESS_RULE.exec(row.note)?.[1];
+            if (rule === undefined || !witnessTs.includes(`'${rule}'`)) {
+                out.push({
+                    kind: 'witness-without-rule',
+                    id,
+                    msg: rule
+                        ? `${id}: marked witness on \`${rule}\`, which the witness source does not emit`
+                        : `${id}: marked witness but its note names no witness rule (\`geometry/...\`)`,
+                });
+            }
+        }
     }
 
     // F — the census columns: present, non-empty, and from the closed vocabularies.
@@ -243,7 +274,7 @@ export function main(): number {
     try {
         assertWatchlistResolves({
             gate: 'lint_design_antipattern_parity',
-            candidates: [path.relative(REPO, CATALOG), path.relative(REPO, REGISTRY)],
+            candidates: [path.relative(REPO, CATALOG), path.relative(REPO, REGISTRY), ...WITNESS_SOURCES],
             repoRoot: REPO,
         });
     } catch (exc) {
@@ -256,7 +287,8 @@ export function main(): number {
 
     const catalogMd = fs.readFileSync(CATALOG, 'utf-8');
     const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
-    const findings = parityFindings(catalogMd, registryTs);
+    const witnessTs = WITNESS_SOURCES.map((rel) => fs.readFileSync(path.join(REPO, rel), 'utf-8')).join('\n');
+    const findings = parityFindings(catalogMd, registryTs, witnessTs);
 
     const rows = statusRows(catalogMd);
     const entries = catalogEntries(catalogMd).length;

package/src/scripts/lint_evidence_artifacts.ts

@@ -49,6 +49,8 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
+import { parseClearance } from './_lib/merge_clearance_record.js';
+import { readRequiredProviders } from './_lib/ratification_artifact.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 import { parseExecutionMode } from './_lib/repeated_run.js';
 import { reportScanned } from './_lib/scan_scope.js';
@@ -65,6 +67,8 @@ export const EVIDENCE_TYPES = [
     'analysis',
     'feel',
     'ratification',
+    'merge-clearance',
+    'bypass-record',
 ] as const;
 
 /**
@@ -202,6 +206,22 @@ export interface Finding {
     readonly reason: string;
 }
 
+const RATIFICATION_POLICY = path.join('src', 'config', 'ratification-policy.json');
+
+function clearanceProblems(root: string, contents: string): string[] {
+    let required: number | null = null;
+    try {
+        required = readRequiredProviders(fs.readFileSync(path.join(root, RATIFICATION_POLICY), 'utf8'));
+    } catch {
+        required = null;
+    }
+    if (required === null) {
+        return [`${RATIFICATION_POLICY} is missing or unreadable, so the outcome cannot be derived`];
+    }
+    const parsed = parseClearance(contents, required);
+    return Array.isArray(parsed) ? parsed : [];
+}
+
 export function checkFiles(root: string, files: readonly string[], ledger?: GateLedger): Finding[] {
     const findings: Finding[] = [];
     ledger?.plan([...files]);
@@ -248,6 +268,17 @@ export function checkFiles(root: string, files: readonly string[], ledger?: Gate
                 continue;
             }
         }
+        // A clearance decides whether a `needs-council` PR merges, so one that
+        // does not parse — or whose outcome its own seats do not support under
+        // the committed quorum policy — is a finding rather than a typed record.
+        if (res.type === 'merge-clearance') {
+            const problems = clearanceProblems(root, contents);
+            if (problems.length > 0) {
+                ledger?.fail(rel, 'merge clearance does not parse');
+                findings.push({ file: rel, reason: `merge-clearance does not parse: ${problems.join('; ')}` });
+                continue;
+            }
+        }
         if (res.type === null) {
             ledger?.fail(rel, 'no evidence type declared');
             findings.push({

package/src/scripts/lint_example_fences.ts

@@ -71,6 +71,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assignmentPattern } from './_lib/egress_rules.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { reportScanned } from './_lib/scan_scope.js';
@@ -159,8 +160,16 @@ export const PATTERNS: readonly FencePattern[] = [
         source: 'tool-safety',
         langs: 'any',
         label: 'Credential assigned a literal value in an example',
-        pattern:
-            /\b(api[_-]?key|apikey|password|passwd|secret|access[_-]?token|client[_-]?secret)\b\s*[:=]\s*["'][^"']{8,}["']/i,
+        pattern: assignmentPattern(
+            {
+                keywords: ['apiKey', 'apikey', 'password', 'passwd', 'secret', 'accessToken', 'clientSecret'],
+                before: '\\b',
+                after: '\\b',
+                capture: true,
+                value: `["'][^"']{8,}["']`,
+            },
+            'i',
+        ),
         // Placeholders are the correct way to show the shape and must not fire.
         // `secret-vcs-guard` owns real credentials; this pattern owns the
         // *teaching* of an inline literal, so anything self-evidently fake is out.