@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/check_knowledge_cards.ts

@@ -38,6 +38,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 // _lib package layout shifts; the TS twins always exist, so a static import is
 // byte-faithful for behaviour (the only observable effect is the --global path).
 import { asOf } from './_lib/as_of.js';
+import { REQUIRED_CARD_FIELDS } from './_lib/experience_card.js';
 import * as _kg from './_lib/knowledge_global.js';
 import * as _kgr from './_lib/knowledge_global_redaction.js';
 import { assertScanned } from './_lib/scan_scope.js';
@@ -201,13 +202,92 @@ function _check_card(
     }
 
     const lines = _splitlines(text);
+    const fm = _parse_frontmatter(text);
 
-    // C1 — size
-    if (lines.length > 150) {
+    // C1 — size. Scoped to the external arm with its five siblings: the README
+    // puts C1 in the C1–C6 band it calls "this variant's invariants", and says
+    // of that band that it is "not part of the `experience` variant at all".
+    // Running it on both arms while the comment below says the band is the
+    // external arm's was a contradiction between the code and its own note.
+    if ((fm['kind'] ?? 'external') !== 'experience' && lines.length > 150) {
         errors.push(`${rel}:${lines.length} — C1: card exceeds 150 lines (${lines.length})`);
     }
 
-    const fm = _parse_frontmatter(text);
+    // The directory is a TAGGED UNION, and C1–C6 belong to ONE arm of it.
+    //
+    // `agents/knowledge/README.md` records the AI council of 2026-08-30
+    // (anthropic + openai, 2/2) deciding the shape: `kind: external` cards
+    // cache expensive remote structural evidence and carry an authoritative
+    // pointer, a trust tier and a pinned source_version — "Checks C1–C6 in
+    // check_knowledge_cards are this variant's invariants". `kind: experience`
+    // cards are mined from this repository's own audit stream, have no remote
+    // source to point at, and the council was explicit that the external
+    // variant's checks "are not part of the `experience` variant at all".
+    //
+    // The port that produced this file froze the retired implementation's
+    // behaviour deliberately, and that implementation predates the union. So
+    // it ran C2 and C4 over an experience card and demanded `links.authoritative`,
+    // `trust` and `type: anti-hallucination` — three fields the experience
+    // contract does not define. One committed card reported three violations
+    // for having exactly the shape its own contract prescribes.
+    //
+    // Dispatching on `kind` rather than skipping: the experience arm is now
+    // checked against `REQUIRED_CARD_FIELDS` from `_lib/experience_card.ts`,
+    // which is the contract the council named. Skipping outright would have
+    // traded a wrong check for no check — nothing else walks this directory
+    // for the experience arm.
+    // Presence, not a non-empty scalar — and the count below is corrected from
+    // an earlier comment that said "four" while naming five, which an
+    // independent review caught. FIVE of the ten required fields can carry
+    // their value on the FOLLOWING lines rather than on the key's own line:
+    // the block lists `trigger_context`, `contradictions` and `supersedes`,
+    // and the block scalars `strategy` and `falsifier`. The tiny scalar-only
+    // parser above reads such a key as the empty string.
+    //
+    // The number is a CEILING on the risk, not a claim that all five bite
+    // today: a card writing `strategy: one short line` parses truthy, so only
+    // the ones actually written as blocks would. Asking for a truthy value
+    // would report a declared `trigger_context:` with three entries under it as
+    // missing — a reading of the parser, not of the card — and the set of
+    // fields that bite would then depend on how each card happened to be
+    // formatted, which is the worst property a required-field check can have.
+    const kind = fm['kind'] ?? 'external';
+    if (kind === 'experience') {
+        const block = FRONTMATTER_RE.exec(text)?.[1] ?? '';
+        const declared = new Set(
+            _splitlines(block)
+                .filter((l) => l.length > 0 && l[0] !== ' ' && l[0] !== '\t' && l.includes(':'))
+                .map((l) => l.slice(0, l.indexOf(':')).trim()),
+        );
+        for (const field of REQUIRED_CARD_FIELDS) {
+            if (!declared.has(field)) {
+                errors.push(`${rel}:0 — E1: experience card missing required '${field}' field`);
+            }
+        }
+
+        // ADR-100's G1–G5 ARE NOT PART OF THE UNION, and returning without them
+        // was a real hole rather than a tidiness point. They ask whether a card
+        // may be in the GLOBAL store — tier, sensitivity, the promotion audit
+        // trail, and G3's confidential-pattern scan — which is an orthogonal
+        // axis to which arm the card belongs to. `agents/knowledge/README.md`
+        // scopes C1–C6 to `kind: external` and says nothing of the G band,
+        // because the G band is about the store.
+        //
+        // Measured before the repair, at --global on a fixture: an experience
+        // card carrying `ops@…` and `build-07.internal` exited 0 and reported
+        // nothing, while the byte-identical card as `kind: external` reported
+        // G3 on the email and G1/G4 on the missing tier and sensitivity. The
+        // promotion path reaches this: `knowledge_global_cli promote` does not
+        // filter on `kind`.
+        //
+        // Scope of the loss, stated rather than overclaimed: promotion still
+        // redacts at write time, so what the early return killed was the
+        // STANDING AUDIT over an already-promoted store, not the write gate.
+        if (global_mode) {
+            errors.push(..._check_global_card(rel, text, fm));
+        }
+        return errors;
+    }
 
     // C4 — trust tagging
     if (!fm['trust']) {

package/src/scripts/check_memory.ts

@@ -54,6 +54,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML, { parseDocument } from 'yaml';
 
 import { asOf } from './_lib/as_of.js';
+import { assignmentPattern } from './_lib/egress_rules.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 type Severity = 'error' | 'warning' | 'info';
@@ -112,11 +113,20 @@ const _TYPE_COUNTS: Record<string, number> = {};
 // Redaction heuristics — plain-regex, deliberately conservative.
 // False positives are fixed by quoting the line differently; false
 // negatives are a curator responsibility.
-const REDACTION_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+export const REDACTION_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
     // Key=value secret with a clear credential-word prefix. The value must
     // be a single token (no spaces, no "/" — skips filepaths and URLs).
     [
-        /\b(api[_-]?key|auth[_-]?token|access[_-]?token|bearer|secret|password|passwd|private[_-]?key)\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{8,}(?![/.\w])/i,
+        assignmentPattern(
+            {
+                keywords: ['apiKey', 'authToken', 'accessToken', 'bearer', 'secret', 'password', 'passwd', 'privateKey'],
+                before: '\\b',
+                after: '\\b',
+                capture: true,
+                value: '[A-Za-z0-9+/=_\\-]{8,}(?![/.\\w])',
+            },
+            'i',
+        ),
         'inline credential',
     ],
     [/https?:\/\/[^\s"'/]*:[^\s"'/]*@/, 'url with credentials'],
@@ -895,7 +905,7 @@ function _isCliEntry(): boolean {
 const _isMain =
     _isCliEntry();
 if (_isMain) {
-    process.exit(main());
+    process.exitCode = main();
 }
 
 export { main };

package/src/scripts/check_pack_size.ts

@@ -342,7 +342,7 @@ const BOUND_PAYLOAD_EXCEPTIONS: readonly BoundPayloadException[] = [
     { fingerprint: 'aeffa474df3f805de07cdc9c6960c4918aa8e51e317fa1c30906d2f0267b7a16', path: 'dist/agent-src/templates/hooks/pre-commit-roadmap-progress', size: 3988, why: 'git hook template — same reason' },
     { fingerprint: '914f9c34551c5f4c42a70cd8bb0cd7b73078b0c4e7815b551833a3c64c8476d3', path: 'src/scripts/agent-config', size: 2391, why: 'the CLI entry script; an executable entry point carries no extension by convention' },
     { fingerprint: '0bb1cdd48ac2e9b6a2a56cde25de9fc221d75d42683680284c43118cff796e92', path: 'src/scripts/hooks/shims/php', size: 4439, why: 'shim invoked as the command name `php`; an extension would break the lookup' },
-    { fingerprint: 'b14bdd3cd589848ad8e6d7e5f4ee633dc9005a2a97abba327a9426ce556714da', path: 'src/scripts/install', size: 22049, why: 'the installer entry script; same reason as the CLI entry' },
+    { fingerprint: 'a82ebd0d5fc87f655b6c5ff64fa650810daeacd4aa9f3366aabeebe0bb017940', path: 'src/scripts/install', size: 23116, why: 'the installer entry script; same reason as the CLI entry' },
     { fingerprint: '1fb564019de468368e34941dffd5eb8bc994364313e02f476ff354ac0da464d7', path: 'src/templates/minimal/overrides-gitkeep', size: 164, why: 'placeholder that becomes .gitkeep on install; extensionless on purpose' },
 ];
 

package/src/scripts/check_permission_deny_syntax.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env tsx
+/**
+ * check_permission_deny_syntax — the provenance gate over the host permission
+ * deny-rule pins in `src/install/hostPermissionsAdapter.ts`.
+ *
+ * `road-to-a-project-contract-written-down` step 2.1. The step named
+ * `src/scripts/hooks/host_lowering.yaml` as the home for this pin, which would
+ * have put it behind the plumbing ratification record. The AI council of
+ * 2026-10-13 (anthropic + openai, 2/2, both converging on the same path)
+ * refused that home — a permission rule has no hook slot and no dispatcher
+ * verdict — and required a provenance gate in its place. This is that gate.
+ *
+ * ```
+ * A PIN WITH NO URL, NO READ DATE, OR A PASSED REVIEW DATE IS NOT A PIN.
+ * EVERY RULE THE RENDERER PRODUCES MATCHES THE GRAMMAR THE QUOTED EXAMPLES SHOW.
+ * ```
+ *
+ * WHAT THIS DOES NOT CLAIM, stated rather than implied. The examples are
+ * verbatim quotes recorded with their URL and read date; the renderer is
+ * checked against the grammar they exhibit. That is CONFORMANCE TO A RECORDED
+ * READING, not conformance to the live host — the same honesty limit the
+ * council named when it observed that a test reading the renderer's own
+ * constant proves internal consistency and nothing more. Only a probe against
+ * an installed host would close it, and this gate does not pretend to.
+ *
+ * It also deliberately does NOT fetch `docs_url`. A build that depends on a
+ * mutable vendor page is nondeterministic and fails on an unrelated edit to
+ * that page; the review date is the drift signal instead.
+ *
+ * Usage: ./scripts-run src/scripts/check_permission_deny_syntax [--today YYYY-MM-DD]
+ * Exit codes: 0 — every pin is current and every rule conforms · 1 — a finding.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { asOf } from './_lib/as_of.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import {
+    HOST_PERMISSION_SYNTAX,
+    denyRulesFor,
+    type HostPermissionSyntax,
+} from '../install/hostPermissionsAdapter.js';
+import { classifyNoGo } from '../install/noGoRules.js';
+
+/**
+ * Bullets this gate renders, one per rule shape the adapter can produce.
+ *
+ * Committed here rather than generated, so a renderer change that silently
+ * stops producing one of the shapes is a finding instead of a smaller fixture.
+ */
+const FIXTURES: readonly string[] = [
+    'Never edit `migrations/` by hand',
+    'Never overwrite `.env`',
+    'Never read `secrets/`',
+    'Never run `php artisan migrate:fresh` outside a throwaway database',
+];
+
+/** `Tool(specifier)` — the shape every example on the page exhibits. */
+const RULE_RE = /^(Edit|Read|Bash)\(.+\)$/;
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The ISO day after `iso`. */
+function dayAfter(iso: string): string {
+    const d = new Date(`${iso}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + 1);
+    return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Every finding against one row. Exported so the rejecting cases can be driven
+ * over crafted rows: this gate's corpus is a typed constant, not a file tree,
+ * so there is no `--root` fixture seam for a `_lib/gate_self_test.ts`
+ * `--self-test` to point at. `tests/scripts/permission_deny_syntax.test.ts`
+ * carries the discrimination proof instead, and runs on every commit.
+ */
+export function checkRow(row: HostPermissionSyntax, today: string): string[] {
+    const bad: string[] = [];
+    const where = `host \`${row.host}\``;
+    if (!row.docs_url.startsWith('https://')) {
+        bad.push(`${where}: docs_url is not an https URL`);
+    }
+    if (!ISO_RE.test(row.docs_at)) bad.push(`${where}: docs_at is not an ISO date`);
+    if (!ISO_RE.test(row.expires)) bad.push(`${where}: expires is not an ISO date`);
+    // One day of slack, because `docs_at` is written by a human in their own
+    // zone while `today` below is UTC. Without it a page read at 01:00 CEST
+    // reds the gate on the day it was read, which would teach the next author
+    // to back-date the field rather than to record when they read it.
+    if (ISO_RE.test(row.docs_at) && row.docs_at > dayAfter(today)) {
+        bad.push(`${where}: docs_at ${row.docs_at} is more than a day in the future`);
+    }
+    if (ISO_RE.test(row.expires) && row.expires < today) {
+        bad.push(
+            `${where}: the pin's review date ${row.expires} has passed — re-read ` +
+                `${row.docs_url}, update docs_at/expires, and re-check the examples`,
+        );
+    }
+    if (ISO_RE.test(row.docs_at) && ISO_RE.test(row.expires) && row.expires <= row.docs_at) {
+        bad.push(`${where}: expires ${row.expires} is not after docs_at ${row.docs_at}`);
+    }
+    if (row.deny_key.length === 0) bad.push(`${where}: deny_key is empty`);
+    if (row.examples.length === 0) bad.push(`${where}: no example is recorded`);
+    for (const ex of row.examples) {
+        if (!RULE_RE.test(ex)) bad.push(`${where}: example \`${ex}\` is not Tool(specifier)`);
+    }
+
+    // Every rule the renderer produces must use a tool the examples show, in
+    // the shape they show. A renderer that started emitting `Write(...)` — a
+    // rule the host accepts and never consults — is caught here.
+    const tools = new Set(row.examples.map((e) => e.slice(0, e.indexOf('('))));
+    const rendered: string[] = [];
+    for (const bullet of FIXTURES) {
+        for (const rule of denyRulesFor(row.host, classifyNoGo(bullet))) {
+            rendered.push(rule);
+            if (!RULE_RE.test(rule)) {
+                bad.push(`${where}: rendered \`${rule}\` is not Tool(specifier)`);
+                continue;
+            }
+            const tool = rule.slice(0, rule.indexOf('('));
+            if (!tools.has(tool)) {
+                bad.push(
+                    `${where}: rendered \`${rule}\` uses tool \`${tool}\`, which no recorded ` +
+                        'example shows',
+                );
+            }
+        }
+    }
+    if (rendered.length === 0) {
+        bad.push(`${where}: the fixtures rendered no rule at all`);
+        return bad;
+    }
+
+    // Each shape, asserted on its own. The earlier version checked only that
+    // SOME rule was produced and that each produced rule's tool was recorded,
+    // which a renderer that silently stopped emitting `Read(...)` passes — the
+    // comment above FIXTURES claimed this was covered and it was not.
+    for (const [label, matches] of SHAPES) {
+        if (!rendered.some(matches)) {
+            bad.push(
+                `${where}: the fixtures rendered no ${label} rule — a renderer that stops ` +
+                    'producing a shape must be a finding, not a smaller result',
+            );
+        }
+    }
+
+    // The PAIRING, not only the shapes. A `Read` no-go must also produce the
+    // `Edit` row the page requires for NotebookEdit, and a shape check alone
+    // cannot see that row disappear: the Edit shape stays satisfied by a
+    // different fixture's path rule.
+    for (const bullet of FIXTURES) {
+        const c = classifyNoGo(bullet);
+        if (c.action !== 'read') continue;
+        const rules = denyRulesFor(row.host, c);
+        const spec = rules
+            .find((r) => r.startsWith('Read('))
+            ?.slice('Read('.length, -1);
+        if (spec === undefined || !rules.includes(`Edit(${spec})`)) {
+            bad.push(
+                `${where}: the read fixture rendered no \`Edit(…)\` beside its \`Read(…)\` — ` +
+                    'the page names NotebookEdit as the tool a Read deny does not cover',
+            );
+        }
+    }
+    return bad;
+}
+
+/** One entry per rule shape the adapter is expected to be able to render. */
+const SHAPES: readonly (readonly [string, (r: string) => boolean])[] = [
+    ['Edit(path)', (r) => r.startsWith('Edit(')],
+    ['Read(path)', (r) => r.startsWith('Read(')],
+    ['Bash(exact command)', (r) => r.startsWith('Bash(') && !r.endsWith(' *)')],
+    ['Bash(command with arguments)', (r) => r.startsWith('Bash(') && r.endsWith(' *)')],
+];
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    // `asOf()`, not the wall clock: this gate's only time-dependent verdict is
+    // whether a pin's review date has passed, and a staleness verdict that
+    // differs between Monday and Friday over an unchanged tree is not
+    // reproducible from the commit. `--today` stays as this gate's own pin,
+    // which is what the rejecting cases in its test drive.
+    let today = asOf().toISOString().slice(0, 10);
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--today') {
+            const next = argv[i + 1];
+            if (next === undefined || !ISO_RE.test(next)) {
+                process.stderr.write('check_permission_deny_syntax: --today needs YYYY-MM-DD\n');
+                return 1;
+            }
+            today = next;
+            i += 1;
+        }
+    }
+
+    const rows = Object.values(HOST_PERMISSION_SYNTAX);
+    // Through the shared resolver, not a hand-written line: a gate that reports
+    // a count it never asserted can print `scanned: 0` and exit green, which is
+    // exactly the certify-an-empty-corpus failure this seam exists to stop.
+    // No `allowEmpty` — a pin table with no rows is a dead scope here, never an
+    // expected state, and the gate should say so rather than pass.
+    try {
+        reportScanned({
+            gate: 'check_permission_deny_syntax',
+            scanned: rows.length,
+            units: 'host permission pin(s)',
+            roots: ['src/install/hostPermissionsAdapter.ts'],
+        });
+    } catch (err) {
+        process.stderr.write(`❌  ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    const bad = rows.flatMap((row) => checkRow(row, today));
+    process.stdout.write(
+        `check_permission_deny_syntax ledger: scanned=${String(rows.length)} ` +
+            `planned=${String(rows.length)} skipped=0\n`,
+    );
+    if (bad.length > 0) {
+        for (const b of bad) process.stderr.write(`❌  ${b}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  check_permission_deny_syntax: ${String(rows.length)} host pin(s) current, ` +
+            `every rendered rule in the recorded grammar.\n`,
+    );
+    return 0;
+}
+
+/**
+ * True when this module is the process entry. Compared as resolved URLs, then
+ * as real paths: a raw `file://` string misses spaces, percent-encoding and
+ * symlinked paths (macOS `/var`), and a missed match exits 0 having run nothing.
+ */
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href ||
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}