@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/check_loss_class_declared.ts

@@ -0,0 +1,308 @@
+#!/usr/bin/env tsx
+/**
+ * An undeclared lossy transform on a model-facing path fails
+ * (`road-to-runtime-context-floors` step 3.2).
+ *
+ * STRICTNESS — decided, not assumed
+ * ---------------------------------
+ * Council 2026-08-28 (2/2 convergent, anthropic + openai, 2 rounds) resolved the
+ * `how-strict-the-loss-class-lint-is` blocker as option (b): FAIL on transforms
+ * whose output reaches the model, WARN elsewhere. Option (a) — fail everywhere in
+ * `src/` — buys a first-run backlog whose usual answer is a broad allowlist, and
+ * this repository has a measured history of an allowlist emptying a gate. Option
+ * (c) — warn everywhere, ratchet later — is the shape this repository has
+ * measurably never ratcheted.
+ *
+ * Both seats added the same refinement, adopted here: **unknown reachability is
+ * classified as model-reaching.** Ambiguity must not become an accidental
+ * exemption.
+ *
+ * WHAT COUNTS AS MODEL-FACING
+ * ---------------------------
+ * A hook concern bound on a slot whose output can reach the model, whose script
+ * BOTH emits a context payload AND applies a lossy operation to content. Both
+ * halves are read from code with comments stripped — the first cut of this
+ * detector matched `truncat` inside three docblocks that describe truncation
+ * without performing any, and a gate that fires on prose about a defect rather
+ * than the defect is how a real corpus of one becomes a pro-forma corpus of four.
+ *
+ * Measured at landing: **1** module qualifies — `hot_context_hook`, which is
+ * exactly the `ephemeral-lossy` exemplar the contract classifies. A corpus of one
+ * is the honest state of this tree, not a broken detector; the gate fires the day
+ * a second lands.
+ *
+ * Exit codes: 0 clean (warnings allowed) · 1 an undeclared model-facing
+ * transform · 2 misuse / unreadable manifest.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_loss_class_declared [--root <dir>] [--json] [--quiet]
+ *   ./scripts-run src/scripts/check_loss_class_declared --self-test
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { isProblem, parseLossDeclaration, type DeclarationProblem } from './_lib/loss_class.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+
+/** Slots whose output can reach the model. */
+const MODEL_FACING_SLOTS = [
+    'session_start',
+    'user_prompt_submit',
+    'pre_compact',
+    'stop',
+    'post_tool_use',
+    'pre_tool_use',
+] as const;
+
+/** Emitting a context payload — the "reaches the model" half. */
+const EMIT_PATTERNS = [/\bcontext\s*:/, /additionalContext/, /hookSpecificOutput/];
+
+/** Shortening, redacting or capping content — the "lossy" half. */
+const LOSSY_PATTERNS = [/\bredact/i, /\btruncat/i, /\b(?:WORD|CHAR|MAX)_(?:CAP|CHARS|LEN|WORDS)\b/];
+
+export interface LossFinding {
+    concern: string;
+    script: string;
+    tier: 'fail' | 'warn';
+    problem: DeclarationProblem;
+}
+
+export interface LossVerdict {
+    scanned: number;
+    modelFacing: number;
+    findings: LossFinding[];
+}
+
+/** Strip block and line comments so the detector reads CODE, never prose about code. */
+export function stripComments(src: string): string {
+    return src
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/^\s*\/\/.*$/gm, '');
+}
+
+export function emitsContext(codeOnly: string): boolean {
+    return EMIT_PATTERNS.some((p) => p.test(codeOnly));
+}
+
+export function isLossy(codeOnly: string): boolean {
+    return LOSSY_PATTERNS.some((p) => p.test(codeOnly));
+}
+
+function loadManifest(root: string): { concerns: Record<string, { script?: unknown }>; platforms: Record<string, Record<string, string[]>> } {
+    const file = path.join(root, 'src', 'scripts', 'hook_manifest.yaml');
+    const raw = fs.readFileSync(file, 'utf-8');
+    const out = spawnSync(
+        process.execPath,
+        ['-e', 'const y=require("js-yaml");let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const d=y.load(s);process.stdout.write(JSON.stringify({concerns:d.concerns||{},platforms:d.platforms||{}}))})'],
+        { input: raw, encoding: 'utf-8', cwd: REPO_ROOT, maxBuffer: 64 * 1024 * 1024 },
+    );
+    if (out.status !== 0 || !out.stdout) throw new Error(`hook_manifest.yaml could not be parsed: ${out.stderr || 'no output'}`);
+    return JSON.parse(out.stdout) as { concerns: Record<string, { script?: unknown }>; platforms: Record<string, Record<string, string[]>> };
+}
+
+/**
+ * Which concerns sit on a model-facing slot.
+ *
+ * A concern bound on NO slot this gate recognises is `unknown` reachability, and
+ * per the council refinement it is treated as model-facing rather than skipped.
+ */
+export function modelFacingConcerns(platforms: Record<string, Record<string, string[]>>): Set<string> {
+    const out = new Set<string>();
+    for (const slots of Object.values(platforms)) {
+        if (slots === null || typeof slots !== 'object') continue;
+        for (const [slot, names] of Object.entries(slots)) {
+            if (!Array.isArray(names)) continue;
+            const facing = (MODEL_FACING_SLOTS as readonly string[]).includes(slot);
+            for (const n of names) if (facing) out.add(n);
+        }
+    }
+    return out;
+}
+
+export function evaluate(root: string = REPO_ROOT, ledger?: GateLedger): LossVerdict {
+    const { concerns, platforms } = loadManifest(root);
+    const facing = modelFacingConcerns(platforms);
+    const bound = new Set<string>();
+    for (const slots of Object.values(platforms)) {
+        if (slots === null || typeof slots !== 'object') continue;
+        for (const names of Object.values(slots)) if (Array.isArray(names)) for (const n of names) bound.add(n);
+    }
+
+    const findings: LossFinding[] = [];
+    let scanned = 0;
+    let modelFacing = 0;
+
+    ledger?.plan(Object.keys(concerns));
+
+    for (const [name, spec] of Object.entries(concerns)) {
+        const rel = typeof spec?.script === 'string' ? spec.script : null;
+        if (rel === null) {
+            ledger?.skip(name, 'manifest_absent');
+            continue;
+        }
+        const abs = path.join(root, rel);
+        if (!fs.existsSync(abs)) {
+            ledger?.skip(name, 'no_applicable_files');
+            continue;
+        }
+        scanned += 1;
+
+        const source = fs.readFileSync(abs, 'utf-8');
+        const code = stripComments(source);
+        if (!isLossy(code) || !emitsContext(code)) {
+            // Not a lossy model-facing transform: the check does not apply to it.
+            ledger?.outOfScope(name, 'not_applicable_kind');
+            continue;
+        }
+
+        // Unknown reachability fails closed: a bound concern this gate cannot
+        // place on a known slot is treated as model-reaching.
+        const reaches = facing.has(name) || !bound.has(name);
+        if (reaches) modelFacing += 1;
+
+        const decl = parseLossDeclaration(source);
+        if (!isProblem(decl)) {
+            ledger?.complete(name);
+            continue;
+        }
+        findings.push({ concern: name, script: rel, tier: reaches ? 'fail' : 'warn', problem: decl });
+        ledger?.fail(name, `undeclared or malformed loss_class (${decl.kind})`);
+    }
+    return { scanned, modelFacing, findings };
+}
+
+// ---------------------------------------------------------------- self-test
+
+const LOSSY_EMITTER = `
+const WORD_CAP = 400;
+export function run() {
+  const kept = redactLines(body).slice(0, WORD_CAP);
+  return { context: kept.join('\\n') };
+}
+`;
+
+function plant(dir: string, header: string, body: string, slot = 'session_start'): void {
+    fs.mkdirSync(path.join(dir, 'src', 'scripts'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'scripts', 'fixture_hook.ts'), header + body);
+    fs.writeFileSync(
+        path.join(dir, 'src', 'scripts', 'hook_manifest.yaml'),
+        `schema_version: 1\nconcerns:\n  fixture:\n    script: src/scripts/fixture_hook.ts\nplatforms:\n  claude:\n    ${slot}:\n      - fixture\n`,
+    );
+}
+
+const NO_DECL = '';
+const DECL_RECOVERABLE = '/**\n * loss_class: recoverable-lossy\n * loss_recovery: agents/knowledge/intake/<file>:<a>-<b>\n */\n';
+const DECL_RECOVERABLE_NO_LOCATOR = '/**\n * loss_class: recoverable-lossy\n */\n';
+const DECL_EPHEMERAL = '/**\n * loss_class: ephemeral-lossy\n */\n';
+const DECL_TYPO = '/**\n * loss_class: recoverable_lossy\n */\n';
+
+function selfTestCases(): SelfTestCase[] {
+    const mk = (name: string, expect: 'reject' | 'accept', header: string, body: string, slot?: string): SelfTestCase => ({
+        name,
+        expect,
+        run: () => {
+            const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lcd-'));
+            try {
+                plant(dir, header, body, slot);
+                return runGateCli(REPO_ROOT, 'src/scripts/check_loss_class_declared.ts', ['--root', dir, '--quiet'], REPO_ROOT);
+            } finally {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    });
+    return [
+        mk('model-facing lossy transform with no declaration → reject', 'reject', NO_DECL, LOSSY_EMITTER),
+        mk('same transform with recoverable-lossy + locator → accept', 'accept', DECL_RECOVERABLE, LOSSY_EMITTER),
+        mk('recoverable-lossy WITHOUT a locator → reject', 'reject', DECL_RECOVERABLE_NO_LOCATOR, LOSSY_EMITTER),
+        mk('ephemeral-lossy (owes no locator) → accept', 'accept', DECL_EPHEMERAL, LOSSY_EMITTER),
+        mk('a misspelled class is not honoured → reject', 'reject', DECL_TYPO, LOSSY_EMITTER),
+        mk('non-lossy emitter needs no declaration → accept', 'accept', NO_DECL, `export function run(){return {context:'hi'};}`),
+        mk('lossy but emits no context → accept', 'accept', NO_DECL, `const WORD_CAP=5;export function run(){return body.slice(0,WORD_CAP);}`),
+        mk('prose about truncation is not truncation → accept', 'accept', NO_DECL, `/* we deliberately never truncate or redact here */\nexport function run(){return {context:'hi'};}`),
+    ];
+}
+
+// ---------------------------------------------------------------------- CLI
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) {
+        return runSelfTest({ gate: 'check_loss_class_declared', cases: selfTestCases(), minCases: 7, minRejectCases: 3 });
+    }
+    const quiet = argv.includes('--quiet');
+    const json = argv.includes('--json');
+    const ri = argv.indexOf('--root');
+    const rootArg = ri !== -1 ? argv[ri + 1] : undefined;
+    const root = rootArg !== undefined ? path.resolve(rootArg) : REPO_ROOT;
+
+    const ledger = new GateLedger('check_loss_class_declared');
+    let v: LossVerdict;
+    try {
+        v = evaluate(root, ledger);
+    } catch (err) {
+        process.stderr.write(`❌  check_loss_class_declared: ${(err as Error).message}\n`);
+        return 2;
+    }
+
+    try {
+        reportScanned({ gate: 'check_loss_class_declared', scanned: v.scanned, units: 'hook script(s)', roots: ['src/scripts/hook_manifest.yaml'] });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  check_loss_class_declared: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
+    ledger.report();
+
+    if (json) {
+        process.stdout.write(JSON.stringify(v, null, 2) + '\n');
+        return v.findings.some((f) => f.tier === 'fail') ? 1 : 0;
+    }
+
+    const say = (f: LossFinding): string => {
+        switch (f.problem.kind) {
+            case 'missing':
+                return 'declares no loss_class';
+            case 'unknown-class':
+                return `declares loss_class: ${f.problem.value}, which is not one of the five`;
+            case 'missing-recovery':
+                return 'declares recoverable-lossy but no loss_recovery locator — without one the class is indistinguishable from ephemeral-lossy';
+        }
+    };
+
+    for (const f of v.findings) {
+        const stream = f.tier === 'fail' ? process.stderr : process.stdout;
+        stream.write(`${f.tier === 'fail' ? '❌' : '⚠️ '}  ${f.concern} (${f.script}) shortens content on a model-facing path and ${say(f)}\n`);
+    }
+
+    if (v.findings.some((f) => f.tier === 'fail')) {
+        process.stderr.write(
+            `\n    Add a declaration to the module's own docblock:\n` +
+                `      loss_class: exact | lossless | recoverable-lossy | ephemeral-lossy | forbidden\n` +
+                `      loss_recovery: <where the original is retrievable>   # recoverable-lossy only\n` +
+                `    Contract: docs/contracts/loss-classes.md\n`,
+        );
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  every model-facing lossy transform declares its loss class ` +
+                `(${String(v.modelFacing)} model-facing of ${String(v.scanned)} hook script(s)).\n`,
+        );
+    }
+    return 0;
+}
+
+if (process.env['GATE_SELF_TEST_CHILD'] !== '1' || process.argv.includes('--root')) {
+    if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+        process.exit(main());
+    }
+}

package/src/scripts/check_md_language.ts

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { classifyMarkdownLines } from './_lib/md_prose_lines.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 // Umlauts and German-only characters.
@@ -52,9 +53,6 @@ function _escapeRegExp(s: string): string {
 // Labeled bilingual anchor: lines starting with "DE:" or "- DE:" (and EN).
 const DE_ANCHOR_RE = /^\s*[-*]?\s*(DE|EN):\s/i;
 
-// Inline code spans.
-const INLINE_CODE_RE = /`[^`]*`/g;
-
 // Per-line escape marker.
 const IGNORE_RE = /<!--\s*md-language-check:\s*ignore\s*-->/i;
 
@@ -66,120 +64,39 @@ export interface Violation {
     context: string;
 }
 
-function _strip_inline_code(text: string): string {
-    return text.replace(INLINE_CODE_RE, '');
-}
-
-/** Python `str.splitlines()` — universal-newline split, no trailing empty element. */
-function splitlines(text: string): string[] {
-    if (text === '') return [];
-    const lines: string[] = [];
-    let current = '';
-    for (let i = 0; i < text.length; i++) {
-        const ch = text[i] as string;
-        const code = text.charCodeAt(i);
-        if (ch === '\r') {
-            lines.push(current);
-            current = '';
-            if (text[i + 1] === '\n') i += 1; // \r\n consumed as one
-            continue;
-        }
-        if (
-            ch === '\n' ||
-            code === 0x0b ||
-            code === 0x0c ||
-            code === 0x1c ||
-            code === 0x1d ||
-            code === 0x1e ||
-            code === 0x85 ||
-            code === 0x2028 ||
-            code === 0x2029
-        ) {
-            lines.push(current);
-            current = '';
-            continue;
-        }
-        current += ch;
-    }
-    if (current !== '') lines.push(current);
-    return lines;
-}
-
 export function scan_file(p: string): Violation[] {
     const violations: Violation[] = [];
-    let lines: string[];
+    let content: string;
     try {
-        lines = splitlines(fs.readFileSync(p, 'utf-8'));
+        content = fs.readFileSync(p, 'utf-8');
     } catch (exc) {
         const msg = exc instanceof Error ? exc.message : String(exc);
-        process.stderr.write(`⚠️  Cannot read ${p}: ${msg}\n`);
+        process.stderr.write(`\u26a0\ufe0f  Cannot read ${p}: ${msg}\n`);
         return violations;
     }
 
-    let in_fence = false;
-    let in_frontmatter = false;
-    for (let idx = 0; idx < lines.length; idx++) {
-        const raw = lines[idx] as string;
-        const lineno = idx + 1;
-        const stripped = _lstrip(raw);
-
-        // YAML frontmatter at top of file.
-        if (lineno === 1 && stripped === '---') {
-            in_frontmatter = true;
-            continue;
-        }
-        if (in_frontmatter) {
-            if (stripped === '---') {
-                in_frontmatter = false;
-            }
-            continue;
-        }
-
-        // Fenced code blocks.
-        if (stripped.startsWith('```') || stripped.startsWith('~~~')) {
-            in_fence = !in_fence;
-            continue;
-        }
-        if (in_fence) {
-            continue;
-        }
-
-        // Indented code blocks (4+ leading spaces, non-list).
-        const listStarts = ['-', '*', '+', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
-        if (raw.startsWith('    ') && !listStarts.some((c) => stripped.startsWith(c))) {
-            continue;
-        }
-
-        // Labeled bilingual anchor.
-        if (DE_ANCHOR_RE.test(raw)) {
-            continue;
-        }
-
-        // Per-line opt-out marker.
-        if (IGNORE_RE.test(raw)) {
-            continue;
-        }
-
-        // Strip inline code spans before scanning.
-        const scan_text = _strip_inline_code(raw);
-        const ctx = _rstrip(raw);
+    // Frontmatter / fence / indented-code / marker skipping is shared with
+    // `lint_canonical_terms` via `_lib/md_prose_lines` — see that module's
+    // header for why a second copy was refused. The classification is the same
+    // code this function used to carry inline; the DE:/EN: anchor and the
+    // per-line ignore marker are passed in as this gate's own markers.
+    for (const line of classifyMarkdownLines(content, { markers: [DE_ANCHOR_RE, IGNORE_RE] })) {
+        if (line.kind !== 'prose') continue;
+        const scan_text = line.text;
+        const ctx = _rstrip(line.raw);
 
         for (const m of scan_text.matchAll(UMLAUT_RE)) {
-            violations.push({ file: p, line: lineno, kind: 'umlaut', match: m[0], context: ctx });
+            violations.push({ file: p, line: line.lineno, kind: 'umlaut', match: m[0], context: ctx });
         }
 
         for (const m of scan_text.matchAll(DE_WORD_RE)) {
-            violations.push({ file: p, line: lineno, kind: 'de_word', match: m[0], context: ctx });
+            violations.push({ file: p, line: line.lineno, kind: 'de_word', match: m[0], context: ctx });
         }
     }
 
     return violations;
 }
 
-function _lstrip(s: string): string {
-    return s.replace(/^\s+/, '');
-}
-
 function _rstrip(s: string): string {
     return s.replace(/\s+$/, '');
 }

package/src/scripts/check_memory_proposal.ts

@@ -230,14 +230,24 @@ function parse_args(argv: readonly string[]): ParsedArgs {
     let quiet = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i]!;
-        if (arg === '--intake-id') {
-            intake_id = _need(argv, ++i, '--intake-id');
-        } else if (arg.startsWith('--intake-id=')) {
-            intake_id = arg.slice('--intake-id='.length);
-        } else if (arg === '--proposal') {
-            proposal = _need(argv, ++i, '--proposal');
-        } else if (arg.startsWith('--proposal=')) {
-            proposal = arg.slice('--proposal='.length);
+        // Mutual exclusion is checked INLINE, at the second flag, and the error
+        // names the flag that arrived second. That is what argparse does with a
+        // mutually exclusive group, and this file mirrors argparse's messages
+        // exactly — the post-loop check it replaced was order-stable and always
+        // blamed `--proposal`, which inverts the blame when `--proposal` came
+        // first. Reconciled toward the TEMPLATE side (road-to-memory-twin
+        // -reconciliation 2.1): the copy that looked like the drift was the
+        // faithful one.
+        if (arg === '--intake-id' || arg.startsWith('--intake-id=')) {
+            if (proposal !== null) {
+                _argparse_error('argument --intake-id: not allowed with argument --proposal');
+            }
+            intake_id = arg === '--intake-id' ? _need(argv, ++i, '--intake-id') : arg.slice('--intake-id='.length);
+        } else if (arg === '--proposal' || arg.startsWith('--proposal=')) {
+            if (intake_id !== null) {
+                _argparse_error('argument --proposal: not allowed with argument --intake-id');
+            }
+            proposal = arg === '--proposal' ? _need(argv, ++i, '--proposal') : arg.slice('--proposal='.length);
         } else if (arg === '--format') {
             const v = _need(argv, ++i, '--format');
             format = _checkFormat(v);
@@ -255,9 +265,6 @@ function parse_args(argv: readonly string[]): ParsedArgs {
             _argparse_error(`unrecognized arguments: ${arg}`);
         }
     }
-    if (intake_id !== null && proposal !== null) {
-        _argparse_error('argument --proposal: not allowed with argument --intake-id');
-    }
     if (intake_id === null && proposal === null) {
         _argparse_error('one of the arguments --intake-id --proposal is required');
     }