@njeybe/nativ 2.3.1 → 2.4.0

package/dist/core/session-memory.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function getSessionMemoryDir(targetDir) {
+    return path.join(targetDir, '.ai', 'memory', 'sessions');
+}
+export function getSessionIndexPath(targetDir) {
+    return path.join(getSessionMemoryDir(targetDir), 'index.json');
+}
+export function getLatestSessionPath(targetDir) {
+    return path.join(getSessionMemoryDir(targetDir), 'latest.json');
+}
+export function loadSessionIndex(targetDir) {
+    const indexPath = getSessionIndexPath(targetDir);
+    if (!fs.existsSync(indexPath)) {
+        return {
+            version: '1.0.0',
+            updatedAt: new Date().toISOString(),
+            sessions: [],
+        };
+    }
+    try {
+        const raw = fs.readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.sessions)) {
+            return {
+                version: '1.0.0',
+                updatedAt: new Date().toISOString(),
+                sessions: [],
+            };
+        }
+        return parsed;
+    }
+    catch {
+        return {
+            version: '1.0.0',
+            updatedAt: new Date().toISOString(),
+            sessions: [],
+        };
+    }
+}
+export function saveSessionIndex(targetDir, index) {
+    const dir = getSessionMemoryDir(targetDir);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    index.updatedAt = new Date().toISOString();
+    fs.writeFileSync(getSessionIndexPath(targetDir), JSON.stringify(index, null, 2), 'utf8');
+}
+export function saveSessionCheckpoint(targetDir, input) {
+    const dir = getSessionMemoryDir(targetDir);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const now = new Date();
+    const dateStr = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    const sessionId = input.sessionId || `sess-${dateStr}`;
+    const checkpoint = {
+        sessionId,
+        timestamp: now.toISOString(),
+        ...(input.role ? { role: input.role.trim() } : {}),
+        ...(input.taskId ? { taskId: input.taskId.trim() } : {}),
+        summary: input.summary.trim(),
+        ...(input.decisions && input.decisions.length > 0 ? { decisions: input.decisions.map((d) => d.trim()) } : {}),
+        ...(input.obstacles && input.obstacles.length > 0 ? { obstacles: input.obstacles.map((o) => o.trim()) } : {}),
+        ...(input.nextSteps && input.nextSteps.length > 0 ? { nextSteps: input.nextSteps.map((n) => n.trim()) } : {}),
+        ...(input.activeFiles && input.activeFiles.length > 0 ? { activeFiles: input.activeFiles.map((f) => f.trim()) } : {}),
+    };
+    // Write individual session file
+    const sessionPath = path.join(dir, `${sessionId}.json`);
+    fs.writeFileSync(sessionPath, JSON.stringify(checkpoint, null, 2), 'utf8');
+    // Write latest.json
+    fs.writeFileSync(getLatestSessionPath(targetDir), JSON.stringify(checkpoint, null, 2), 'utf8');
+    // Update index
+    const index = loadSessionIndex(targetDir);
+    index.latestSessionId = sessionId;
+    // Remove existing entry with same sessionId if updating
+    index.sessions = index.sessions.filter((s) => s.sessionId !== sessionId);
+    index.sessions.unshift({
+        sessionId,
+        timestamp: checkpoint.timestamp,
+        role: checkpoint.role,
+        taskId: checkpoint.taskId,
+        summary: checkpoint.summary,
+    });
+    // Keep index trimmed to 50 most recent sessions
+    if (index.sessions.length > 50) {
+        index.sessions = index.sessions.slice(0, 50);
+    }
+    saveSessionIndex(targetDir, index);
+    return checkpoint;
+}
+export function getLatestSession(targetDir) {
+    const latestPath = getLatestSessionPath(targetDir);
+    if (!fs.existsSync(latestPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(latestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function getSession(targetDir, sessionId) {
+    const sessionPath = path.join(getSessionMemoryDir(targetDir), `${sessionId}.json`);
+    if (!fs.existsSync(sessionPath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(sessionPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function listSessions(targetDir, limit = 10) {
+    const index = loadSessionIndex(targetDir);
+    return index.sessions.slice(0, limit);
+}

package/dist/core/setup-assets.d.ts

@@ -7,7 +7,7 @@
  */
 import { type EnforcementMode } from './enforcement.js';
 export declare const MCP_SERVER_NAME = "nativ";
-export declare const AGENT_FILES: readonly ["architect.md", "worker.md", "verifier.md"];
+export declare const AGENT_FILES: readonly ["architect.md", "worker.md", "verifier.md", "explorer.md"];
 export type AssetAction = 'created' | 'updated' | 'unchanged' | 'skipped';
 export interface AssetChange {
     /** Path relative to the project root, forward slashes. */

package/dist/core/setup-assets.js

@@ -15,7 +15,7 @@ import { resolveProjectRoot } from './root-resolver.js';
 import { isLegacyTemplate, normalizeForHash } from './legacy-templates.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const MCP_SERVER_NAME = 'nativ';
-export const AGENT_FILES = ['architect.md', 'worker.md', 'verifier.md'];
+export const AGENT_FILES = ['architect.md', 'worker.md', 'verifier.md', 'explorer.md'];
 const MANAGED_PREFIX = '<!-- nativ:managed sha256=';
 const MANAGED_PATTERN = /\n?<!-- nativ:managed sha256=([0-9a-f]{12}) -->\s*$/;
 const PRE_TOOL_USE_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit';
@@ -60,6 +60,7 @@ const SECRET_READ_DENY = [
     'Read(./.env.production.local)',
     'Read(./**/*.pem)',
     'Read(./**/*.key)',
+    'Read(./.nativ/*.local.json)',
 ];
 export function buildDesiredConfig(invocation) {
     const cli = cliString(invocation);
@@ -72,6 +73,8 @@ export function buildDesiredConfig(invocation) {
         deny: [
             ...prefixes.flatMap((p) => [
                 `Bash(${p} task unlock *)`,
+                `Bash(${p} learn approve *)`,
+                `Bash(${p} learn reject *)`,
                 `Bash(${p} db sync *)`,
                 `Bash(${p} task complete * --no-verify)`,
                 `Bash(${p} task complete * --no-verify *)`,
@@ -79,7 +82,7 @@ export function buildDesiredConfig(invocation) {
             ...SECRET_READ_DENY,
         ],
         // Contract edits always need a human's yes, whichever agent asks.
-        ask: ['Edit(./.ai/**)', 'Write(./.ai/**)'],
+        ask: ['Edit(./.ai/**)', 'Write(./.ai/**)', 'Edit(./.nativ/**)', 'Write(./.nativ/**)'],
         preToolUse: { matcher: PRE_TOOL_USE_MATCHER, command: `${cli} hook check`, timeout: HOOK_TIMEOUT_SECONDS },
         sessionStart: { matcher: SESSION_START_MATCHER, command: `${cli} hook context`, timeout: HOOK_TIMEOUT_SECONDS },
     };

package/dist/core/verifier.d.ts

@@ -10,6 +10,14 @@ export interface VerificationResult {
     error?: string;
     skipped?: boolean;
     codeShape?: CodeShapeReport;
+    /** Results of the configured `verifyPhases`, when any ran. */
+    phases?: PhaseResult[];
+}
+export interface PhaseResult {
+    name: string;
+    command: string;
+    success: boolean;
+    durationMs: number;
 }
 export interface TaskVerificationResult {
     taskId: string;
@@ -42,6 +50,34 @@ export declare function executeVerification(command: string, cwd: string, timeou
  * In 'warn' mode (default) the result is untouched; in 'block' mode issues fail it with a reason.
  */
 export declare function applyCodeShape(result: VerificationResult, targetDir: string, task: MasterPlanTask): VerificationResult;
+export interface VerifyPhase {
+    name: string;
+    run: string;
+}
+/** Configured phases, or an error when the config exists but cannot be trusted to say what they are. */
+export interface VerifyPhasesConfig {
+    phases: VerifyPhase[];
+    error?: string;
+}
+/** `verifyPhases` from the main checkout's `.nativ/config.json`, never from a worktree's own copy. */
+export declare function loadVerifyPhases(configDir: string): VerifyPhasesConfig;
+/** Outcome of running the configured phases once; shared by every task in a batch. */
+export interface PhasesOutcome {
+    reports: PhaseResult[];
+    failure?: VerificationResult;
+}
+/** Runs the configured phases in order and stops at the first failure. */
+export declare function runVerifyPhases(cwd: string, configDir: string, timeout?: number): Promise<PhasesOutcome>;
+/**
+ * The one verification every path shares: the configured phases in order, stopping at the
+ * first failure, then the task's own command, then the code-shape check.
+ */
+export declare function runTaskVerification(task: MasterPlanTask, options: {
+    cwd: string;
+    configDir?: string;
+    timeout?: number;
+    phases?: PhasesOutcome;
+}): Promise<VerificationResult>;
 /**
  * Run verification for a single specific task in the plan.
  */

package/dist/core/verifier.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { exec } from 'node:child_process';
 import { checkCodeShape, formatCodeShapeReport } from './code-shape.js';
+import { parseJsonLoose } from './enforcement.js';
+import { resolveMainRoot } from './root-resolver.js';
 export function loadMasterPlan(targetDir) {
     const planPath = path.join(targetDir, '.ai', 'master_plan.json');
     if (!fs.existsSync(planPath)) {
@@ -98,6 +100,91 @@ export function applyCodeShape(result, targetDir, task) {
     }
     return result;
 }
+/** Reads the file, retrying once: antivirus or an editor saving can briefly lock it on Windows. */
+function readConfigText(file) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return fs.readFileSync(file, 'utf8');
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            if (attempt >= 1)
+                throw err;
+        }
+    }
+}
+/** `verifyPhases` from the main checkout's `.nativ/config.json`, never from a worktree's own copy. */
+export function loadVerifyPhases(configDir) {
+    let raw;
+    try {
+        raw = readConfigText(path.join(resolveMainRoot(configDir), '.nativ', 'config.json'));
+    }
+    catch (err) {
+        return { phases: [], error: `.nativ/config.json cannot be read (${err?.message})` };
+    }
+    if (raw === null)
+        return { phases: [] };
+    if (!raw.trim())
+        return { phases: [], error: '.nativ/config.json is empty' };
+    let phases;
+    try {
+        phases = parseJsonLoose(raw)?.verifyPhases;
+    }
+    catch (err) {
+        return { phases: [], error: `.nativ/config.json is not valid JSON (${err?.message})` };
+    }
+    if (phases === undefined || phases === null)
+        return { phases: [] };
+    // An empty or null "run" switches a phase off; a missing or mistyped field is a mistake.
+    const isEntry = (p) => typeof p?.name === 'string' && p.name.trim()
+        && (p.run === null || typeof p.run === 'string');
+    if (!Array.isArray(phases) || !phases.every(isEntry)) {
+        return { phases: [], error: 'verifyPhases must be a list of { "name": "...", "run": "..." } entries' };
+    }
+    const active = phases.filter((p) => p.run && p.run.trim());
+    return { phases: active.map((p) => ({ name: p.name.trim(), run: p.run.trim() })) };
+}
+function configFailure(message) {
+    const error = `${message}, so the configured checks could not run. Fix it and verify again.`;
+    const command = '.nativ/config.json';
+    return { success: false, exitCode: 1, command, stdout: '', stderr: error, durationMs: 0, error };
+}
+/** Runs the configured phases in order and stops at the first failure. */
+export async function runVerifyPhases(cwd, configDir, timeout) {
+    const config = loadVerifyPhases(configDir);
+    if (config.error)
+        return { reports: [], failure: configFailure(config.error) };
+    const reports = [];
+    for (const phase of config.phases) {
+        const res = await executeVerification(phase.run, cwd, timeout);
+        reports.push({ name: phase.name, command: res.command, success: res.success, durationMs: res.durationMs });
+        if (!res.success) {
+            const cause = res.error ? `: ${res.error.trim()}` : '';
+            return { reports, failure: { ...res, phases: reports, error: `Phase "${phase.name}" failed${cause}` } };
+        }
+    }
+    return { reports };
+}
+/**
+ * The one verification every path shares: the configured phases in order, stopping at the
+ * first failure, then the task's own command, then the code-shape check.
+ */
+export async function runTaskVerification(task, options) {
+    const configDir = options.configDir ?? options.cwd;
+    const outcome = options.phases ?? (await runVerifyPhases(options.cwd, configDir, options.timeout));
+    // In a batch the shared phase time is counted once, by the batch, not again for every task.
+    if (outcome.failure) {
+        return { ...outcome.failure, phases: outcome.reports, ...(options.phases ? { durationMs: 0 } : {}) };
+    }
+    const raw = await executeVerification(task.verificationCommand, options.cwd, options.timeout);
+    if (outcome.reports.length) {
+        raw.phases = outcome.reports;
+        raw.durationMs += options.phases ? 0 : outcome.reports.reduce((sum, r) => sum + r.durationMs, 0);
+        raw.skipped = false;
+    }
+    return applyCodeShape(raw, options.cwd, task);
+}
 /**
  * Run verification for a single specific task in the plan.
  */
@@ -150,8 +237,7 @@ export async function verifyTask(taskId, targetDirArg, options = {}) {
             },
         };
     }
-    const raw = await executeVerification(foundTask.verificationCommand, targetDir, options.timeout);
-    const result = applyCodeShape(raw, targetDir, foundTask);
+    const result = await runTaskVerification(foundTask, { cwd: targetDir, timeout: options.timeout });
     return {
         taskId: foundTask.id,
         title: foundTask.title,
@@ -239,9 +325,11 @@ export async function verifyBatch(targetDirArg, options = {}) {
     let failed = 0;
     let skipped = 0;
     let totalDuration = 0;
+    // The phases check the whole project, so one run serves every task in the batch.
+    const phases = candidates.length ? await runVerifyPhases(targetDir, targetDir, options.timeout) : { reports: [] };
+    totalDuration += phases.reports.reduce((sum, r) => sum + r.durationMs, 0);
     for (const { task, milestone } of candidates) {
-        const raw = await executeVerification(task.verificationCommand, targetDir, options.timeout);
-        const vResult = applyCodeShape(raw, targetDir, task);
+        const vResult = await runTaskVerification(task, { cwd: targetDir, timeout: options.timeout, phases });
         totalDuration += vResult.durationMs;
         if (vResult.skipped) {
             skipped++;

package/dist/db/introspector.js

@@ -81,30 +81,30 @@ async function createPostgresDriver(url) {
         },
         async tables() {
             const builder = new TableBuilder();
-            const tables = await client.query(`
-        SELECT t.table_name, obj_description(format('%I.%I', t.table_schema, t.table_name)::regclass, 'pg_class') AS description
-        FROM information_schema.tables t
-        WHERE t.table_schema = current_schema() AND t.table_type = 'BASE TABLE'
+            const tables = await client.query(`
+        SELECT t.table_name, obj_description(format('%I.%I', t.table_schema, t.table_name)::regclass, 'pg_class') AS description
+        FROM information_schema.tables t
+        WHERE t.table_schema = current_schema() AND t.table_type = 'BASE TABLE'
         ORDER BY t.table_name`);
             for (const row of tables.rows) {
                 const table = builder.get(row.table_name);
                 if (row.description)
                     table.description = row.description;
             }
-            const pks = await client.query(`
-        SELECT kcu.table_name, kcu.column_name
-        FROM information_schema.table_constraints tc
-        JOIN information_schema.key_column_usage kcu
-          ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema AND kcu.table_name = tc.table_name
+            const pks = await client.query(`
+        SELECT kcu.table_name, kcu.column_name
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema AND kcu.table_name = tc.table_name
         WHERE tc.table_schema = current_schema() AND tc.constraint_type = 'PRIMARY KEY'`);
             const pkSet = new Set(pks.rows.map((r) => `${r.table_name}.${r.column_name}`));
-            const columns = await client.query(`
-        SELECT c.table_name, c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
-               c.numeric_precision, c.numeric_scale, c.is_nullable, c.column_default
-        FROM information_schema.columns c
-        JOIN information_schema.tables t
-          ON t.table_schema = c.table_schema AND t.table_name = c.table_name AND t.table_type = 'BASE TABLE'
-        WHERE c.table_schema = current_schema()
+            const columns = await client.query(`
+        SELECT c.table_name, c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
+               c.numeric_precision, c.numeric_scale, c.is_nullable, c.column_default
+        FROM information_schema.columns c
+        JOIN information_schema.tables t
+          ON t.table_schema = c.table_schema AND t.table_name = c.table_name AND t.table_type = 'BASE TABLE'
+        WHERE c.table_schema = current_schema()
         ORDER BY c.table_name, c.ordinal_position`);
             for (const row of columns.rows) {
                 builder.get(row.table_name).columns.push({
@@ -116,31 +116,31 @@ async function createPostgresDriver(url) {
                 });
             }
             // information_schema has no index view — pg_catalog is the only source.
-            const indexes = await client.query(`
-        SELECT t.relname AS table_name, i.relname AS index_name, ix.indisunique AS is_unique,
-               (SELECT array_agg(a.attname::text ORDER BY k.ord)
-                  FROM unnest(ix.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
-                  JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum) AS columns
-        FROM pg_index ix
-        JOIN pg_class t ON t.oid = ix.indrelid
-        JOIN pg_class i ON i.oid = ix.indexrelid
-        JOIN pg_namespace n ON n.oid = t.relnamespace
-        WHERE n.nspname = current_schema() AND NOT ix.indisprimary AND t.relkind IN ('r', 'p')
+            const indexes = await client.query(`
+        SELECT t.relname AS table_name, i.relname AS index_name, ix.indisunique AS is_unique,
+               (SELECT array_agg(a.attname::text ORDER BY k.ord)
+                  FROM unnest(ix.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+                  JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum) AS columns
+        FROM pg_index ix
+        JOIN pg_class t ON t.oid = ix.indrelid
+        JOIN pg_class i ON i.oid = ix.indexrelid
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        WHERE n.nspname = current_schema() AND NOT ix.indisprimary AND t.relkind IN ('r', 'p')
         ORDER BY t.relname, i.relname`);
             for (const row of indexes.rows) {
                 builder.get(row.table_name).indexes.push({ name: row.index_name, columns: row.columns ?? [], unique: row.is_unique });
             }
-            const fks = await client.query(`
-        SELECT con.conname AS constraint_name, cl.relname AS table_name, a.attname AS column_name,
-               fcl.relname AS ref_table, fa.attname AS ref_column, con.confdeltype AS on_delete
-        FROM pg_constraint con
-        JOIN pg_class cl ON cl.oid = con.conrelid
-        JOIN pg_namespace n ON n.oid = cl.relnamespace
-        JOIN pg_class fcl ON fcl.oid = con.confrelid
-        CROSS JOIN LATERAL unnest(con.conkey, con.confkey) AS k(attnum, fattnum)
-        JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum
-        JOIN pg_attribute fa ON fa.attrelid = con.confrelid AND fa.attnum = k.fattnum
-        WHERE n.nspname = current_schema() AND con.contype = 'f'
+            const fks = await client.query(`
+        SELECT con.conname AS constraint_name, cl.relname AS table_name, a.attname AS column_name,
+               fcl.relname AS ref_table, fa.attname AS ref_column, con.confdeltype AS on_delete
+        FROM pg_constraint con
+        JOIN pg_class cl ON cl.oid = con.conrelid
+        JOIN pg_namespace n ON n.oid = cl.relnamespace
+        JOIN pg_class fcl ON fcl.oid = con.confrelid
+        CROSS JOIN LATERAL unnest(con.conkey, con.confkey) AS k(attnum, fattnum)
+        JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.attnum
+        JOIN pg_attribute fa ON fa.attrelid = con.confrelid AND fa.attnum = k.fattnum
+        WHERE n.nspname = current_schema() AND con.contype = 'f'
         ORDER BY cl.relname, con.conname`);
             for (const row of fks.rows) {
                 builder.get(row.table_name).foreignKeys.push({
@@ -177,22 +177,22 @@ async function createMysqlDriver(url) {
         },
         async tables() {
             const builder = new TableBuilder();
-            for (const row of await rows(`
-        SELECT TABLE_NAME AS table_name, TABLE_COMMENT AS table_comment
-        FROM information_schema.TABLES
-        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+            for (const row of await rows(`
+        SELECT TABLE_NAME AS table_name, TABLE_COMMENT AS table_comment
+        FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
         ORDER BY TABLE_NAME`)) {
                 const table = builder.get(row.table_name);
                 if (row.table_comment)
                     table.description = row.table_comment;
             }
-            for (const row of await rows(`
-        SELECT c.TABLE_NAME AS table_name, c.COLUMN_NAME AS column_name, c.COLUMN_TYPE AS column_type,
-               c.IS_NULLABLE AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY AS column_key
-        FROM information_schema.COLUMNS c
-        JOIN information_schema.TABLES t
-          ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_TYPE = 'BASE TABLE'
-        WHERE c.TABLE_SCHEMA = DATABASE()
+            for (const row of await rows(`
+        SELECT c.TABLE_NAME AS table_name, c.COLUMN_NAME AS column_name, c.COLUMN_TYPE AS column_type,
+               c.IS_NULLABLE AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY AS column_key
+        FROM information_schema.COLUMNS c
+        JOIN information_schema.TABLES t
+          ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_TYPE = 'BASE TABLE'
+        WHERE c.TABLE_SCHEMA = DATABASE()
         ORDER BY c.TABLE_NAME, c.ORDINAL_POSITION`)) {
                 builder.get(row.table_name).columns.push({
                     name: row.column_name,
@@ -203,10 +203,10 @@ async function createMysqlDriver(url) {
                 });
             }
             const indexMap = new Map();
-            for (const row of await rows(`
-        SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name, NON_UNIQUE AS non_unique, COLUMN_NAME AS column_name
-        FROM information_schema.STATISTICS
-        WHERE TABLE_SCHEMA = DATABASE() AND INDEX_NAME <> 'PRIMARY'
+            for (const row of await rows(`
+        SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name, NON_UNIQUE AS non_unique, COLUMN_NAME AS column_name
+        FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA = DATABASE() AND INDEX_NAME <> 'PRIMARY'
         ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX`)) {
                 const key = `${row.table_name}.${row.index_name}`;
                 let entry = indexMap.get(key);
@@ -219,13 +219,13 @@ async function createMysqlDriver(url) {
             }
             for (const { table, index } of indexMap.values())
                 builder.get(table).indexes.push(index);
-            for (const row of await rows(`
-        SELECT k.CONSTRAINT_NAME AS constraint_name, k.TABLE_NAME AS table_name, k.COLUMN_NAME AS column_name,
-               k.REFERENCED_TABLE_NAME AS ref_table, k.REFERENCED_COLUMN_NAME AS ref_column, r.DELETE_RULE AS delete_rule
-        FROM information_schema.KEY_COLUMN_USAGE k
-        JOIN information_schema.REFERENTIAL_CONSTRAINTS r
-          ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME AND r.TABLE_NAME = k.TABLE_NAME
-        WHERE k.TABLE_SCHEMA = DATABASE() AND k.REFERENCED_TABLE_NAME IS NOT NULL
+            for (const row of await rows(`
+        SELECT k.CONSTRAINT_NAME AS constraint_name, k.TABLE_NAME AS table_name, k.COLUMN_NAME AS column_name,
+               k.REFERENCED_TABLE_NAME AS ref_table, k.REFERENCED_COLUMN_NAME AS ref_column, r.DELETE_RULE AS delete_rule
+        FROM information_schema.KEY_COLUMN_USAGE k
+        JOIN information_schema.REFERENTIAL_CONSTRAINTS r
+          ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME AND r.TABLE_NAME = k.TABLE_NAME
+        WHERE k.TABLE_SCHEMA = DATABASE() AND k.REFERENCED_TABLE_NAME IS NOT NULL
         ORDER BY k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`)) {
                 builder.get(row.table_name).foreignKeys.push({
                     name: row.constraint_name,

package/dist/governor/store.d.ts

@@ -31,3 +31,21 @@ export declare function appendEscalation(targetDir: string, build: (id: string)
     position?: 'first' | 'last';
     projectName?: string;
 }): string;
+export interface EscalationHistoryEntry {
+    id: string;
+    type: string;
+    status: 'resolved' | 'dismissed';
+    summary: string;
+    resolutionNotes?: string;
+    resolvedAt?: string;
+}
+/**
+ * The closed escalations of one task, oldest first, so the worker who picks the task up again
+ * learns how each gap was settled instead of raising it a second time.
+ */
+export declare function taskEscalationHistory(targetDir: string, taskId: string, limit?: number): EscalationHistoryEntry[];
+/**
+ * Closes the pending escalations of a task that has just completed: the question was settled one way
+ * or another, so it should not keep asking for a decision. Returns the ids it closed.
+ */
+export declare function closeEscalationsForTask(targetDir: string, taskId: string, note: string): string[];

package/dist/governor/store.js

@@ -82,3 +82,56 @@ export function appendEscalation(targetDir, build, options) {
         return id;
     });
 }
+const HISTORY_TEXT_LIMIT = 400;
+/** Plain single-line text: control characters could hide words in a terminal or a prompt. */
+function clip(value) {
+    const text = String(value ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim();
+    return text.length > HISTORY_TEXT_LIMIT ? `${text.slice(0, HISTORY_TEXT_LIMIT)}...` : text;
+}
+const sortKey = (e) => String(e.resolvedAt ?? e.timestamp ?? '');
+/**
+ * The closed escalations of one task, oldest first, so the worker who picks the task up again
+ * learns how each gap was settled instead of raising it a second time.
+ */
+export function taskEscalationHistory(targetDir, taskId, limit = 3) {
+    const records = loadEscalationFile(targetDir, path.basename(targetDir)).escalations;
+    return records
+        .filter((e) => e && typeof e === 'object' && e.taskId === taskId)
+        .filter((e) => e.status === 'resolved' || e.status === 'dismissed')
+        .sort((a, b) => sortKey(a).localeCompare(sortKey(b)))
+        .slice(-limit)
+        .map((e) => ({
+        id: clip(e.id),
+        type: clip(e.type),
+        status: e.status,
+        summary: clip(e.summary),
+        ...(e.resolutionNotes ? { resolutionNotes: clip(e.resolutionNotes) } : {}),
+        ...(e.resolvedAt ? { resolvedAt: clip(e.resolvedAt) } : {}),
+    }));
+}
+/**
+ * Closes the pending escalations of a task that has just completed: the question was settled one way
+ * or another, so it should not keep asking for a decision. Returns the ids it closed.
+ */
+export function closeEscalationsForTask(targetDir, taskId, note) {
+    const file = escalationPath(targetDir);
+    if (!fs.existsSync(file))
+        return [];
+    return withFileLockSync(file, () => {
+        const data = loadEscalationFile(targetDir, path.basename(targetDir));
+        const closed = [];
+        for (const e of data.escalations) {
+            if (!e || e.taskId !== taskId || (e.status && e.status !== 'pending_review'))
+                continue;
+            e.status = 'resolved';
+            e.resolutionNotes = note;
+            e.resolvedAt = new Date().toISOString();
+            closed.push(e.id);
+        }
+        if (closed.length) {
+            data.lastUpdated = new Date().toISOString();
+            writeJsonAtomicSync(file, data);
+        }
+        return closed;
+    });
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { runVerify } from './commands/verify.js';
 import { runTestGen, TEST_GEN_FRAMEWORK_HELP } from './commands/test-gen.js';
 import { runBench } from './commands/bench.js';
 import { runTriage } from './commands/triage.js';
+import { runLearnPropose, runLearnDecide, runLearnList } from './commands/learn.js';
 import { packageVersion } from './core/version.js';
 export function createProgram() {
     const program = new Command();
@@ -215,6 +216,46 @@ export function createProgram() {
         .action(async (taskId, targetDir, options) => {
         await runTaskUnlock(taskId, targetDir, { reason: options.reason, revoke: options.revoke });
     });
+    const learn = program
+        .command('learn')
+        .description('Project lessons the contracts do not capture: agents propose, a human approves');
+    learn
+        .command('propose <insight> [targetDir]')
+        .description('Propose a lesson for later workers (it waits for a human to approve it)')
+        .option('--role <role>', 'Only workers with this role see it')
+        .option('--files <globs>', 'Comma-separated files, dirs or globs; only tasks touching them see it')
+        .option('--task <taskId>', 'The task where it came up')
+        .option('-d, --details <details>', 'Longer explanation')
+        .option('--by <who>', 'Who proposes it (defaults to NATIV_ROLE)')
+        .option('--json', 'Output the stored learning as JSON')
+        .action(async (insight, targetDir, options) => {
+        await runLearnPropose(insight, targetDir, options);
+    });
+    learn
+        .command('approve <id> [targetDir]')
+        .description('Approve a proposed lesson so matching tasks carry it (interactive terminal only)')
+        .option('-n, --note <note>', 'Why it was approved')
+        .option('-y, --yes', 'Skip the confirmation question (still needs a terminal)')
+        .action(async (id, targetDir, options) => {
+        await runLearnDecide(id, 'approved', targetDir, options);
+    });
+    learn
+        .command('reject <id> [targetDir]')
+        .description('Reject a proposed or approved lesson (interactive terminal only)')
+        .option('-n, --note <note>', 'Why it was rejected')
+        .option('-y, --yes', 'Skip the confirmation question (still needs a terminal)')
+        .action(async (id, targetDir, options) => {
+        await runLearnDecide(id, 'rejected', targetDir, options);
+    });
+    learn
+        .command('list [targetDir]')
+        .description('List lessons')
+        .option('-s, --status <status>', 'proposed, approved or rejected')
+        .option('--role <role>', 'Only lessons scoped to this role')
+        .option('--json', 'Output as JSON')
+        .action(async (targetDir, options) => {
+        await runLearnList(targetDir, options);
+    });
     const hook = program
         .command('hook')
         .description('Claude Code hook entry points for role enforcement');