@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/check_platform_anchor.ts

@@ -13,6 +13,13 @@
  * An ordinary pull request never reaches the network through this path, which is
  * what keeps a fail-closed network dependency proportionate.
  *
+ * One read runs on every invocation, gated diff or not, and needs no network:
+ * the bypass records in `BYPASS_RECORD_DIR`. A bypass still
+ * open past its `restore_by`, or restored with no council review recorded
+ * seven days on, fails the run — the contract's § Emergency use names the
+ * record, and this is the only reader that notices a route left unclosed. It
+ * stays what the rest of this gate is: local and voluntarily invoked.
+ *
  * Failing closed is deliberate and was the explicit condition of the decision
  * that commissioned this gate: `unverifiable` is a failure, not a pass, because
  * a control that succeeds when it cannot measure is advisory. The two negative
@@ -38,8 +45,15 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { asOf } from './_lib/as_of.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import {
+    BYPASS_RECORD_DIR,
+    BYPASS_RECORD_LIMIT,
+    BYPASS_RECORD_MAX_BYTES,
     checkAnchorIdentity,
     evaluateAnchor,
+    evaluateBypassRecords,
+    printable,
+    type BypassFinding,
+    type BypassRecordInput,
     readAnchorPolicy,
     readWaivers,
     type AnchorReading,
@@ -154,6 +168,218 @@ export function touchesPolicy(files: readonly string[]): boolean {
     return files.map((f) => f.replace(/\\/g, '/').trim()).includes(POLICY_PATH);
 }
 
