@event4u/agent-config 7.5.0 → 8.1.0

package/src/scripts/check_knowledge_sharing.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env tsx
+/**
+ * Team-sharing gate for `agents/knowledge/` — road-to-knowledge-system
+ * Phase 3. Pre-commit check: storage location IS the sharing policy (per
+ * the 2026-07-05 council verdict), so this gate exists to catch the two
+ * ways that policy can be violated by accident:
+ *
+ *   1. A gitignored intake file staged anyway (via `git add -f` or a
+ *      misconfigured .gitignore) — BLOCK. Intake is local scratch; it
+ *      must never reach a commit.
+ *   2. A page under `agents/knowledge/` carrying `visibility: private`
+ *      in its frontmatter — BLOCK. A private-scoped entry belongs in the
+ *      user-global store, never in the team-shared repo path (mirrors
+ *      the "link" reference's team-sync share-readiness gate).
+ *
+ * Creation budget (≥ 5 NEW files under `agents/knowledge/` in one
+ * commit) is a WARNING, not a block — large legitimate batches (e.g. a
+ * bootstrap run) should not be hard-refused, just flagged for a second
+ * look.
+ *
+ * Usage: check_knowledge_sharing.ts [--staged-files <path-list-file>]
+ * Without --staged-files, reads the real `git diff --cached` state.
+ *
+ * Exit codes: 0 = clean or warn-only, 1 = blocked, 3 = internal error.
+ */
+import { execFileSync } from 'node:child_process';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const PROG = 'check_knowledge_sharing.ts';
+const CREATION_BUDGET_WARN = 5;
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/;
+
+export interface StagedFile {
+    path: string;
+    status: 'A' | 'M' | 'D' | 'R' | string;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Parse `git diff --cached --name-status` output (also accepted pre-split for tests). */
+export function parseNameStatus(raw: string): StagedFile[] {
+    const out: StagedFile[] = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim()) continue;
+        const [status, ...rest] = line.split('\t');
+        const path = rest[rest.length - 1]; // renames carry old\tnew — keep the new path
+        const statusChar = status?.[0];
+        if (!statusChar || !path) continue;
+        out.push({ path, status: statusChar });
+    }
+    return out;
+}
+
+export interface SharingReport {
+    blocked: string[]; // human-readable block reasons
+    warnings: string[]; // human-readable warnings
+}
+
+/** Pure — takes staged files + a content-reader so tests never touch the real filesystem or git. */
+export function checkSharing(staged: StagedFile[], readContent: (path: string) => string | null): SharingReport {
+    const blocked: string[] = [];
+    const warnings: string[] = [];
+
+    const intakeFiles = staged.filter(
+        (f) => f.path.startsWith('agents/memory/intake/') || f.path.startsWith('agents/knowledge/intake/'),
+    );
+    for (const f of intakeFiles) {
+        blocked.push(`${f.path}: gitignored intake staged — intake is local scratch, never committed`);
+    }
+
+    const knowledgeFiles = staged.filter(
+        (f) => f.path.startsWith('agents/knowledge/') && !f.path.startsWith('agents/knowledge/intake/') && f.path.endsWith('.md'),
+    );
+    for (const f of knowledgeFiles) {
+        const content = readContent(f.path);
+        if (content === null) continue;
+        const match = FRONTMATTER_RE.exec(content);
+        if (match?.[1] === undefined) continue;
+        let fm: unknown;
+        try {
+            fm = YAML.parse(match[1]);
+        } catch {
+            continue;
+        }
+        if (isPlainObject(fm) && fm.visibility === 'private') {
+            blocked.push(`${f.path}: visibility: private — belongs in the user-global knowledge store, not the team-shared repo`);
+        }
+    }
+
+    const newKnowledgeFiles = staged.filter(
+        (f) => f.status === 'A' && f.path.startsWith('agents/knowledge/') && !f.path.startsWith('agents/knowledge/intake/'),
+    );
+    if (newKnowledgeFiles.length >= CREATION_BUDGET_WARN) {
+        warnings.push(
+            `${newKnowledgeFiles.length} new files under agents/knowledge/ in this commit — review the batch (creation budget: ${CREATION_BUDGET_WARN})`,
+        );
+    }
+
+    return { blocked, warnings };
+}
+
+function gitStagedNameStatus(): string {
+    return execFileSync('git', ['diff', '--cached', '--name-status'], { encoding: 'utf8' });
+}
+
+function gitStagedContent(path: string): string | null {
+    try {
+        return execFileSync('git', ['show', `:${path}`], { encoding: 'utf8' });
+    } catch {
+        return null;
+    }
+}
+
+function printUsage(): void {
+    process.stdout.write(`usage: ${PROG}\n`);
+}
+
+export function main(argv: string[]): number {
+    for (const arg of argv) {
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        }
+        process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+        printUsage();
+        return 1;
+    }
+
+    let staged: StagedFile[];
+    try {
+        staged = parseNameStatus(gitStagedNameStatus());
+    } catch (err) {
+        process.stderr.write(`${PROG}: error: git diff --cached failed: ${(err as Error).message}\n`);
+        return 3;
+    }
+
+    const { blocked, warnings } = checkSharing(staged, gitStagedContent);
+
+    for (const w of warnings) {
+        process.stdout.write(`🟡 ${w}\n`);
+    }
+
+    if (blocked.length > 0) {
+        for (const b of blocked) {
+            process.stderr.write(`❌ ${b}\n`);
+        }
+        process.stderr.write(`${PROG}: commit blocked — ${blocked.length} sharing violation(s).\n`);
+        return 1;
+    }
+
+    process.stdout.write(`${PROG}: sharing gate clear.\n`);
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_media_deps.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Detect-and-instruct check for the optional **media tooling** (B8 recorded
+ * proof-page demos): `asciinema` (records a terminal session to a `.cast`) and
+ * `agg` (converts a `.cast` → animated GIF).
+ *
+ * Per the `missing-tool-handling` rule the package NEVER installs a system
+ * binary silently — it detects, prints the exact platform install command, and
+ * exits non-zero (the same shape as the docker check in taskfiles/mcp.yml). So
+ * every maintainer gets a consistent on-demand prompt; nobody gets a surprise
+ * install. Called as the prereq of any B8 recording task.
+ *
+ * Exit 0 = all present · 1 = at least one missing (prints install hints).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_media_deps
+ *   ./scripts-run src/scripts/check_media_deps --quiet   # print only on failure
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _FILE = fileURLToPath(import.meta.url);
+
+export interface MediaTool {
+    bin: string;
+    purpose: string;
+    install: { darwin: string; linux: string; other: string };
+}
+
+export const MEDIA_TOOLS: MediaTool[] = [
+    {
+        bin: 'asciinema',
+        purpose: 'record a terminal session to a .cast (B8 proof-page demos)',
+        install: {
+            darwin: 'brew install asciinema',
+            linux: 'pipx install asciinema   # or your distro package manager',
+            other: 'see the asciinema install docs for your platform',
+        },
+    },
+    {
+        bin: 'agg',
+        purpose: 'convert a .cast → animated GIF (asciinema gif generator)',
+        install: {
+            darwin: 'brew install agg',
+            linux: 'cargo install --locked agg   # or grab a release binary',
+            other: 'see the agg install docs for your platform',
+        },
+    },
+];
+
+/** True when `bin` is runnable on PATH (probed with `--version`). */
+export function isPresent(bin: string): boolean {
+    const r = spawnSync(bin, ['--version'], { stdio: 'ignore' });
+    // ENOENT → not on PATH. A non-zero exit with no spawn error still means the
+    // binary exists (some tools return non-zero for --version), so key off error.
+    return !r.error;
+}
+
+export function installHint(tool: MediaTool, platform: NodeJS.Platform = process.platform): string {
+    if (platform === 'darwin') return tool.install.darwin;
+    if (platform === 'linux') return tool.install.linux;
+    return tool.install.other;
+}
+
+/** Return the subset of `tools` that are not installed. */
+export function missingTools(tools: MediaTool[] = MEDIA_TOOLS): MediaTool[] {
+    return tools.filter((t) => !isPresent(t.bin));
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const quiet = argv.includes('--quiet');
+    const missing = missingTools();
+    if (missing.length === 0) {
+        if (!quiet) {
+            process.stdout.write(`✅  media tooling: ${MEDIA_TOOLS.map((t) => t.bin).join(' + ')} present.\n`);
+        }
+        return 0;
+    }
+    process.stderr.write(`❌  media tooling missing (${missing.map((t) => t.bin).join(', ')}) — required for B8 recorded demos.\n`);
+    process.stderr.write('   The package never installs system binaries for you (missing-tool-handling). Install on demand:\n\n');
+    for (const t of missing) {
+        process.stderr.write(`   ${t.bin} — ${t.purpose}\n     ${installHint(t)}\n`);
+    }
+    process.stderr.write('\n   Then re-run this check.\n');
+    return 1;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());

