@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/_lib/security_lint.ts

@@ -13,8 +13,12 @@
 //      skipped by every check. Grep-auditable, scoped to the block.
 //   2. Confidence weighting — a match in a doc / example / template / evals
 //      file scores at 0.25x; below the FAIL threshold it is a WARN.
-//   3. Per-file pragma — `<!-- security-lint: allow <check> "<reason>" -->`
-//      anywhere in the file suppresses one check for that file.
+//   3. Bound pragma — `<!-- security-lint: allow <check> "<reason>" sha256:<hex> -->`
+//      anywhere in the file suppresses ONE check for the specific evidence whose
+//      fingerprint is listed. Repeat `sha256:<hex>` once per accepted match. The
+//      unbound form (no hash) still suppresses the whole file and reports itself
+//      as a `legacy-pragma` finding, because a key lookup with no content
+//      binding accepts whatever that line is later changed to say.
 //
 // There is no global allowlist — that is the rejected pattern.
 //
@@ -27,6 +31,7 @@
 //   - `report()` reproduces the glyphs (🔴 / ⚠️), the `(-rank, path, line)`
 //     sort, the weight note `(weight 0.25)`, and every printed string verbatim.
 
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -61,11 +66,18 @@ export const DEFAULT_SCAN_ROOTS: readonly string[] = [
 const _EXAMPLE_PATH =
     /(^|\/)(docs|evals|tests?|fixtures?)(\/|$)|example|template|sample|\/_template/i;
 
-//   Python: re.compile(r'<!--\s*security-lint:\s*allow\s+(?P<check>[\w-]+)\s+"(?P<reason>[^"]+)"\s*-->')
+// Grammar: `<!-- security-lint: allow <check> "<reason>" [sha256:<hex>]... -->`
 // JS `\w` is ASCII-only by default (matches Python re's `[\w-]` for the ASCII
 // check ids used here). Global flag so finditer-style iteration works.
+//
+// The hash group is OPTIONAL and repeatable. Optional because the unbound form
+// must keep working — a grammar change that invalidates every existing pragma
+// at once turns a hardening into an outage, and the migration is what removes
+// the unbound population, not the parser. Repeatable because one file can
+// legitimately carry several accepted matches of the same check, and a single
+// hash would force either a second pragma line or a whole-file fallback.
 const _PRAGMA =
-    /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"\s*-->/g;
+    /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"((?:\s+sha256:[0-9a-f]{64})*)\s*-->/g;
 
 //   Python: re.compile(r"^(\s*)(`{3,}|~{3,})\s*([\w-]*)\s*$")
 const _FENCE = /^(\s*)(`{3,}|~{3,})\s*([A-Za-z0-9_-]*)\s*$/;
@@ -136,6 +148,21 @@ export function path_weight(rel_path: string): number {
     return is_example_path(rel_path) ? 0.25 : 1.0;
 }
 
+const PROJECTION_PREFIX = 'dist/agent-src/';
+
+/**
+ * Fold a projected path back onto the source it was copied from.
+ *
+ * `dist/agent-src/` is a byte-for-byte copy of `src/` with paths rewritten
+ * (ADR-201), so an artifact and its projection are the same artifact for the
+ * purpose of "which evidence did a human accept". Two identities would mean two
+ * fingerprints for one accepted line, and only one of them could be written
+ * into the pragma the projection copies verbatim.
+ */
+export function source_identity(rel: string): string {
+    return rel.startsWith(PROJECTION_PREFIX) ? `src/${rel.slice(PROJECTION_PREFIX.length)}` : rel;
+}
+
 /** A file pre-split into lines with a fence/pragma mask the linters reuse. */
 export class ScannedFile {
     path: string; // absolute or as-given path
@@ -145,6 +172,8 @@ export class ScannedFile {
     in_example_fence: boolean[];
     in_any_fence: boolean[];
     pragmas: Record<string, string>; // check id → reason
+    /** check id → the sha256 fingerprints that pragma accepts. Empty = unbound. */
+    pragma_hashes: Record<string, readonly string[]>;
     weight: number;
 
     constructor(
@@ -155,6 +184,7 @@ export class ScannedFile {
         in_any_fence: boolean[],
         pragmas: Record<string, string>,
         weight: number,
+        pragma_hashes: Record<string, readonly string[]> = {},
     ) {
         this.path = pathArg;
         this.rel = rel;
@@ -163,12 +193,82 @@ export class ScannedFile {
         this.in_any_fence = in_any_fence;
         this.pragmas = pragmas;
         this.weight = weight;
+        this.pragma_hashes = pragma_hashes;
     }
 
     pragma_allows(check: string): boolean {
         return Object.prototype.hasOwnProperty.call(this.pragmas, check);
     }
 
+    /**
+     * Which form of pragma this file carries for `check`.
+     *
+     * `absent`  — no pragma; scan normally.
+     * `legacy`  — a pragma with no fingerprint. Suppresses the whole file, as it
+     *             always did, and says so: a key lookup accepts whatever the
+     *             line is later changed to say, which is the defect being paid
+     *             down, not a mode anybody should choose.
+     * `bound`   — a pragma listing fingerprints. Suppresses exactly the matches
+     *             whose evidence hashes to one of them; anything else survives.
+     */
+    pragma_form(check: string): 'absent' | 'legacy' | 'bound' {
+        if (!this.pragma_allows(check)) return 'absent';
+        return (this.pragma_hashes[check] ?? []).length > 0 ? 'bound' : 'legacy';
+    }
+
+    /**
+     * The fingerprint one finding's evidence hashes to.
+     *
+     * WHAT IS HASHED, and each part earns its place:
+     *   check id      — the same line may legitimately be accepted for one check
+     *                   and not another.
+     *   rel path      — the location IDENTITY. Not the line NUMBER: an unrelated
+     *                   insert above would otherwise break every pragma in the
+     *                   file, and a suppression that breaks on unrelated edits
+     *                   gets deleted rather than re-derived. A `dist/agent-src/`
+     *                   path folds to its `src/` original first, because the
+     *                   projection is byte-exact by contract (ADR-201) and
+     *                   carries the pragma verbatim — without the fold, every
+     *                   migrated pragma would suppress the source and leave its
+     *                   own copy flagged, which is a gate that reds on a file
+     *                   nobody may edit.
+     *   matched line, — the evidence. ASCII whitespace runs collapse so a reflow
+     *   normalized      does not invalidate the binding, `sha256:<hex>` tokens are
+     *                   removed, and NOTHING else is stripped: the zero-width
+     *                   characters this suite hunts are exactly what a wider
+     *                   normalizer would erase.
+     *
+     * WHY THE HASH TOKENS COME OUT. A pragma's own reason string can be the
+     * matched evidence — two in this tree are, because they quote the very
+     * phrases their check detects in order to explain themselves. Without this
+     * the fingerprint would have to be computed over a line that already
+     * contains it, which has no fixed point: writing the hash changes the line,
+     * which changes the hash. Stripping the tokens makes the fingerprint stable
+     * under the act of recording it, and costs nothing elsewhere — a `sha256:`
+     * token in ordinary prose is not evidence of anything a linter here checks.
+     *
+     * Deliberately NOT the whole file: incidental content elsewhere would make
+     * every unrelated edit re-fire the pragma, which is the noise that produces
+     * blanket suppressions.
+     */
+    evidence_fingerprint(finding: Finding): string {
+        const text = finding.line > 0 ? (this.lines[finding.line - 1] ?? '') : '';
+        const normalized = text
+            .replace(/\s*sha256:[0-9a-f]{64}/g, '')
+            .replace(/[ \t]+/g, ' ')
+            .trim();
+        return createHash('sha256')
+            .update(`${finding.check}\n${source_identity(this.rel)}\n${normalized}`, 'utf-8')
+            .digest('hex');
+    }
+
+    /** Drop the findings this file's BOUND pragma for `check` accepts. */
+    filter_bound_pragma(check: string, findings: readonly Finding[]): Finding[] {
+        const accepted = new Set(this.pragma_hashes[check] ?? []);
+        if (accepted.size === 0) return [...findings];
+        return findings.filter((f) => !accepted.has(this.evidence_fingerprint(f)));
+    }
+
     /** Yield [lineno, text] honouring the fence masks (mirrors iter_lines). */
     *iter_lines(
         opts: { skip_example_fence?: boolean; skip_any_fence?: boolean } = {},
@@ -286,11 +386,21 @@ export function scan_file(filePath: string): ScannedFile {
     // Pragmas are explicit, grep-auditable opt-out markers — honour them
     // anywhere in the file.
     const pragmas: Record<string, string> = {};
+    const pragmaHashes: Record<string, readonly string[]> = {};
     for (const text of lines) {
         _PRAGMA.lastIndex = 0;
         let m: RegExpExecArray | null;
         while ((m = _PRAGMA.exec(text)) !== null) {
-            pragmas[m[1] as string] = m[2] as string;
+            const check = m[1] as string;
+            pragmas[check] = m[2] as string;
+            const hashes = (m[3] ?? '').match(/sha256:([0-9a-f]{64})/g) ?? [];
+            // Union across repeated pragmas for one check rather than replace:
+            // two lines each accepting one match is a legitimate spelling, and
+            // a last-one-wins read would silently drop the first.
+            pragmaHashes[check] = [
+                ...(pragmaHashes[check] ?? []),
+                ...hashes.map((h) => h.slice('sha256:'.length)),
+            ];
             if (m.index === _PRAGMA.lastIndex) {
                 _PRAGMA.lastIndex += 1;
             }
@@ -305,6 +415,7 @@ export function scan_file(filePath: string): ScannedFile {
         in_any,
         pragmas,
         path_weight(rel),
+        pragmaHashes,
     );
 }
 
@@ -330,6 +441,7 @@ export function scan_path(filePath: string, base: string): ScannedFile {
         sf.in_any_fence,
         sf.pragmas,
         path_weight(rel),
+        sf.pragma_hashes,
     );
 }
 
@@ -379,12 +491,23 @@ function _pathCmp(a: string, b: string): number {
 }
 
 /** Yield ScannedFile for every matching file under the given roots. */
+/**
+ * Walk a corpus.
+ *
+ * `scanBase` exists for the bounded-root mode every child linter now carries
+ * (`--root DIR`): the roots stay relative, the base they resolve against moves.
+ * Absent, it is the package root and the walk is exactly what it always was —
+ * `scan_path(p, ROOT)` computes the same `rel` and the same `path_weight` as the
+ * `scan_file(p)` this used to call, so a flagless run reads the identical corpus
+ * with identical finding paths.
+ */
 export function* iter_corpus(
     roots: readonly string[] = DEFAULT_SCAN_ROOTS,
     exts: readonly string[] = ['.md'],
+    scanBase: string = ROOT,
 ): Generator<ScannedFile> {
     for (const root of roots) {
-        const base = path.join(ROOT, root);
+        const base = path.join(scanBase, root);
         if (!fs.existsSync(base)) {
             continue;
         }
@@ -396,12 +519,61 @@ export function* iter_corpus(
                 continue;
             }
             if (st.isFile() && exts.includes(path.extname(p))) {
-                yield scan_file(p);
+                yield scan_path(p, scanBase);
             }
         }
     }
 }
 
+/**
+ * The prefix a child linter uses to publish what it inspected, under `--json`.
+ *
+ * WHY STDERR, AND WHY ONLY UNDER `--json`. Under `--json` a child's STDOUT is a
+ * findings array with one consumer — `lint_agent_security`, which parses it.
+ * A count printed there would corrupt the payload. Stderr is free on that path
+ * and already carries the dead-scope diagnostic, so the umbrella reads the
+ * count from the same stream it would read a failure on.
+ *
+ * The umbrella SUMS these across its five children and publishes the total as
+ * its own `scanned:` line. The sum counts artifact INSPECTIONS, not distinct
+ * artifacts: a file in more than one child's corpus is counted once per child
+ * that read it. That is deliberate and is the stronger collapse detector — a
+ * distinct-union count would stay high when one child's corpus moved, as long
+ * as another child still covered those paths, which is exactly the failure
+ * `gate-coverage.yml` exists to catch.
+ */
+/** The check id an unbound pragma reports itself under. */
+export const LEGACY_PRAGMA_CHECK = 'legacy-pragma';
+
+/**
+ * The finding an unbound pragma emits about itself.
+ *
+ * LOW, so it never blocks: the unbound form is legal and this is a
+ * migration signal, not a violation. It is a FINDING rather than a printed
+ * aside so it travels every path the linters already have — the human report,
+ * the `--json` payload the umbrella aggregates, and the SARIF file — without
+ * a second reporting channel that only one of them reads.
+ */
+export function legacy_pragma_finding(sf: ScannedFile, check: string): Finding {
+    return new Finding(
+        sf.rel,
+        0,
+        LEGACY_PRAGMA_CHECK,
+        'LOW',
+        `unbound \`security-lint: allow ${check}\` pragma suppresses this whole file — ` +
+            'it accepts whatever the matched text is later changed to say. Bind it with ' +
+            '`sha256:<hex>` per accepted match.',
+        sf.weight,
+    );
+}
+
+export const CHILD_SCANNED_PREFIX = 'scanned: ';
+
+/** Publish a child linter's inspected count on stderr. See {@link CHILD_SCANNED_PREFIX}. */
+export function report_child_scanned(count: number): void {
+    process.stderr.write(`${CHILD_SCANNED_PREFIX}${String(count)}\n`);
+}
+
 /**
  * Print findings grouped by severity; return an exit code.
  *

package/src/scripts/_lib/self_repair.ts

@@ -30,14 +30,27 @@ import { createHash } from 'node:crypto';
 import { redact_low_impact_entry } from '../ai_council/redact_low_impact_entry.js';
 import { is_kernel_rule } from './kernel_rules.js';
 
-/** Where a record came from. */
-export type DefectSource = 'user-reported' | 'self-detected';
+/**
+ * Where a record came from.
+ *
+ * `user-reported` and `self-detected` both require something to have FIRED — a
+ * user complaint, or a deterministic detector. `model-noticed` is the third
+ * intake: a model notices an edge case in a rule, or a methodology the user
+ * just explained that no skill carries. Nothing fired, and before this source
+ * existed such an observation had no record type at all and was handed to a
+ * host-native memory tool no reader of this repository can query.
+ *
+ * It is a SOURCE and not a second store: the record shape, the fingerprint
+ * derivation, the noclobber path and the creation cap are all unchanged.
+ */
+export type DefectSource = 'user-reported' | 'self-detected' | 'model-noticed';
 
 /** The defect classes a record can carry. One class = one detector. */
 export type DefectClass =
     | 'user-reported'
     | 'council-availability-claim'
