@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/learning_sidecar.ts

@@ -22,8 +22,15 @@
  * auto-promoted) — it NEVER mutates the curated YAML truths. Deterministic:
  * byte-stable for a fixed `now` + a fixed intake set.
  *
+ * `--format status` is the third, human-facing view (road-to-learning-you-can-
+ * see Phase 2): the verdict counts, the top `preferred` lessons with their
+ * corroboration and age, and the sentence saying what a promotion requires. It
+ * is a FORMAT and not a verb (decision D2 cites ADR-041) — `memory:learn`
+ * passes argv straight through, so a format needs no registry row — and it is
+ * read-only to the point of refusing `--write` rather than ignoring it.
+ *
  * Usage: learning_sidecar.ts [--intake-dir DIR] [--out-dir DIR] [--now ISO]
- *                            [--write] [--format text|json]
+ *                            [--write] [--format text|json|status]
  * Exit codes: 0 ok, 2 usage error, 3 internal error.
  */
 import { createHash } from 'node:crypto';
@@ -48,7 +55,11 @@ export const SCHEMA_VERSION = 1;
 export type Polarity = 'preferred' | 'dead_end';
 export type Verdict = 'preferred' | 'contested' | 'dead_end';
 
-interface Signal {
+/** The output formats. `status` is the one-screen human view (read-only). */
+export const FORMATS = ['text', 'json', 'status'] as const;
+export type Format = (typeof FORMATS)[number];
+
+export interface Signal {
     id: string;
     ts: string;
     tsMs: number;
@@ -226,9 +237,21 @@ export function aggregate(signals: readonly Signal[], nowMs: number): Lesson[] {
 }
 
 export function buildSidecar(intakeDir: string, nowIso: string): Sidecar {
+    return buildSidecarFromSignals(readSignals(intakeDir), nowIso);
+}
+
+/**
+ * The half of `buildSidecar` that does not read the disk.
+ *
+ * Split out for a caller that needs BOTH the input count and the output
+ * lessons from one pass — the session-end dogfood ledger records `signals_in`
+ * beside `lessons_out`, and reading the intake twice to get them would make the
+ * two numbers describe two different reads under the 2 s budget they exist to
+ * measure.
+ */
+export function buildSidecarFromSignals(signals: readonly Signal[], nowIso: string): Sidecar {
     const nowMs = _parseTsMs(nowIso) ?? 0;
-    const lessons = aggregate(readSignals(intakeDir), nowMs);
-    return { schema_version: SCHEMA_VERSION, generated_at: nowIso, lessons };
+    return { schema_version: SCHEMA_VERSION, generated_at: nowIso, lessons: aggregate(signals, nowMs) };
 }
 
 /** Render the human dead-ends + contested ledger. */
@@ -261,22 +284,98 @@ export function renderLessonsMd(sidecar: Sidecar): string {
     return L.join('\n');
 }
 
+/** How many `preferred` lessons the status screen lists before it stops. */
+export const STATUS_TOP_N = 5;
+
+/**
+ * The human step. Printed as the LAST line of the status screen, because this
+ * tree writes no rule and no skill on its own: a lesson becomes a durable
+ * artefact only when a person carries it through `/memory:propose` or the
+ * `learning-to-rule-or-skill` skill. A list of preferred lessons is one flag
+ * away from `--apply`, and naming the hand-off on every screen is the cheapest
+ * standing answer to "why is there no button".
+ */
+export const PROMOTION_HANDOFF =
+    'Promote by hand: /memory:propose · src/skills/learning-to-rule-or-skill/SKILL.md';
+
+/**
+ * One screen answering "what has this learned?" — verdict counts, the top
+ * `preferred` lessons with their corroboration and age, and what a promotion
+ * requires. READ ONLY by construction: it takes a built sidecar and returns a
+ * string, so there is no path from this function to the disk.
+ */
+export function renderStatus(sidecar: Sidecar): string {
+    const byVerdict: Record<Verdict, number> = { preferred: 0, contested: 0, dead_end: 0 };
+    for (const l of sidecar.lessons) byVerdict[l.verdict] += 1;
+
+    const nowMs = _parseTsMs(sidecar.generated_at) ?? 0;
+    const L: string[] = [];
+    L.push(`${PROG}: ${String(sidecar.lessons.length)} lesson(s) as of ${sidecar.generated_at}`);
+    L.push(
+        `preferred: ${String(byVerdict.preferred)} · ` +
+            `contested: ${String(byVerdict.contested)} · ` +
+            `dead-end: ${String(byVerdict.dead_end)}`,
+    );
+    L.push('');
+
+    const preferred = sidecar.lessons
+        .filter((l) => l.verdict === 'preferred')
+        .sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : 1))
+        .slice(0, STATUS_TOP_N);
+    L.push(`Top ${String(STATUS_TOP_N)} preferred:`);
+    if (preferred.length === 0) {
+        L.push('  (none — a lesson needs corroboration before it appears here)');
+    } else {
+        preferred.forEach((l, i) => {
+            // Age is floored, so a lesson seen hours ago reads `0d old` rather
+            // than rounding up into a day it has not lived.
+            const ageDays = Math.max(0, Math.floor((nowMs - (_parseTsMs(l.last_ts) ?? nowMs)) / 86400000));
+            L.push(
+                `  ${String(i + 1)}. ${l.entry_type} @ ${l.path} — ` +
+                    `${String(l.corroborations)} origins, ${String(ageDays)}d old`,
+            );
+            L.push(`     ${l.body}`);
+        });
+    }
+    L.push('');
+    L.push(
+        `A lesson is promoted at ${String(MIN_CORROBORATIONS)} distinct origins, ` +
+            `weighted by a ${String(HALF_LIFE_DAYS)}-day half-life; nothing here promotes itself.`,
+    );
+    L.push(PROMOTION_HANDOFF);
+    return `${L.join('\n')}\n`;
+}
+
 export function main(argv: string[]): number {
     let intakeDir = path.join('agents', 'memory', 'intake');
     let outDir = path.join('agents', 'memory');
     let nowIso = '';
     let write = false;
-    let format: 'text' | 'json' = 'text';
+    let format: Format = 'text';
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] as string;
         if (a === '--intake-dir') intakeDir = argv[++i] ?? intakeDir;
         else if (a === '--out-dir') outDir = argv[++i] ?? outDir;
         else if (a === '--now') nowIso = argv[++i] ?? '';
         else if (a === '--write') write = true;