package/src/scripts/check_memory_contradiction.ts

@@ -0,0 +1,280 @@
+#!/usr/bin/env tsx
+/**
+ * Contradiction surfacing for `/memory promote` — road-to-second-brain
+ * Phase 2 (council 2026-07-07, verdict:
+ * `agents/settings/contexts/second-brain-delta-verdict.md`).
+ *
+ * Mechanical detector, deliberately NOT NLI: a candidate entry that shares a
+ * PRIMARY KEY with an existing curated entry of the same durable type but has
+ * LOW body similarity (Jaccard < 0.3) is a potential contradiction — same
+ * topic, different claim. High similarity on the same key is a rewording /
+ * extension (dedup territory, handled by `check_memory_similarity.ts`);
+ * different keys are different topics.
+ *
+ * Scoped to the behaviorally load-bearing durable types only
+ * (`incident-learnings`, `product-rules`, `domain-invariants` by default) —
+ * exploratory types evolve legitimately and are never checked.
+ *
+ * The detector SURFACES; it never resolves. Resolution goes through the
+ * existing contested flow in `/memory promote` (approve new + mark old
+ * `contested` with provenance, or revise the new entry). Auto-resolution is
+ * on the council REJECT list.
+ *
+ * Usage:
+ *   check_memory_contradiction.ts --type <type> --key <primary-key> \
+ *       --body "<text>" [--memory-root <dir>] [--durable-types a,b,c] [--format text|json]
+ *
+ * Exit codes: 0 = no contradiction (or type not durable — silent no-op),
+ * 1 = potential contradiction found (surface the pair, ask the human),
+ * 2 = usage error, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+import { jaccardSimilarity } from './_lib/text_similarity.js';
+
+const PROG = 'check_memory_contradiction.ts';
+
+export const CONTRADICTION_THRESHOLD = 0.3;
+export const DEFAULT_DURABLE_TYPES = new Set([
+    'incident-learnings',
+    'product-rules',
+    'domain-invariants',
+]);
+
+// Fields whose values carry the entry's CLAIM (compared via Jaccard).
+const BODY_FIELDS = ['rule', 'symptom', 'body', 'description', 'text', 'summary'] as const;
+// Fields that can serve as the entry's primary key, in precedence order.
+const KEY_FIELDS = ['key', 'id'] as const;
+
+export interface CuratedEntry {
+    file: string;
+    key: string;
+    body: string;
+}
+
+export interface ContradictionHit {
+    existing: CuratedEntry;
+    key: string;
+    similarity: number;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function entryKey(entry: Record<string, unknown>): string {
+    for (const f of KEY_FIELDS) {
+        const v = entry[f];
+        if (typeof v === 'string' && v.trim()) {
+            return v.trim().toLowerCase();
+        }
+    }
+    return '';
+}
+
+function entryBody(entry: Record<string, unknown>): string {
+    const parts: string[] = [];
+    for (const f of BODY_FIELDS) {
+        const v = entry[f];
+        if (typeof v === 'string' && v.trim()) {
+            parts.push(v.trim());
+        }
+    }
+    return parts.join('\n');
+}
+
+function parseYamlDocs(file: string): Array<Record<string, unknown>> {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: Array<Record<string, unknown>> = [];
+    let parsed: unknown;
+    try {
+        parsed = YAML.parse(text);
+    } catch {
+        return [];
+    }
+    if (Array.isArray(parsed)) {
+        for (const item of parsed) {
+            if (isPlainObject(item)) out.push(item);
+        }
+    } else if (isPlainObject(parsed)) {
+        // single-entry file (content-addressed layout) OR legacy
+        // `{entries: [...]}` shape.
+        const entries = parsed['entries'];
+        if (Array.isArray(entries)) {
+            for (const item of entries) {
+                if (isPlainObject(item)) out.push(item);
+            }
+        } else {
+            out.push(parsed);
+        }
+    }
+    return out;
+}
+
+/** Load curated entries of one type — content-addressed dir + legacy single file. */
+export function loadCuratedEntries(memoryRoot: string, type: string): CuratedEntry[] {
+    const out: CuratedEntry[] = [];
+    const shardDir = path.join(memoryRoot, type);
+    let shardFiles: string[] = [];
+    try {
+        shardFiles = fs
+            .readdirSync(shardDir)
+            .filter((n) => n.endsWith('.yml') || n.endsWith('.yaml'))
+            .sort()
+            .map((n) => path.join(shardDir, n));
+    } catch {
+        // no shard dir — fine
+    }
+    const legacy = path.join(memoryRoot, `${type}.yml`);
+    const files = fs.existsSync(legacy) ? [...shardFiles, legacy] : shardFiles;
+    for (const file of files) {
+        for (const entry of parseYamlDocs(file)) {
+            const key = entryKey(entry);
+            const body = entryBody(entry);
+            if (key && body) {
+                out.push({ file, key, body });
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Same primary key + Jaccard body similarity below the threshold →
+ * potential contradiction. Returns at most ONE hit (the lowest-similarity
+ * same-key entry) — one surfaced pair per promote is enough.
+ */
+export function findContradiction(
+    candidateKey: string,
+    candidateBody: string,
+    existing: CuratedEntry[],
+): ContradictionHit | null {
+    const key = candidateKey.trim().toLowerCase();
+    if (!key || !candidateBody.trim()) return null;
+    let worst: ContradictionHit | null = null;
+    for (const entry of existing) {
+        if (entry.key !== key) continue;
+        const similarity = jaccardSimilarity(candidateBody, entry.body);
+        if (similarity < CONTRADICTION_THRESHOLD) {
+            if (worst === null || similarity < worst.similarity) {
+                worst = { existing: entry, key, similarity };
+            }
+        }
+    }
+    return worst;
+}
+
+function main(argv: string[]): number {
+    let type = '';
+    let key = '';
+    let body = '';
+    let memoryRoot = path.join('agents', 'memory');
+    let durableTypes = DEFAULT_DURABLE_TYPES;
+    let format = 'text';
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = (): string => {
+            const v = argv[++i];
+            if (v === undefined) {
+                process.stderr.write(`${PROG}: error: ${a} requires a value\n`);
+                process.exit(2);
+            }
+            return v;
+        };
+        if (a === '--type') type = next();
+        else if (a === '--key') key = next();
+        else if (a === '--body') body = next();
+        else if (a === '--memory-root') memoryRoot = next();
+        else if (a === '--durable-types')
+            durableTypes = new Set(
+                next()
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter(Boolean),
+            );
+        else if (a === '--format') {
+            format = next();
+            if (format !== 'text' && format !== 'json') {
+                process.stderr.write(`${PROG}: error: --format must be text|json\n`);
+                return 2;
+            }
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                `usage: ${PROG} --type <type> --key <primary-key> --body <text> ` +
+                    `[--memory-root <dir>] [--durable-types a,b,c] [--format text|json]\n`,
+            );
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+
+    if (!type || !key || !body) {
+        process.stderr.write(`${PROG}: error: --type, --key and --body are required\n`);
+        return 2;
+    }
+
+    if (!durableTypes.has(type)) {
+        if (format === 'json') {
+            process.stdout.write(JSON.stringify({ checked: false, reason: 'type-not-durable' }) + '\n');
+        }
+        return 0; // exploratory types are never contradiction-checked
+    }
+
+    let hit: ContradictionHit | null;
+    try {
+        hit = findContradiction(key, body, loadCuratedEntries(path.resolve(memoryRoot), type));
+    } catch (exc) {
+        process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+
+    if (!hit) {
+        if (format === 'json') {
+            process.stdout.write(JSON.stringify({ checked: true, contradiction: null }) + '\n');
+        }
+        return 0;
+    }
+
+    if (format === 'json') {
+        process.stdout.write(
+            JSON.stringify(
+                {
+                    checked: true,
+                    contradiction: {
+                        key: hit.key,
+                        similarity: Number(hit.similarity.toFixed(4)),
+                        threshold: CONTRADICTION_THRESHOLD,
+                        existing_file: hit.existing.file,
+                    },
+                },
+                null,
+                2,
+            ) + '\n',
+        );
+    } else {
+        process.stdout.write(
+            `⚠️  potential contradiction on key '${hit.key}' (similarity ` +
+                `${hit.similarity.toFixed(2)} < ${CONTRADICTION_THRESHOLD}):\n` +
+                `    existing: ${hit.existing.file}\n` +
+                `    Resolve via the contested flow — approve new + mark old ` +
+                `'contested' (with provenance), or revise the new entry. NEVER auto-resolve.\n`,
+        );
+    }
+    return 1;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_memory_similarity.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env tsx
+/**
+ * Advisory near-duplicate check for `/memory propose` — road-to-knowledge-system
+ * Phase 2 (capture hygiene). Scans existing intake signals of the SAME type
+ * for the closest Jaccard match to a candidate body and classifies it.
+ *
+ * This is an ADDITIONAL, non-destructive check layered in front of
+ * `memory_signal.ts` — it never writes, and it never changes that script's
+ * own exact-match rate-limit behaviour (a documented, load-bearing parity
+ * contract). The `/memory propose` command runs this first; on `merge` it
+ * surfaces the matched entry and asks the human before emitting anyway.
+ *
+ * Usage:
+ *   check_memory_similarity.ts --type <type> --body "<text>" [--intake-root <dir>]
+ *
+ * Exit codes: 0 = create or warn (proceed, optionally after surfacing the
+ * near match), 1 = merge threshold hit (surface the match, ask before
+ * emitting), 2 = usage error, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { findMostSimilar, type Candidate } from './_lib/text_similarity.js';
+
+const PROG = 'check_memory_similarity.ts';
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Sorted signals-*.jsonl file paths under root — mirrors memory_signal.ts's own glob order. */
+function globSignals(root: string): string[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(root);
+    } catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.startsWith('signals-') && n.endsWith('.jsonl'))
+        .sort()
+        .map((n) => path.join(root, n));
+}
+
+export function loadCandidates(intakeRoot: string, entryType: string): Candidate[] {
+    const out: Candidate[] = [];
+    for (const file of globSignals(intakeRoot)) {
+        let text: string;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        } catch {
+            continue;
+        }
+        for (const rawLine of text.split('\n')) {
+            const line = rawLine.trim();
+            if (!line) continue;
+            let obj: unknown;
+            try {
+                obj = JSON.parse(line);
+            } catch {
+                continue;
+            }
+            if (!isPlainObject(obj)) continue;
+            if (obj.entry_type !== entryType) continue;
+            const id = typeof obj.id === 'string' ? obj.id : '';
+            const body = typeof obj.body === 'string' ? obj.body : '';
+            if (!id || !body) continue;
+            out.push({ id, text: body });
+        }
+    }
+    return out;
+}
+
+function printUsage(): void {
+    process.stderr.write(`usage: ${PROG} --type TYPE --body BODY [--intake-root DIR]\n`);
+}
+
+export function main(argv: string[]): number {
+    let type: string | null = null;
+    let body: string | null = null;
+    let intakeRoot = path.join('agents', 'memory', 'intake');
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--type') {
+            type = argv[++i] ?? null;
+        } else if (arg === '--body') {
+            body = argv[++i] ?? null;
+        } else if (arg === '--intake-root') {
+            intakeRoot = argv[++i] ?? intakeRoot;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 2;
+        }
+    }
+
+    if (!type || !body) {
+        process.stderr.write(`${PROG}: error: --type and --body are required\n`);
+        printUsage();
+        return 2;
+    }
+
+    const candidates = loadCandidates(intakeRoot, type);
+    const match = findMostSimilar(body, candidates);
+
+    if (!match || match.classification === 'create') {
+        process.stdout.write(`${PROG}: no near-duplicate found — proceed to create.\n`);
+        return 0;
+    }
+
+    const scorePct = (match.score * 100).toFixed(0);
+    if (match.classification === 'warn') {
+        process.stdout.write(
+            `${PROG}: nearest match ${match.id} (${scorePct}% similar) — review before proceeding, then create if distinct.\n`,
+        );
+        return 0;
+    }
+
+    // classification === 'merge'
+    process.stdout.write(
+        `${PROG}: likely duplicate of ${match.id} (${scorePct}% similar) — reuse or update that entry instead of creating a new one. Emit anyway only if this is a genuinely distinct finding.\n`,
+    );
+    return 1;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}