+/**
+ * The bypass records in the checkout. Read on every run, gated diff or not: an
+ * open bypass is a fact about the repository, not about the change under test.
+ * A missing directory is no records; one that exists and cannot be listed is
+ * returned as an unreadable record, which fails the gate.
+ */
+export function readBypassRecords(root: string): BypassRecordInput[] {
+    const names: string[] = [];
+    let dir: fs.Dir | null = null;
+    try {
+        if (!fs.lstatSync(path.join(root, BYPASS_RECORD_DIR)).isDirectory()) {
+            return [{ path: BYPASS_RECORD_DIR, text: null }];
+        }
+        // Every entry counts toward the ceiling, and the listing stops one past
+        // it, so a directory stuffed with other files cannot cost an unbounded read.
+        dir = fs.opendirSync(path.join(root, BYPASS_RECORD_DIR));
+        for (let entry = dir.readSync(); entry !== null; entry = dir.readSync()) {
+            names.push(entry.name);
+            if (names.length > BYPASS_RECORD_LIMIT) {
+                return [{ path: `${BYPASS_RECORD_DIR} (more than ${String(BYPASS_RECORD_LIMIT)} entries)`, text: null }];
+            }
+        }
+    } catch (err) {
+        // No directory means no bypass was ever recorded. Any other failure is
+        // a directory that exists and cannot be read, which shows nothing closed.
+        return (err as NodeJS.ErrnoException).code === 'ENOENT' ? [] : [{ path: BYPASS_RECORD_DIR, text: null }];
+    } finally {
+        try {
+            dir?.closeSync();
+        } catch {
+            // Closing a listing that already ended is not a finding.
+        }
+    }
+    return names
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+        .map((n) => ({ path: `${BYPASS_RECORD_DIR}/${n}`, text: readRecordOnce(path.join(root, BYPASS_RECORD_DIR, n)) }));
+}
+
+/**
+ * One record, opened once without following a symbolic link, checked and read
+ * through that same descriptor with a byte ceiling — so the object checked is
+ * the object read, and a replacement between the two cannot slip in.
+ */
+export function readRecordOnce(file: string, platformNoFollow: boolean = fs.constants.O_NOFOLLOW !== undefined): string | null {
+    // Without O_NOFOLLOW the open would follow a link, so no record is trusted.
+    // The flag itself is never a parameter: a caller can only say it is missing.
+    const noFollow = fs.constants.O_NOFOLLOW;
+    if (!platformNoFollow || noFollow === undefined) {
+        return null;
+    }
+    let fd: number | null = null;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > BYPASS_RECORD_MAX_BYTES) {
+            return null;
+        }
+        const buf = Buffer.alloc(BYPASS_RECORD_MAX_BYTES + 1);
+        let total = 0;
+        for (;;) {
+            const read = fs.readSync(fd, buf, total, buf.length - total, null);
+            if (read === 0) break;
+            total += read;
+            if (total > BYPASS_RECORD_MAX_BYTES) return null;
+        }
+        return buf.subarray(0, total).toString('utf8');
+    } catch {
+        return null;
+    } finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            } catch {
+                // The result was already decided; a failed close must not turn it into a crash.
+            }
+        }
+    }
+}
+
+/**
+ * Bypass records the base revision carries and the checkout does not. A record
+ * is the route's only trace, so removing one — or the whole directory — is a
+ * finding of its own. Read from Git against the base, never from a caller's
+ * file list, which can simply leave the deletion out. A base listing that
+ * cannot be read fails closed; a root that is no Git work tree has no base.
+ */
+export function removedBypassRecords(root: string, baseRef: string): BypassFinding[] {
+    const inside = spawnSync('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+    if (inside.status !== 0 || (inside.stdout ?? '').trim() !== 'true') {
+        return [];
+    }
+    const listed = spawnSync('git', ['-C', root, 'ls-tree', '-r', '-z', '--name-only', baseRef, '--', `${BYPASS_RECORD_DIR}/`], {
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    if (listed.status !== 0 || typeof listed.stdout !== 'string') {
+        return [
+            {
+                code: 'bypass-record-removed',
+                path: BYPASS_RECORD_DIR,
+                message: `the bypass records at the base \`${printable(baseRef)}\` could not be listed, so a deletion cannot be ruled out`,
+            },
+        ];
+    }
+    return listed.stdout
+        .split('\0')
+        .filter((f) => f.endsWith('.md'))
+        .filter((f) => {
+            try {
+                fs.lstatSync(path.join(root, f));
+                return false;
+            } catch {
+                return true;
+            }
+        })
+        .map((f) => ({ code: 'bypass-record-removed' as const, path: printable(f), message: `${printable(f)} is at the base \`${printable(baseRef)}\` and gone here` }));
+}
+
+/** The committed review cites the record's subject digest, read from `HEAD`. */
+export function reviewReader(
+    root: string,
+    index: ReadonlySet<string>,
+    budget: { perReview: number; total: number; reads: number } = {
+        perReview: REVIEW_MAX_BYTES,
+        total: REVIEW_TOTAL_BYTES,
+        reads: REVIEW_READ_LIMIT,
+    },
+): (rel: string, subject: string, restoredAtMs: number) => boolean {
+    const cache = new Map<string, { text: string; addedAtMs: number } | null>();
+    let bytes = 0;
+    const read = (rel: string): { text: string; addedAtMs: number } | null => {
+        // The allowance is computed before the read and caps it, so the total
+        // can reach the budget and never pass it; bytes are counted as bytes.
+        const allowance = Math.min(budget.perReview, budget.total - bytes);
+        if (cache.size >= budget.reads || allowance <= 0) {
+            return null;
+        }
+        const shown = spawnSync('git', ['-C', root, 'show', `HEAD:${rel}`], { maxBuffer: allowance });
+        // The commit that first added the file: a review written before the
+        // restore was committed before it, whatever its text says.
+        const added = spawnSync('git', ['-C', root, 'log', '--diff-filter=A', '--format=%ct', '--', rel], { encoding: 'utf8' });
+        const times = (added.stdout ?? '').trim().split('\n').filter((l) => /^\d+$/u.test(l));
+        const first = times.length > 0 ? Number(times[times.length - 1]) * 1000 : NaN;
+        if (shown.status !== 0 || !Buffer.isBuffer(shown.stdout) || shown.stdout.length > allowance || added.status !== 0 || Number.isNaN(first)) {
+            return null;
+        }
+        bytes += shown.stdout.length;
+        return { text: shown.stdout.toString('utf8'), addedAtMs: first };
+    };
+    return (rel, subject, restoredAtMs) => {
+        // A council review lives with the council's records — never in the bypass
+        // record directory, so a record cannot name itself or another record.
+        if (!rel.startsWith(COUNCIL_REVIEW_DIR) || rel.startsWith(`${BYPASS_RECORD_DIR}/`) || !reviewCommitted(root, rel, index)) {
+            return false;
+        }
+        if (!cache.has(rel)) {
+            cache.set(rel, read(rel));
+        }
+        const review = cache.get(rel);
+        return review !== null && review !== undefined && review.text.includes(subject) && review.addedAtMs >= restoredAtMs;
+    };
+}
+
+/** Where a council review a bypass record may cite lives. */
+export const COUNCIL_REVIEW_DIR = 'agents/evidence/council/';
+
+/**
+ * The run's review budget: one review at most 1 MiB, at most 20 distinct
+ * reviews and 4 MiB in total. Past it a review is not read, so the record that
+ * names it fails closed rather than costing more.
+ */
+const REVIEW_MAX_BYTES = 1024 * 1024;
+const REVIEW_READ_LIMIT = 20;
+const REVIEW_TOTAL_BYTES = 4 * 1024 * 1024;
+
+/**
+ * A `council_review` path names a regular file committed at `HEAD` inside the
+ * evidence tree — read from the commit's tree, never the working tree, so
+ * a directory, an untracked file or a symbolic link does not count.
+ */
+export function reviewCommitted(root: string, rel: string, index: ReadonlySet<string> = committedEvidence(root)): boolean {
+    const norm = path.posix.normalize(rel);
+    if (norm !== rel || !norm.startsWith('agents/evidence/') || norm.endsWith('/') || norm.split('/').includes('..')) {
+        return false;
+    }
+    return index.has(norm);
+}
+
+/**
+ * Every regular file committed at `HEAD` in the evidence tree, read once
+ * per run from one tree snapshot. A tree that cannot be read is an empty set,
+ * so every non-pending review then fails closed.
+ */
+export function committedEvidence(root: string): Set<string> {
+    const r = spawnSync('git', ['-C', root, 'ls-tree', '-r', '-z', 'HEAD', '--', 'agents/evidence/'], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const out = new Set<string>();
+    if (r.status !== 0 || typeof r.stdout !== 'string') {
+        return out;
+    }
+    for (const entry of r.stdout.split('\0')) {
+        const m = /^(100644|100755) blob [0-9a-f]+\t(.+)$/su.exec(entry);
+        if (m !== null) {
+            out.add(m[2] as string);
+        }
+    }
+    return out;
+}
+
 export interface AnchorGateResult {
     exitCode: 0 | 1;
     lines: string[];
@@ -336,6 +562,12 @@ export function main(argv: readonly string[] = process.argv.slice(2), source = l
             files.push(a);
         }
     }
+    // The ref reaches `git diff` and `git ls-tree` as a positional argument, so
+    // one starting with `-` would be read as an option.
+    if (baseRef !== null && baseRef.startsWith('-')) {
+        process.stderr.write(`check_platform_anchor: --base-ref ${printable(baseRef)} is not a ref\n`);
+        return 1;
+    }
 
     let changed: string[];
     if (filesFlagSeen) {
@@ -366,6 +598,17 @@ export function main(argv: readonly string[] = process.argv.slice(2), source = l
     }
 
     const result = evaluateGate(changed, policyText, source, repo);
+    const open = [
+        ...evaluateBypassRecords(readBypassRecords(root), asOf(), reviewReader(root, committedEvidence(root))),
+        ...removedBypassRecords(root, resolveBaseRef(baseRef, root)),
+    ];
+    if (open.length > 0) {
+        result.lines.push('', `❌  ${String(open.length)} bypass record(s) without a closing:`);
+        for (const f of open) {
+            result.lines.push(`  · [${f.code}] ${f.message}`);
+        }
+        result.exitCode = 1;
+    }
 
     reportScanned({
         gate: 'check_platform_anchor',

package/src/scripts/check_proposal.ts

@@ -23,6 +23,10 @@
  *   5. Required sections all present (1..10 per template).
  *   6. Success signal — Section 7 has a concrete metric, target, and
  *      evaluation date.
+ *   7. A `scope: package` proposal at `stage: gated` declares `changed_files:`
+ *      and names a passing `ratification_record:` and an `owner_authorization:`,
+ *      both bound to the digest of those files (ADR-281 as amended) — see
+ *      `_checkGatedRecord` for what this can and cannot prove.
  *
  * Exit codes: 0 = pass, 1 = gate failure, 2 = PyYAML missing, 3 = internal error.
  *
@@ -31,6 +35,7 @@
  *     check_proposal --format json path/to.md
  */
 
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as nodePath from 'node:path';
 import process from 'node:process';
@@ -38,8 +43,26 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { asOf } from './_lib/as_of.js';
+import {
+    isRatified,
+    RATIFICATION_DIR,
+    readRatification,
+    readRequiredProviders,
+} from './_lib/ratification_artifact.js';
+import {
+    assertContained,
+    DEFAULT_REVISION,
+    fileAtRevision,
+    GatedSubjectRefusal,
+    resolveRevision,
+    subjectOf,
+} from './_lib/ratification_subject.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
+/** This script's own tree: the quorum policy is read from here, never from the proposal's. */
+const REPO = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const POLICY_PATH = 'src/config/ratification-policy.json';
+
 type Severity = 'error' | 'warning';
 
 const REQUIRED_FRONTMATTER: ReadonlySet<string> = new Set([
@@ -392,7 +415,165 @@ function _resolvePath(p: string): string {
     return nodePath.resolve(p);
 }
 
-function _runChecks(text: string, p: string | null = null): Finding[] {
+/**
+ * The digest a package proposal's review and approval must both carry: one
+ * digest over EVERY file the proposal declares as its change, read from Git
+ * objects at `revision`.
+ *
+ * Not the gate's `subject`, on purpose. The gate digests only the GATED subset
+ * of a diff, and a learning usually changes a skill or rule body the gate does
+ * not watch — over such a change the gate's digest covers nothing and is the
+ * same for every proposal, so a record bound to it would be bound to no
+ * content. ADR-281 as amended requires a digest-bound review for every
+ * learning-originated package change, so the binding has to cover what the
+ * proposal changes. It reuses the subject module's ONE hashing loop and
+ * serialisation, by handing the declared files in as the closure it treats as
+ * covered, rather than growing a second loop that could drift from the first.
+ */
+export function proposalSubjectOf(
+    root: string,
+    files: readonly string[],
+    revision: string = DEFAULT_REVISION,
+): string {
+    return subjectOf(root, files, files, revision).digest;
+}
+
+/** The Git work tree a proposal file sits in, or `null` outside one. */
+function _repoRootOf(proposalPath: string): string | null {
+    const env = { ...process.env };
+    // A GIT_DIR inherited from a hook would answer for the hook's repository.
+    for (const k of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR']) delete env[k];
+    const dir = nodePath.dirname(nodePath.resolve(proposalPath));
+    const res = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env });
+    return res.status === 0 ? res.stdout.trim() : null;
+}
+
+/**
+ * A package-scoped proposal reaches `stage: gated` only on a council record
+ * bound to its own change AND an owner authorization bound to the same digest.
+ *
+ * The ORDER is ADR-281's amendment of 2026-10-07: the council record is the
+ * REVIEW, the owner's authorization is the APPROVAL, and a favourable verdict is
+ * advisory until the second exists. A record alone is refused, naming what is
+ * missing.
+ *
+ * WHAT THIS CANNOT PROVE, said before what it can. The authorization is a file
+ * the proposal names and a digest that file carries; nothing here establishes
+ * that the owner wrote it. ADR-281 § 5 makes the owner's route his own recorded
+ * act on the forge, which leaves no artifact a script can authenticate. What
+ * IS established is narrower: the review and the authorization name the SAME
+ * content as the proposal's declared change, read at one commit, so neither can
+ * be carried over from another change, and the review is a record the
+ * ratification reader accepts against the committed provider policy.
+ *
+ * A `scope: project` proposal, and any stage before `gated`, is checked exactly
+ * as before.
+ */
+function _checkGatedRecord(fm: Frontmatter, findings: Finding[], repoRoot: string | null): void {
+    if (fm['stage'] !== 'gated' || fm['scope'] !== 'package') {
+        return;
+    }
+    const refuse = (message: string): void => {
+        findings.push(new Finding('error', 'gated', message));
+    };
+    if (repoRoot === null) {
+        refuse('stage=gated with scope=package is checked against Git objects, and this proposal is not inside a Git work tree');
+        return;
+    }
+
+    const changed = fm['changed_files'];
+    const files = Array.isArray(changed)
+        ? changed.filter((f): f is string => typeof f === 'string').map((f) => f.trim()).filter((f) => f !== '')
+        : [];
+    if (files.length === 0 || !Array.isArray(changed) || files.length !== changed.length) {
+        refuse(
+            'stage=gated with scope=package needs `changed_files:` — a non-empty list of the paths ' +
+                'this proposal declares as its change, which its review and approval are bound to',
+        );
+        return;
+    }
+
+    // One commit for the whole check: the digest and both named files are read
+    // from the same resolved revision, never from a name resolved twice.
+    let commit: string;
+    let expected: string;
+    try {
+        commit = resolveRevision(repoRoot, DEFAULT_REVISION);
+        expected = proposalSubjectOf(repoRoot, files, commit);
+    } catch (err) {
+        if (!(err instanceof GatedSubjectRefusal)) {
+            throw err;
+        }
+        refuse(`the declared change cannot be digested: ${err.message}`);
+        return;
+    }
+
+    const requiredProviders = readRequiredProviders(_readOrNull(joinPath(REPO, POLICY_PATH)));
+    for (const [key, what] of [
+        ['ratification_record', 'the council’s review'],
+        ['owner_authorization', 'the owner’s approval'],
+    ] as const) {
+        const named = fm[key];
+        if (typeof named !== 'string' || named.trim() === '') {
+            refuse(
+                `stage=gated with scope=package needs \`${key}:\` — ${what}, bound to this ` +
+                    'proposal’s own change (ADR-281 as amended 2026-10-07)',
+            );
+            continue;
+        }
+        const rel = named.trim();
+        let bytes: Buffer | null;
+        try {
+            assertContained(rel);
+            bytes = fileAtRevision(repoRoot, commit, rel);
+        } catch (err) {
+            if (!(err instanceof GatedSubjectRefusal)) {
+                throw err;
+            }
+            refuse(`${key} names \`${rel}\`: ${err.message}`);
+            continue;
+        }
+        if (bytes === null) {
+            refuse(`${key} names \`${rel}\`, which is not a committed regular file at HEAD`);
+            continue;
+        }
+        const text = bytes.toString('utf8');
+        if (key === 'ratification_record') {
+            if (!rel.startsWith(`${RATIFICATION_DIR}/`) || !rel.endsWith('.md')) {
+                refuse(`${key} \`${rel}\` is not a record under \`${RATIFICATION_DIR}/\``);
+                continue;
+            }
+            const reading = readRatification(text, requiredProviders, expected);
+            if (!isRatified(reading)) {
+                const why = reading.problems.map((pr) => pr.message);
+                if (reading.artifact !== null && !why.length) {
+                    why.push(`verdict is \`${reading.artifact.verdict}\``);
+                }
+                refuse(`${key} \`${rel}\` does not pass for this change: ${why.join('; ')}`);
+            }
+            continue;
+        }
+        const found = /^subject:\s*([0-9a-f]{64})\s*$/m.exec(text);
+        if (found === null) {
+            refuse(`${key} \`${rel}\` carries no \`subject:\` digest, so it is bound to no change`);
+        } else if (found[1] !== expected) {
+            refuse(
+                `${key} \`${rel}\` is bound to \`${String(found[1]).slice(0, 12)}…\`, not to this ` +
+                    `proposal’s change (\`${expected.slice(0, 12)}…\`)`,
+            );
+        }
+    }
+}
+
+function _readOrNull(p: string): string | null {
+    try {
+        return fs.readFileSync(p, 'utf8');
+    } catch {
+        return null;
+    }
+}
+
+export function _runChecks(text: string, p: string | null = null, repoRoot?: string | null): Finding[] {
     const findings: Finding[] = [];
     const fm = _loadFrontmatter(text);
     _checkFrontmatter(fm, findings);
@@ -402,6 +583,7 @@ function _runChecks(text: string, p: string | null = null): Finding[] {
     _checkMarkers(body, findings);
     _checkSuccessSignal(body, findings);
     _checkOriginatingProject(body, fm, findings);
+    _checkGatedRecord(fm, findings, repoRoot !== undefined ? repoRoot : p === null ? null : _repoRootOf(p));
     if (p !== null) {
         _proposalRateWarning(p, findings);
     }

package/src/scripts/check_reach_channels.ts

@@ -53,6 +53,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { AUTHORIZATION_HEADER, CLASS_SPELLED_PREFIXES } from './_lib/egress_rules.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { SchemaError, validate, type YamlValue } from './validate_frontmatter.js';
 
@@ -145,7 +146,7 @@ const REDACTED = '<redacted>';
 export const REDACTIONS: readonly (readonly [RegExp, string])[] = [
     // `Authorization: Bearer …` — the header name stays, the value does not.
     // Runs to end of line: everything after the colon is the credential.
-    [/(\bauthorization\s*:\s*)(\S.*)$/gi, `$1${REDACTED}`],
+    [new RegExp(`(\\b${AUTHORIZATION_HEADER}\\s*:\\s*)(\\S.*)$`, 'gi'), `$1${REDACTED}`],
     // `KEY=VALUE`. Two narrowings carry their weight. The lookbehind requires
     // the key to START a token — so `yt-dlp==2026.7.4` is never chopped at its
     // `dlp=` tail and `--target=/opt` is left alone — while still admitting a
@@ -153,8 +154,9 @@ export const REDACTIONS: readonly (readonly [RegExp, string])[] = [
     // actually appears in a command. `(?!=)` excludes the `==` pin operator.
     [/(?<![A-Za-z0-9_./-])([A-Za-z_][A-Za-z0-9_]{2,})=(?!=)\S+/g, `$1=${REDACTED}`],
     // Provider key prefixes — the shapes that are a secret by construction.
-    [/\b(sk|pk|rk)-[A-Za-z0-9_-]{8,}/gi, `$1-${REDACTED}`],
-    [/\b(gh[pousr]|github_pat|xox[baprs])[-_][A-Za-z0-9_-]{8,}/gi, `$1_${REDACTED}`],
+    // Spelled as classes in the rule table; the prefix stem stays, the value does not.
+    [new RegExp(`\\b${CLASS_SPELLED_PREFIXES.dashKeys.family}[A-Za-z0-9_-]{8,}`, 'gi'), `$1-${REDACTED}`],
+    [new RegExp(`\\b${CLASS_SPELLED_PREFIXES.tokens.family}[A-Za-z0-9_-]{8,}`, 'gi'), `$1_${REDACTED}`],
     // A hex digest ≥ 32: an API key or a signature, never part of an install verb.
     [/(?<![0-9a-fA-F])[0-9a-fA-F]{32,}(?![0-9a-fA-F])/g, REDACTED],
     // A ≥ 24-char run carrying lower + upper + digit — the entropy shape of an

package/src/scripts/check_references.ts

@@ -9,8 +9,11 @@
  * same scan scope and order, same example/allowlist/skip logic. No
  * behaviour changes — latent bugs are replicated.
  *
- * Scans .md files in dist/agent-src/ and agents/ for internal references
- * (file paths, skill names, rule names) and reports broken ones.
+ * Scans .md files in dist/agent-src/, agents/ and docs/guidelines/ for
+ * internal references (file paths, skill names, rule names) and reports
+ * broken ones. The third root is not decoration: this line named two while
+ * `SCAN_DIRS` below has held three, so a reader checking whether their
+ * guideline's links are covered read the wrong answer off the header.
  *
  * Exit codes: 0 = clean, 1 = broken refs found, 3 = internal error
  *

package/src/scripts/check_release_manifest_content.ts

@@ -26,6 +26,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { CONSUMER_IMPACT_VALUES } from './_lib/consumer_impact.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -78,6 +79,37 @@ function _diffPaths(a: unknown, b: unknown, at: Segment[] = []): Segment[][] {
     return JSON.stringify(a) === JSON.stringify(b) ? [] : [at];
 }
 
+function _isImpactEntry(v: unknown): boolean {
+    if (!_isObject(v)) return false;
+    const keys = Object.keys(v);
+    return (
+        (CONSUMER_IMPACT_VALUES as readonly unknown[]).includes(v['impact']) &&
+        keys.every((k) => k === 'impact' || (k === 'security' && v[k] === true))
+    );
+}
+
+/**
+ * `head` without the one `agentConfig.impact` entry the release itself writes:
+ * keyed to the version being cut, absent at the base, in the trailer
+ * vocabulary. Containers the removal empties go too when the base lacked them,
+ * so any other difference still surfaces at its own path.
+ */
+function _withoutReleaseImpactEntry(base: unknown, head: unknown): unknown {
+    if (!_isObject(base) || !_isObject(head) || !_isObject(head['agentConfig'])) return head;
+    const version = head['version'];
+    const impact = head['agentConfig']['impact'];
+    const baseConfig = _isObject(base['agentConfig']) ? base['agentConfig'] : undefined;
+    const baseImpact = baseConfig && _isObject(baseConfig['impact']) ? baseConfig['impact'] : undefined;
+    if (typeof version !== 'string' || !_isObject(impact) || !_isImpactEntry(impact[version])) return head;
+    if (baseImpact && version in baseImpact) return head;
+    const { [version]: _written, ...restImpact } = impact;
+    const config: Record<string, unknown> = { ...head['agentConfig'], impact: restImpact };
+    if (Object.keys(restImpact).length === 0 && !baseImpact) delete config['impact'];
+    const out: Record<string, unknown> = { ...head, agentConfig: config };
+    if (Object.keys(config).length === 0 && !baseConfig) delete out['agentConfig'];
+    return out;
+}
+
 /**
  * The differences between `base` and `head` text of one manifest that are NOT a
  * version-string change in a declared version field. Empty means in shape.
@@ -94,6 +126,7 @@ export function manifestDifferences(file: string, base: string | null, head: str
     } catch (err) {
         return [`${file}: not parseable JSON (${(err as Error).message})`];
     }
+    if (file === 'package.json') b = _withoutReleaseImpactEntry(a, b);
     const allowed = VERSION_FIELDS[file] ?? [];
     const out: string[] = [];
     for (const p of _diffPaths(a, b)) {

package/src/scripts/check_release_pr_shape.ts

@@ -59,6 +59,11 @@ const ALLOWLIST_GLOBS = [
     // its regenerated dist twin (kept in lockstep with package.json.version).
     'src/agent-src/templates/agents/agent-project-settings.example.yml',
     'dist/agent-src/templates/agents/agent-project-settings.example.yml',
+    // Released settings surface — rewritten by release.ts writeReleasedSurface
+    // inside the cut, so without this entry the release PR carries a file its
+    // own shape step refuses. It is the base the NEXT cut's settings-delta
+    // assertion reads.
+    'tests/fixtures/settings_surface_released.json',
 ] as const;
 
 /**

package/src/scripts/check_rule_invariants.ts

@@ -7,7 +7,15 @@
  * re-landed as #847 (13f244c9b — non-destructive "Irreversible external action"
  * row + "Never act while asking" clause) and #849 (2c46e7f3b — direct-answers
  * "no duration estimates" + "never cite the rule"). This checker's invariant set
- * covers those exact strings — it would have flagged the loss at CI time.
+ * covers those exact strings — so a run of it would have caught the loss.
+ *
+ * WHERE it runs, stated because the line above used to say "at CI time" and
+ * that is not where this is registered: the only caller is `task ci`, and no
+ * workflow under `.github/workflows/` invokes `task ci` — three steps in
+ * `consistency.yml` say so in as many words, which is why they re-register
+ * their own gates there. It is also not in `task preflight`. So the loss would
+ * have been caught by someone running the full local chain, and by nothing on
+ * the pull request.
  *
  * Loads `tests/golden/invariants.json` and verifies that every invariant
  * string (whitespace-normalised: runs of whitespace collapse to a single