-    | 'language-mirror';
+    | 'language-mirror'
+    | 'model-noticed';
 
 /**
  * Runtime mirror of `DefectClass`, in declaration order. The upstream issue
@@ -49,6 +62,7 @@ export const DEFECT_CLASSES: readonly DefectClass[] = [
     'user-reported',
     'council-availability-claim',
     'language-mirror',
+    'model-noticed',
 ];
 
 /** How far a record may travel outward. */
@@ -61,14 +75,94 @@ export interface DefectFinding {
     evidence: string;
     /** One line naming what the fix should change. */
     suggested_surface: string;
+    /**
+     * The assets this record is ABOUT, drawn from a closed vocabulary and
+     * resolved against the tree at write time (see `partitionTargets`).
+     *
+     * `suggested_surface` is free text, so no record could ever be JOINED to
+     * the asset it describes — two records about one rule's weakness were two
+     * unrelated strings. A target is machine-addressable, which is what makes
+     * the per-target occurrence count in `targetCounts` possible at all.
+     *
+     * An EMPTY list stays legal: a real observation with no identified home is
+     * information, not an error. That is deliberately different from an
+     * UNRESOLVABLE entry, which lands in `proposes` instead.
+     */
+    target?: string[];
+    /**
+     * Target-shaped strings that do not resolve in the tree — a rule that does
+     * not exist yet, a skill the record is proposing. Kept rather than
+     * rejected, because "this should exist" is a legitimate observation; kept
+     * SEPARATE from `target`, because a silently accepted unresolvable id is
+     * worse than free text — it looks joined and joins to nothing.
+     */
+    proposes?: string[];
 }
 
