@event4u/agent-config 8.7.0 → 8.8.0

package/src/scripts/domain_soundness_status.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env tsx
+/**
+ * Domain-soundness validation status + ratchet
+ * (road-to-domain-soundness Phase 1 + Phase 3).
+ *
+ * The four non-coding profiles (finance, founder, ops, content_creator) SELL
+ * concrete domain value (DCF, runway, RICE, incident command, messaging), but
+ * the skills are forged on TS/PHP — "promising, not proven" off those stacks.
+ * A disclaimer floor bounds liability, NOT correctness. This tool makes the
+ * provenance honest and machine-checkable: it enumerates the default-surface
+ * domain skills those profiles ship (from source — each profile's
+ * `skills_hint`, never hardcoded) and reports each as:
+ *
+ *   - `validated`   — ships `evals/domain-truth.json` (a sourced answer key,
+ *                     authored by domain competence, distinct from behavioural
+ *                     evals.json). Presence is the machine signal; a passing
+ *                     run against it is the maintainer's Phase-3 gate.
+ *   - `unvalidated` — no domain-truth fixture: general-purpose scaffold, domain
+ *                     correctness not independently validated.
+ *
+ * A domain skill can pass a format/behavioural eval AND carry a disclaimer AND
+ * still embed a wrong domain assumption — this axis is the one that catches it.
+ *
+ * Modes:
+ *   (default)      human report.
+ *   --json         machine-readable.
+ *   --check        ratchet gate (CI): the count of `validated` skills may not
+ *                  drop below the pinned floor (internal/evals/domain-soundness-floor.json);
+ *                  a missing floor is an all-zero floor (bootstrap-inert). The
+ *                  floor only rises via --write-floor after a fixture lands and
+ *                  passes. This is the enforced-honesty gate: it makes a claimed
+ *                  validation impossible to assert without the fixture on disk.
+ *   --write-floor  pin the current validated count as the floor (maintainer
+ *                  action after authoring + running a domain-truth fixture).
+ *
+ * Exit codes: 0 ok / 1 ratchet regression / 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The non-coding profiles whose default surface this tool scopes. */
+export const NON_CODING_PROFILES: readonly string[] = [
+    'finance',
+    'founder',
+    'ops',
+    'content_creator',
+];
+
+export interface StatusOptions {
+    skillsDir?: string;
+    profilesDir?: string;
+    floorPath?: string;
+}
+
+export interface SkillStatus {
+    skill: string;
+    status: 'validated' | 'unvalidated';
+}
+
+export interface SoundnessReport {
+    validationSet: SkillStatus[];
+    validated: number;
+    unvalidated: number;
+    total: number;
+}
+
+function _skillsDir(o: StatusOptions): string {
+    return o.skillsDir ?? path.join(REPO_ROOT, 'src', 'skills');
+}
+function _profilesDir(o: StatusOptions): string {
+    return o.profilesDir ?? path.join(REPO_ROOT, 'src', 'agent-src', 'profiles');
+}
+export function _floorPath(o: StatusOptions = {}): string {
+    return (
+        o.floorPath ??
+        path.join(REPO_ROOT, 'internal', 'evals', 'domain-soundness-floor.json')
+    );
+}
+
+/** Union of the non-coding profiles' `skills_hint`, restricted to real skills. */
+export function validationSet(o: StatusOptions = {}): string[] {
+    const profilesDir = _profilesDir(o);
+    const skillsDir = _skillsDir(o);
+    const out = new Set<string>();
+    for (const p of NON_CODING_PROFILES) {
+        const f = path.join(profilesDir, `${p}.yml`);
+        let doc: unknown;
+        try {
+            doc = parseYaml(fs.readFileSync(f, 'utf-8'));
+        } catch {
+            continue;
+        }
+        const profile = (doc as { profile?: unknown } | null)?.profile;
+        const defaults = (profile as { defaults?: unknown } | null)?.defaults;
+        const hint = (defaults as { skills_hint?: unknown } | null)?.skills_hint;
+        if (Array.isArray(hint)) {
+            for (const s of hint) {
+                if (typeof s === 'string' && fs.existsSync(path.join(skillsDir, s, 'SKILL.md'))) {
+                    out.add(s);
+                }
+            }
+        }
+    }
+    return [...out].sort();
+}
+
+function _isValidated(skillsDir: string, skill: string): boolean {
+    return fs.existsSync(path.join(skillsDir, skill, 'evals', 'domain-truth.json'));
+}
+
+export function computeStatus(o: StatusOptions = {}): SoundnessReport {
+    const skillsDir = _skillsDir(o);
+    const set = validationSet(o);
+    const validationSetStatus: SkillStatus[] = set.map((skill) => ({
+        skill,
+        status: _isValidated(skillsDir, skill) ? 'validated' : 'unvalidated',
+    }));
+    const validated = validationSetStatus.filter((s) => s.status === 'validated').length;
+    return {
+        validationSet: validationSetStatus,
+        validated,
+        unvalidated: validationSetStatus.length - validated,
+        total: validationSetStatus.length,
+    };
+}
+
+function _readFloor(floorPath: string): number {
+    try {
+        const raw = JSON.parse(fs.readFileSync(floorPath, 'utf-8')) as { validated?: number };
+        return raw.validated ?? 0;
+    } catch {
+        return 0;
+    }
+}
+
+export function writeFloor(o: StatusOptions = {}): SoundnessReport {
+    const report = computeStatus(o);
+    const p = _floorPath(o);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(
+        p,
+        JSON.stringify(
+            {
+                _comment:
+                    'Domain-soundness ratchet floor (road-to-domain-soundness Phase 3). ' +
+                    'domain_soundness_status --check fails if the validated count drops below this. ' +
+                    'Regenerate with --write-floor ONLY after a domain-truth fixture lands and passes.',
+                validated: report.validated,
+            },
+            null,
+            2,
+        ) + '\n',
+    );
+    return report;
+}
+
+export function checkRatchet(o: StatusOptions = {}): { ok: boolean; message: string } {
+    const report = computeStatus(o);
+    const floor = _readFloor(_floorPath(o));
+    if (report.validated < floor) {
+        return {
+            ok: false,
+            message: `validated domain skills ${report.validated} < floor ${floor}`,
+        };
+    }
+    return { ok: true, message: `validated ${report.validated}/${report.total} (floor ${floor})` };
+}
+
+function _renderHuman(r: SoundnessReport): string {
+    const lines = [
+        'Domain-soundness status — non-coding default-surface skills',
+        `  validated:   ${r.validated}/${r.total}`,
+        `  unvalidated: ${r.unvalidated}/${r.total}`,
+        '',
+    ];
+    for (const s of r.validationSet) {
+        const mark = s.status === 'validated' ? '✅' : '·';
+        lines.push(`  ${mark} ${s.skill.padEnd(28)} ${s.status}`);
+    }
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const known = new Set(['--json', '--check', '--write-floor']);
+    for (const a of argv) {
+        if (!known.has(a)) {
+            process.stderr.write('usage: domain_soundness_status [--json | --check | --write-floor]\n');
+            return 2;
+        }
+    }
+    if (argv.includes('--write-floor')) {
+        const r = writeFloor();
+        process.stdout.write(`✅  domain-soundness floor pinned: validated ${r.validated}/${r.total}\n`);
+        return 0;
+    }
+    if (argv.includes('--check')) {
+        const { ok, message } = checkRatchet();
+        if (!ok) {
+            process.stdout.write(`❌  domain-soundness ratchet regressed: ${message}\n`);
+            return 1;
+        }
+        process.stdout.write(`✅  domain-soundness ratchet: ${message}.\n`);
+        return 0;
+    }
+    const report = computeStatus();
+    if (argv.includes('--json')) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return 0;
+    }
+    process.stdout.write(_renderHuman(report) + '\n');
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/generate_index.ts