-        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
-        else if (a === '-h' || a === '--help') {
+        else if (a === '--format') {
+            const raw = argv[++i] ?? '';
+            // Validated rather than cast. With two formats an unknown value
+            // fell through to `text` and looked like it had worked; with three,
+            // a typo in `status` would silently print the one-line text form
+            // and a reader would take that for the screen they asked for.
+            if (!(FORMATS as readonly string[]).includes(raw)) {
+                process.stderr.write(
+                    `${PROG}: error: argument --format: invalid choice: '${raw}' ` +
+                        `(choose from ${FORMATS.map((f) => `'${f}'`).join(', ')})\n`,
+                );
+                return 2;
+            }
+            format = raw as Format;
+        } else if (a === '-h' || a === '--help') {
             process.stdout.write(
-                `usage: ${PROG} [--intake-dir DIR] [--out-dir DIR] [--now ISO] [--write] [--format text|json]\n`,
+                `usage: ${PROG} [--intake-dir DIR] [--out-dir DIR] [--now ISO] [--write] ` +
+                    `[--format ${FORMATS.join('|')}]\n`,
             );
             return 0;
         } else {
@@ -284,6 +383,14 @@ export function main(argv: string[]): number {
             return 2;
         }
     }
+    if (format === 'status' && write) {
+        // Refused, not ignored. The acceptance criterion is that the screen
+        // leaves `git status` identical; ignoring the flag would honour that
+        // too, but it would do so silently, and a caller who asked for a write
+        // deserves to be told it did not happen.
+        process.stderr.write(`${PROG}: error: --format status is read-only; drop --write\n`);
+        return 2;
+    }
     if (!nowIso) {
         // Deterministic by contract: refuse to guess `now` from the clock when
         // writing, so output is reproducible. Callers pass --now explicitly.
@@ -310,6 +417,10 @@ export function main(argv: string[]): number {
         process.stdout.write(JSON.stringify(sidecar, null, 2) + '\n');
         return 0;
     }
+    if (format === 'status') {
+        process.stdout.write(renderStatus(sidecar));
+        return 0;
+    }
     const byVerdict = { preferred: 0, contested: 0, dead_end: 0 };
     for (const l of sidecar.lessons) byVerdict[l.verdict] += 1;
     process.stdout.write(

package/src/scripts/lint_blocker_citations.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env tsx
+/**
+ * Every `path:line` a roadmap blocker cites must still point at a line.
+ *
+ * A blocker's `What to do` and `Resolved when` lean on citations like
+ * `src/scripts/foo.ts:120-134`. Line numbers move with every edit above them,
+ * and nothing re-reads a citation once it is written — `check_references`
+ * resolves names, not line numbers. A cited range that now runs past the end
+ * of its file sends the reader of the blocker to nothing.
+ *
+ * Scope: the `## Blockers` section of every active roadmap and every stub.
+ * Checked: the file exists and the last cited line is within its length.
+ * Not checked: what the line says — a content check would red on every
+ * harmless edit above it.
+ *
+ * A citation is a repository-relative path with a file extension, `:`, a line
+ * number and an optional `-<line>` end. A bare `:354-359` with no path is
+ * relative to prose above it and is not read.
+ *
+ * Existing misses are ratcheted (`gate-violation-baselines.json`, gate
+ * `lint_blocker_citations`): line numbers drift, so a miss already in the tree
+ * is drift rather than a new defect, and the count may only fall.
+ *
+ * Exit codes: 0 within the ratchet · 1 above it · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { checkRatchet } from './_lib/gate_baseline.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+type MissKind = 'missing-file' | 'beyond-end';
+
+interface Citation {
+    roadmap: string;
+    line: number;
+    target: string;
+    first: number;
+    last: number;
+}
+
+interface Miss extends Citation {
+    kind: MissKind;
+    length: number | null;
+}
+
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const CITATION_RE = /(?<![\w./:-])((?:[\w.-]+\/)*[\w-][\w.-]*\.[A-Za-z0-9]+):(\d+)(?:-(\d+))?(?!\d)/g;
+
+/** Citations inside the `## Blockers` section, with their line in the roadmap. */
+function citationsIn(text: string, roadmap: string): Citation[] {
+    const m = BLOCKERS_SECTION_RE.exec(text);
+    if (!m) {
+        return [];
+    }
+    const start = m.index + m[0].length;
+    const rest = text.slice(start);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = h2 ? rest.slice(0, h2.index) : rest;
+    const lineOffset = text.slice(0, start).split('\n').length - 1;
+    const out: Citation[] = [];
+    section.split('\n').forEach((raw, i) => {
+        for (const c of raw.matchAll(CITATION_RE)) {
+            const first = Number(c[2]);
+            const last = c[3] === undefined ? first : Number(c[3]);
+            out.push({ roadmap, line: lineOffset + i + 1, target: c[1] as string, first, last });
+        }
+    });
+    return out;
+}
+
+/** Line count of the cited file, repo-relative first, then relative to the citing roadmap. */
+function _lengthOf(root: string, c: Citation): number | null {
+    for (const abs of [path.join(root, c.target), path.join(root, path.dirname(c.roadmap), c.target)]) {
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+            return fs.readFileSync(abs, 'utf8').replace(/\n$/, '').split('\n').length;
+        }
+    }
+    return null;
+}
+
+function checkCitation(root: string, c: Citation, lengths: Map<string, number | null>): Miss | null {
+    const key = `${path.dirname(c.roadmap)}\0${c.target}`;
+    let length = lengths.get(key);
+    if (length === undefined) {
+        length = _lengthOf(root, c);
+        lengths.set(key, length);
+    }
+    if (length === null) {
+        return { ...c, kind: 'missing-file', length };
+    }
+    return Math.max(c.first, c.last) > length ? { ...c, kind: 'beyond-end', length } : null;
+}
+
+function roadmapFiles(root: string): string[] {
+    const out: string[] = [];
+    for (const sub of ['', 'stubs']) {
+        const dir = path.join(root, 'agents', 'roadmaps', sub);
+        let names: string[];
+        try {
+            names = fs.readdirSync(dir);
+        } catch {
+            continue;
+        }
+        for (const n of names.sort()) {
+            const abs = path.join(dir, n);
+            if (n.endsWith('.md') && fs.statSync(abs).isFile()) {
+                out.push(path.relative(root, abs).split(path.sep).join('/'));
+            }
+        }
+    }
+    return out;
+}
+
+function scanTree(root: string): { misses: Miss[]; scanned: number; citations: number } {
+    const lengths = new Map<string, number | null>();
+    const files = roadmapFiles(root);
+    const misses: Miss[] = [];
+    let citations = 0;
+    for (const rel of files) {
+        for (const c of citationsIn(fs.readFileSync(path.join(root, rel), 'utf8'), rel)) {
+            citations += 1;
+            const miss = checkCitation(root, c, lengths);
+            if (miss) {
+                misses.push(miss);
+            }
+        }
+    }
+    return { misses, scanned: files.length, citations };
+}
+
+const _DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    let root = _DEFAULT_ROOT;
+    let baselineRoot = _DEFAULT_ROOT;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--root') {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                process.stderr.write('lint_blocker_citations: --root requires a value\n');
+                return 2;
+            }
+            root = path.resolve(v);
+            baselineRoot = root;
+            i += 1;
+        } else {
+            process.stderr.write(`lint_blocker_citations: unknown argument: ${String(arg)}\n`);
+            return 2;
+        }
+    }
+    const { misses, scanned, citations } = scanTree(root);
+    reportScanned({
+        gate: 'lint_blocker_citations',
+        scanned,
+        units: 'roadmap file(s)',
+        roots: ['agents/roadmaps', 'agents/roadmaps/stubs'],
+        allowEmpty: 'EMPTY_VALID: a checkout with no active roadmap cites nothing',
+    });
+    const verdict = checkRatchet({ gate: 'lint_blocker_citations', actual: misses.length, repoRoot: baselineRoot });
+    const lines = misses.map(
+        (m) =>
+            `  ${m.roadmap}:${String(m.line)} · ${m.target}:${String(m.first)}${m.last !== m.first ? `-${String(m.last)}` : ''} · ` +
+            (m.kind === 'missing-file' ? 'file does not exist' : `file has ${String(m.length)} line(s)`),
+    );
+    if (!verdict.ok) {
+        process.stderr.write(`❌  ${verdict.message}\n`);
+        process.stderr.write(`${lines.join('\n')}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  lint_blocker_citations: ${String(citations)} citation(s) in ${String(scanned)} roadmap file(s). ${verdict.message}\n`,
+    );
+    if (lines.length > 0) {
+        process.stdout.write(`${lines.join('\n')}\n`);
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main());
+        }
+    } catch {
+        if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+            process.exit(main());
+        }
+    }
+}
+
+export { citationsIn, checkCitation, scanTree, main };
+export type { Citation, Miss };