+/** The four asset kinds a `target` entry may address. */
+export const TARGET_KINDS = ['rule', 'skill', 'command', 'hook'] as const;
+export type TargetKind = (typeof TARGET_KINDS)[number];
+
+/** `<kind>:<id>` — closed prefix, id-shaped remainder. Never free text. */
+export const TARGET_RE = /^(rule|skill|command|hook):([a-z0-9][a-z0-9._-]*)$/;
+
+/** Shape only — says nothing about whether the id exists. */
+export function isWellFormedTarget(value: string): boolean {
+    return TARGET_RE.test(value);
+}
+
+/** Split a well-formed target into its kind and id, or null. */
+export function parseTarget(value: string): { kind: TargetKind; id: string } | null {
+    const m = TARGET_RE.exec(value);
+    return m === null ? null : { kind: m[1] as TargetKind, id: m[2] as string };
+}
+
+/**
+ * What a record is doing now.
+ *
+ * The pair `open | released` could express neither a DECLINED record (which
+ * stayed `open` in the queue line for ever) nor a partially actioned one, so
+ * the only way a record left the queue was to be released. Six states, closed:
+ *
+ *   - `open`       — queued, nothing decided.
+ *   - `candidate`  — accepted as worth acting on, not yet acted on.
+ *   - `actioned`   — a fix or a decision landed.
+ *   - `declined`   — deliberately not acted on. Terminal, and NOT a failure.
+ *   - `superseded` — another record covers it.
+ *   - `parked`     — waiting on a named condition; REQUIRES `parked_until`,
+ *                    because a park with no wake condition is a deferral
+ *                    wearing a condition's clothes.
+ */
+export type DefectStatus =
+    | 'open'
+    | 'candidate'
+    | 'actioned'
+    | 'declined'
+    | 'superseded'
+    | 'parked';
+
+export const DEFECT_STATUSES: readonly DefectStatus[] = [
+    'open',
+    'candidate',
+    'actioned',
+    'declined',
+    'superseded',
+    'parked',
+];
+
+/** Statuses that keep a record in the queue line. */
+export const ACTIVE_STATUSES: readonly DefectStatus[] = ['open', 'candidate'];
+
 export interface DefectRecord extends DefectFinding {
     fingerprint: string;
     first_seen: string;
     last_seen: string;
     occurrences: number;
-    status: 'open' | 'released';
+    status: DefectStatus;
+    /** MANDATORY when `status === 'parked'`: when the record comes back. */
+    parked_until?: string;
+    /** One line saying why the record reached a terminal status. */
+    resolution?: string;
     /**
      * Failed egress attempts from the most recent `release` call, sanitized at
      * write time. Local-only bookkeeping: `renderReport` never includes them,
@@ -617,6 +711,38 @@ export function creationCapReached(
     return recentCreations(existing, finding.source, now) >= NEW_RECORDS_PER_SOURCE_PER_WINDOW;
 }
 
+/**
+ * Shape validation for a stored record. Returns the problems, `[]` when valid.
+ *
+ * The one obligation that is NOT a style nit: a `parked` record without a
+ * `parked_until` is a deferral nothing can wake. Everything else here is the
+ * closed-vocabulary check the free-text era could not perform.
+ */
+export function validateRecord(record: DefectRecord): string[] {
+    const out: string[] = [];
+    if (!(DEFECT_STATUSES as readonly string[]).includes(record.status)) {
+        out.push(`status '${String(record.status)}' is outside the closed enum`);
+    }
+    if (record.status === 'parked' && (record.parked_until ?? '').trim() === '') {
+        out.push('status is `parked` but `parked_until` is missing — a park with no wake condition is a deferral, not a park');
+    }
+    for (const value of record.target ?? []) {
+        if (!isWellFormedTarget(value)) {
+            out.push(`target '${value}' is not \`<rule|skill|command|hook>:<id>\``);
+        }
+    }
+    return out;
+}
+
+/** Union of two id lists, order-stable and de-duplicated. */
+function _mergeIds(a: readonly string[] | undefined, b: readonly string[] | undefined): string[] {
+    const out: string[] = [];
+    for (const v of [...(a ?? []), ...(b ?? [])]) {
+        if (!out.includes(v)) out.push(v);
+    }
+    return out;
+}
+
 export function mergeRecord(
     existing: DefectRecord | null,
     finding: DefectFinding,
@@ -624,13 +750,22 @@ export function mergeRecord(
 ): DefectRecord {
     const fp = fingerprint(finding.defect_class, finding.evidence);
     if (existing !== null && existing.fingerprint === fp) {
-        return {
+        const target = _mergeIds(existing.target, finding.target);
+        const proposes = _mergeIds(existing.proposes, finding.proposes);
+        const merged: DefectRecord = {
             ...existing,
             last_seen: now,
             occurrences: existing.occurrences + 1,
-            // A record the user re-reports after a release is open again.
+            // A record re-reported after it left the queue is open again. The
+            // widened enum does not change this: a recurrence refutes whatever
+            // disposition was taken, which is exactly `recurring-criticism`.
             status: 'open',
+            ...(target.length > 0 ? { target } : {}),
+            ...(proposes.length > 0 ? { proposes } : {}),
         };
+        // `open` carries no wake condition; a stale one would read as a park.
+        delete merged.parked_until;
+        return merged;
     }
     return {
         ...finding,