@@ -410,6 +410,20 @@ export function _render_catalog(
         '',
         `## Skills (${skills.length})`,
         '',
+        '> **Behavioural-eval coverage is measured, not implied.** A skill is',
+        '> behaviourally evaluated only if it ships `evals/evals.json`; most do',
+        '> not yet. Coverage is reported per tier (`./scripts-run',
+        '> src/scripts/skill_eval_coverage`) and CI-ratcheted so it can only rise.',
+        '> Listing here never implies a skill is behaviourally tested — the',
+        '> current coverage and its gap are published on [the proof page](proof.md).',
+        '',
+        '> **Non-coding domain correctness is scoped, not proven.** The',
+        '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
+        '> codebases; their embedded domain heuristics are labeled `unvalidated`',
+        '> until they pass a sourced `evals/domain-truth.json` fixture',
+        '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
+        '> floor bounds liability, not correctness — see [the proof page](proof.md).',
+        '',
         _render_table(skills, ['kind', 'name', 'extra', 'description'], '../', _to_shipped_path),
         '',
         `## Rules (${publicRules.length})`,

package/src/scripts/hot_context_hook.ts

@@ -30,6 +30,7 @@
 
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -309,6 +310,39 @@ export function restore_hot_context(
     return { action: 'inject', reason: `restored (source=${source || 'startup'})`, context: block };
 }
 
+// ---------------------------------------------------------------------
+// opt-in memory session index (road-to-memory-retrieval-economy P5)
+// ---------------------------------------------------------------------
+
+/**
+ * Build the compact memory index when `memory.session_index: on`; `null`
+ * on the default-off path, empty corpus, or any failure (never blocks).
+ * Memory roots are cwd-relative (same contract as the MCP tool handlers),
+ * so the build runs chdir-wrapped to the workspace root.
+ */
+function _session_index_block_or_null(root: string): string | null {
+    try {
+        // Lazy require (ESM-safe via createRequire) keeps the default-off
+        // fast path free of the memory_lookup + settings-cascade import cost.
+        const req = createRequire(import.meta.url);
+        const mod = req('./session_memory_index.js') as {
+            session_index_enabled: (root: string) => boolean;
+            build_session_index_block: () => string | null;
+        };
+        if (!mod.session_index_enabled(root)) return null;
+        const prev = process.cwd();
+        try {
+            process.chdir(root);
+            return mod.build_session_index_block();
+        } finally {
+            process.chdir(prev);
+        }
+    } catch (exc) {
+        process.stderr.write(`hot-context-hook: session index skipped: ${String(exc)}\n`);
+        return null;
+    }
+}
+
 // ---------------------------------------------------------------------
 // CLI — dispatcher concern entry point
 // ---------------------------------------------------------------------
@@ -351,12 +385,23 @@ export function main(): number {
         } else if (event === 'session_start') {
             const source = String(payload.source ?? '');
             const decision = restore_hot_context(root, source);
+            const blocks: string[] = [];
             if (decision.action === 'inject' && decision.context) {
+                blocks.push(decision.context);
+            }
+            // Opt-in compact memory index (road-to-memory-retrieval-economy
+            // P5) — default OFF; rides the same injection surface. Memory
+            // roots are cwd-relative, so resolve from the workspace root.
+            const indexBlock = _session_index_block_or_null(root);
+            if (indexBlock !== null) {
+                blocks.push(indexBlock);
+            }
+            if (blocks.length > 0) {
                 process.stdout.write(
                     JSON.stringify({
                         decision: 'allow',
-                        reason: decision.reason,
-                        context: decision.context,
+                        reason: decision.action === 'inject' ? decision.reason : 'memory session index',
+                        context: blocks.join('\n\n'),
                     }) + '\n',
                 );
             }

package/src/scripts/lint_behavioural_eval_freshness.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env tsx
+/**
+ * Lint behavioural-eval freshness — a behavioural `evals.json` that pins the
+ * skill body it was authored against must still match the current SKILL.md
+ * body, or it is flagged stale (road-to-skill-eval-coverage Phase 3).
+ *
+ * Sibling to `lint_eval_freshness.ts`, DIFFERENT axis: that gate keeps a
+ * corpus-backed skill's TRIGGER eval fresh against an upstream SHA; this gate
+ * keeps a skill's BEHAVIOURAL eval fresh against its own SKILL.md body. The
+ * two never conflate.
+ *
+ * A skill's `evals/evals.json` is in scope when it carries a `skill_body_sha`
+ * (SHA-256 of the SKILL.md body — post-frontmatter, trimmed — at authoring
+ * time). Absent = unpinned, OUT of scope (nothing to keep fresh), mirroring
+ * `lint_eval_freshness`'s `upstream: null` handling. So the currently-shipped
+ * evals (which carry no pin) never fail — the gate only bites once an author
+ * opts in by pinning.
+ *
+ * In scope, the gate fails when the pinned `skill_body_sha` differs from the
+ * current SKILL.md body sha: the body moved, so the eval may no longer
+ * exercise it — re-verify and re-pin (`--write-floor`-style human step) rather
+ * than let a stale eval pass silently.
+ *
+ * Deterministic, no token spend: reads on-disk files only. The live re-eval is
+ * a separate, spend-bearing step; this gate verifies the pin is current.
+ *
+ * Exit codes: 0 clean (or none in scope) / 1 at least one stale / 2 usage.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+let SKILLS_DIR = path.join(REPO, 'src', 'skills');
+
+export function _setSkillsDirForTest(p: string): void {
+    SKILLS_DIR = p;
+}
+
+type Json = string | number | boolean | null | Json[] | { [k: string]: Json };
+
+function _splitBody(text: string): string {
+    if (!text.startsWith('---\n')) return text.replace(/\s+$/, '');
+    const end = text.indexOf('\n---', 4);
+    if (end === -1) return text.replace(/\s+$/, '');
+    return text.slice(end + 4).replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+/** SHA-256 of a skill's SKILL.md body (post-frontmatter, trailing-ws-trimmed). */
+export function skillBodySha(skillMdText: string): string {
+    return crypto.createHash('sha256').update(_splitBody(skillMdText), 'utf-8').digest('hex');
+}
+
+export interface FreshnessResult {
+    ok: boolean;
+    stale: Array<{ skill: string; pinned: string; current: string }>;
+    inScope: number;
+}
+
+export function checkFreshness(): FreshnessResult {
+    const stale: FreshnessResult['stale'] = [];
+    let inScope = 0;
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    } catch {
+        return { ok: true, stale, inScope };
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const evalsPath = path.join(SKILLS_DIR, e.name, 'evals', 'evals.json');
+        const skillMd = path.join(SKILLS_DIR, e.name, 'SKILL.md');
+        if (!fs.existsSync(evalsPath) || !fs.existsSync(skillMd)) continue;
+        let spec: Json;
+        try {
+            spec = JSON.parse(fs.readFileSync(evalsPath, 'utf-8')) as Json;
+        } catch {
+            continue;
+        }
+        const pinned =
+            spec && typeof spec === 'object' && !Array.isArray(spec)
+                ? (spec['skill_body_sha'] as string | undefined)
+                : undefined;
+        if (typeof pinned !== 'string' || pinned === '') continue; // unpinned → out of scope
+        inScope += 1;
+        const current = skillBodySha(fs.readFileSync(skillMd, 'utf-8'));
+        if (current !== pinned) {
+            stale.push({ skill: e.name, pinned, current });
+        }
+    }
+    return { ok: stale.length === 0, stale, inScope };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let quiet = false;
+    for (const a of argv) {
+        if (a === '--quiet') quiet = true;
+        else {
+            process.stderr.write('usage: lint_behavioural_eval_freshness [--quiet]\n');
+            return 2;
+        }
+    }
+    const { ok, stale, inScope } = checkFreshness();
+    if (!ok) {
+        for (const s of stale) {
+            process.stderr.write(
+                `stale behavioural eval: ${s.skill}/evals/evals.json pinned ${s.pinned.slice(0, 12)}… ` +
+                    `but SKILL.md body is ${s.current.slice(0, 12)}… — re-verify and re-pin skill_body_sha\n`,
+            );
+        }
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(
+            `✅  behavioural-eval freshness: ${inScope} pinned eval(s) current (unpinned evals out of scope).\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -50,14 +50,18 @@
           "last": {"type": "integer", "description": "Return only the most recent N entries, after other filters apply.", "minimum": 1},
           "session": {"type": "string", "description": "Filter to a single 16-char session id."},
           "entry_type": {"type": "string", "description": "Filter by the `t` tag (e.g. note, decision, phase)."},
-          "path": {"type": "string", "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."}
+          "path": {"type": "string", "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."},
+          "around": {"type": "integer", "minimum": 0, "description": "Timeline anchor: return the entries around this ref (from a detail:\"index\" row) instead of the filtered list — depth_before/depth_after neighbours plus the anchor. Refs are within-file ordinals; rotation invalidates them."},
+          "depth_before": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours before the anchor (with `around`). Defaults to 3."},
+          "depth_after": {"type": "integer", "minimum": 0, "default": 3, "description": "Neighbours after the anchor (with `around`). Defaults to 3."},
+          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact rows (ref, t tag, ~100-char preview, tokens_estimate) instead of full entries — scan first, then re-read the refs you need via `around` or a narrowed filter. 'full' (default) returns complete entries."}
         },
         "additionalProperties": false
       }
     },
     {
       "name": "memory_lookup",
-      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
+      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. WORKFLOW: call with detail:\"index\" FIRST — each row carries id, title and tokens_estimate (the cost of fetching it) — then fetch full bodies via memory_get ONLY for the ids you will actually use, batching multiple ids into one call. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
       "side_effect": "ro",
       "implemented_on": ["stdio"],
       "input_schema": {
@@ -65,12 +69,27 @@
         "properties": {
           "types": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Memory types to scan, e.g. `historical-patterns`, `incident-learnings`, `ownership`. At least one required."},
           "keys": {"type": "array", "items": {"type": "string"}, "description": "Optional anchor paths or globs to match entries against (e.g. a file you are about to edit)."},
-          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."}
+          "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."},
+          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."}
         },
         "required": ["types"],
         "additionalProperties": false
       }
     },
+    {
+      "name": "memory_get",
+      "description": "Batch-fetch FULL memory entries by id — the second half of the index-first retrieval workflow. Call memory_lookup with detail:\"index\" first, pick the ids whose title/tokens_estimate justify the fetch, then fetch them here in ONE batched call. Unknown ids are reported per-id (ids[<id>]=\"unknown\"), never failing the batch. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "ids": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Entry ids to fetch (from a detail:\"index\" lookup)."}
+        },
+        "required": ["ids"],
+        "additionalProperties": false
+      }
+    },
     {
       "name": "memory_signal",
       "description": "Record an engineering-memory signal — a short, anchored observation such as a recurring bug pattern or an ownership note — to the monthly intake log `agents/memory/intake/signals-YYYY-MM.jsonl`. Use to capture a learning tied to a specific file so future `memory_lookup` calls surface it. Appends to the filesystem and is rate-limited per `(type, path)` within a rolling window. Returns the recorded signal.",