package/src/scripts/lint_evidence_artifacts.ts

@@ -50,6 +50,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
+import { parseExecutionMode } from './_lib/repeated_run.js';
 import { reportScanned } from './_lib/scan_scope.js';
 import { parseHonestNull, parseMarkerLine, parseSkipDeclaration } from './check_completion_review.js';
 
@@ -257,6 +258,14 @@ export function checkFiles(root: string, files: readonly string[], ledger?: Gate
             });
             continue;
         }
+        // The contract's second axis (repeated-run / flaky), orthogonal to the
+        // type marker above — any artifact may declare it.
+        const mode = parseExecutionMode(contents);
+        if (mode.kind === 'invalid') {
+            ledger?.fail(rel, `invalid evidence-mode: ${mode.reason}`);
+            findings.push({ file: rel, reason: `evidence-mode: ${mode.reason}` });
+            continue;
+        }
         ledger?.complete(rel);
     }
     return findings;

package/src/scripts/lint_hook_concern_budget.ts

@@ -52,8 +52,6 @@ function _load_manifest(p: string): Manifest {
 }
 
 interface SettingsBlock {
-    max_per_event?: number;
-    hard_fail?: boolean;
     tier1_concerns?: string[];
 }
 
@@ -66,9 +64,11 @@ function _isFile(p: string): boolean {
 }
 
 /**
- * Minimal YAML walk for `hooks.concern_budget.*`. Mirrors the Python
- * `_read_settings_block` line walker verbatim — no YAML dependency,
- * tolerant of missing keys / blocks.
+ * Minimal YAML walk for `hooks.concern_budget.tier1_concerns`. Mirrors the
+ * Python `_read_settings_block` line walker — no YAML dependency, tolerant of
+ * missing keys / blocks. `max_per_event` and `hard_fail` are not read: those
+ * keys were retired, the cap is {@link DEFAULT_MAX_PER_EVENT} and hard-fail is
+ * the `--strict` argv alone.
  */
 function _read_settings_block(settings_path: string): SettingsBlock {
     const out: SettingsBlock = {};
@@ -107,18 +107,7 @@ function _read_settings_block(settings_path: string): SettingsBlock {
             in_tier1 = false;
         }
         if (in_budget) {
-            let m = /^\s{4}max_per_event\s*:\s*(\d+)/.exec(line);
-            if (m) {
-                out.max_per_event = Number.parseInt(m[1] as string, 10);
-                in_tier1 = false;
-                continue;
-            }
-            m = /^\s{4}hard_fail\s*:\s*(true|false)/.exec(line);
-            if (m) {
-                out.hard_fail = m[1] === 'true';
-                in_tier1 = false;
-                continue;
-            }
+            let m: RegExpExecArray | null;
             if (/^\s{4}tier1_concerns\s*:\s*\[\s*\]/.test(line)) {
                 out.tier1_concerns = [];
                 in_tier1 = false;
@@ -173,8 +162,8 @@ function _check_concern_counts(
             if (count > max_per_event) {
                 warnings.push(
                     `platforms.${plat}.${event}: ${count} concerns ` +
-                        `(threshold ${max_per_event}). Trim or raise ` +
-                        'hooks.concern_budget.max_per_event in .agent-settings.yml.',
+                        `(threshold ${max_per_event}). Trim the cell; the cap is ` +
+                        'a fixed constant in lint_hook_concern_budget.ts.',
                 );
             }
         }
@@ -230,9 +219,9 @@ export function lint(
     }
 
     const settings = _read_settings_block(settings_path);
-    const max_per_event = settings.max_per_event ?? DEFAULT_MAX_PER_EVENT;
+    const max_per_event = DEFAULT_MAX_PER_EVENT;
     const tier1 = settings.tier1_concerns ?? DEFAULT_TIER1;
-    const hard_fail = (settings.hard_fail ?? DEFAULT_HARD_FAIL) || strict;
+    const hard_fail = DEFAULT_HARD_FAIL || strict;
 
     const warnings: string[] = [];
     const errors: string[] = [];

package/src/scripts/lint_hook_manifest.ts

@@ -52,6 +52,33 @@ const DEFAULT_MANIFEST = path.join(
 const HOOKS_DIR = path.join(REPO_ROOT, "src", "scripts", "hooks");
 const DEFAULT_HOST_LOWERING = path.join(HOOKS_DIR, "host_lowering.yaml");
 
+/**
+ * What a concern does to a turn — the closed set `effect:` draws from.
+ *
+ * Read by the neighbour census, which needs to say what sharing an event with
+ * a foreign entry actually risks. A foreign entry's effect is `unknown` unless
+ * its output shape has been observed: no host exposes another package's hook
+ * execution, so the honest default is that the neighbour's effect cannot be
+ * read off its registration.
+ *
+ * - `permission`   can refuse the thing it fires on
+ * - `context`      puts text in front of the model
+ * - `verification` checks a claim or a shape and reports what it found
+ * - `telemetry`    records state, a ledger, a counter
+ * - `memory`       reads or writes the memory layer
+ * - `notification` tells the human something and changes nothing else
+ * - `formatting`   reshapes a command or a generated file
+ */
+export const CONCERN_EFFECTS: ReadonlySet<string> = new Set([
+  "permission",
+  "context",
+  "verification",
+  "telemetry",
+  "memory",
+  "notification",
+  "formatting",
+]);
+
 // Canonical event vocabulary — keep in lock-step with
 // docs/contracts/hook-architecture-v1.md and dispatch_hook.EVENT_VOCABULARY.
 const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
@@ -159,6 +186,32 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
     if (!_isFile(path.join(REPO_ROOT, script))) {
       errors.push(`concerns.${name}: script not found at '${script}'`);
     }
+    // `effect:` — what this concern DOES to a turn, from a closed set. It is
+    // what lets the neighbour census say "a foreign entry shares this event
+    // with something of ours that can refuse" rather than only "two entries".
+    // Required and enum-checked, which is a stricter rule than the optional
+    // keys below for one reason: a concern with no effect, or with a
+    // misspelled one, would silently drop out of every double-gate comparison
+    // — the warning would stay quiet and read as "no conflict", which is the
+    // wrong answer rather than a missing one. There is no unknown-key guard
+    // on this mapping, so nothing else would catch `effects:`.
+    const effect = spec["effect"];
+    if (typeof effect !== "string" || !CONCERN_EFFECTS.has(effect)) {
+      errors.push(
+        `concerns.${name}: 'effect' must be one of ` +
+          `${[...CONCERN_EFFECTS].sort().join(" | ")} (got ${JSON.stringify(effect)})`,
+      );
+    } else if ((spec["severity"] === "blocking") !== (effect === "permission")) {
+      // The two fields answer the same question from different sides, so a
+      // disagreement is a mistake in one of them, never a shade of meaning:
+      // `blocking` is the dispatcher's word for "this can refuse" and
+      // `permission` is the census's.
+      errors.push(
+        `concerns.${name}: 'effect: ${effect}' contradicts ` +
+          `'severity: ${String(spec["severity"])}' — a concern that can refuse ` +
+          `is 'permission', and only those are 'blocking'`,
+      );
+    }
     // `tools:` — the optional per-concern tool filter the dispatcher applies
     // in-process (`_concern_matches_tool`). Validated because the failure mode
     // is silent: the dispatcher fails toward RUNNING the concern on anything