@njeybe/nativ 2.3.1 → 2.4.1

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/spec-slices.js

@@ -16,9 +16,7 @@ function cap(text, max) {
         return { text, truncated: false };
     return { text: text.slice(0, Math.max(0, max)) + TRUNCATION_MARKER, truncated: true };
 }
-function markdownSection(content, anchor) {
-    const wanted = decodeURIComponent(anchor).toLowerCase();
-    const lines = content.split(/\r?\n/);
+function findSection(lines, predicate) {
     const seen = new Map();
     let inFence = false;
     let start = -1;
@@ -40,17 +38,41 @@ function markdownSection(content, anchor) {
                 return lines.slice(start, i).join('\n').trimEnd();
             continue;
         }
-        const base = slugifyHeading(m[2]);
+        const headingText = m[2];
+        const base = slugifyHeading(headingText);
         const count = seen.get(base) ?? 0;
         seen.set(base, count + 1);
         const slug = count === 0 ? base : `${base}-${count}`;
-        if (slug === wanted) {
+        if (predicate(slug, headingText)) {
             start = i;
             level = hLevel;
         }
     }
     return start >= 0 ? lines.slice(start).join('\n').trimEnd() : null;
 }
+function markdownSection(content, anchor) {
+    const wanted = decodeURIComponent(anchor).trim().toLowerCase();
+    const lines = content.split(/\r?\n/);
+    // 1. Exact slug match (standard markdown anchor)
+    const exact = findSection(lines, (slug) => slug === wanted);
+    if (exact !== null)
+        return exact;
+    // 2. Prefix / section number match (e.g. "6" or "15.1" matching "## 6. Coach..." or "### 15.1 Shared Pieces")
+    const prefixMatch = findSection(lines, (_slug, headingText) => {
+        const raw = headingText.trim().toLowerCase();
+        if (raw === wanted)
+            return true;
+        if (raw.startsWith(`${wanted}.`) || raw.startsWith(`${wanted} `) || raw.startsWith(`${wanted}:`))
+            return true;
+        const base = slugifyHeading(headingText);
+        if (base.startsWith(`${wanted}-`) || base === wanted)
+            return true;
+        return false;
+    });
+    if (prefixMatch !== null)
+        return prefixMatch;
+    return null;
+}
 function jsonPointerValue(doc, pointer) {
     if (pointer === '')
         return { found: true, value: doc };
@@ -80,6 +102,73 @@ function jsonPointerValue(doc, pointer) {
     }
     return { found: true, value: current };
 }
+function getByDotPath(obj, pathStr) {
+    const parts = pathStr.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (cur && typeof cur === 'object' && Object.prototype.hasOwnProperty.call(cur, p)) {
+            cur = cur[p];
+        }
+        else {
+            return { found: false };
+        }
+    }
+    return { found: true, value: cur };
+}
+function findEntityInDoc(doc, ref) {
+    if (!doc || typeof doc !== 'object')
+        return { found: false };
+    // 1. Direct table match in relevantTables or tables
+    const tables = Array.isArray(doc.relevantTables) ? doc.relevantTables : (Array.isArray(doc.tables) ? doc.tables : null);
+    if (tables) {
+        const table = tables.find((t) => t && (t.name === ref || t.tableName === ref || t.id === ref));
+        if (table)
+            return { found: true, value: table };
+    }
+    if (doc.tables && typeof doc.tables === 'object' && !Array.isArray(doc.tables) && Object.prototype.hasOwnProperty.call(doc.tables, ref)) {
+        return { found: true, value: doc.tables[ref] };
+    }
+    // 2. Mail events trigger match
+    if (Array.isArray(doc.mailEvents)) {
+        const event = doc.mailEvents.find((m) => m && (m.trigger === ref || m.endpoint === ref || m.id === ref));
+        if (event)
+            return { found: true, value: event };
+    }
+    // 3. Routes match in routingPolicy or routes
+    const routeLists = [];
+    if (doc.routingPolicy && typeof doc.routingPolicy === 'object') {
+        if (Array.isArray(doc.routingPolicy.playerRoutes))
+            routeLists.push(doc.routingPolicy.playerRoutes);
+        if (Array.isArray(doc.routingPolicy.venueScopedRoutes))
+            routeLists.push(doc.routingPolicy.venueScopedRoutes);
+        if (Array.isArray(doc.routingPolicy.adminRoutes))
+            routeLists.push(doc.routingPolicy.adminRoutes);
+        if (Array.isArray(doc.routingPolicy.routes))
+            routeLists.push(doc.routingPolicy.routes);
+    }
+    if (Array.isArray(doc.routes))
+        routeLists.push(doc.routes);
+    for (const list of routeLists) {
+        const route = list.find((r) => r && (r.name === ref ||
+            r.id === ref ||
+            (Array.isArray(r.routeNames) && r.routeNames.includes(ref))));
+        if (route)
+            return { found: true, value: route };
+    }
+    // 4. Contract list items (e.g. confirmationPageContracts array)
+    for (const key of Object.keys(doc)) {
+        const val = doc[key];
+        if (Array.isArray(val)) {
+            const match = val.find((item) => item && typeof item === 'object' && (item.name === ref ||
+                item.id === ref ||
+                item.trigger === ref ||
+                (Array.isArray(item.routeNames) && item.routeNames.includes(ref))));
+            if (match)
+                return { found: true, value: match };
+        }
+    }
+    return { found: false };
+}
 function joinUrl(base, p) {
     return typeof base === 'string' ? base.replace(/\/+$/, '') + p : p;
 }
@@ -115,9 +204,32 @@ function endpointValue(doc, fragment) {
     return byId ? { found: true, value: byId } : { found: false };
 }
 function jsonRefValue(doc, fragment) {
-    if (fragment === '' || fragment.startsWith('/'))
+    if (fragment === '')
         return jsonPointerValue(doc, fragment);
-    return endpointValue(doc, fragment);
+    // 1. Direct JSON pointer starting with /
+    if (fragment.startsWith('/')) {
+        const ptr = jsonPointerValue(doc, fragment);
+        if (ptr.found)
+            return ptr;
+    }
+    else {
+        // 2. JSON pointer or top-level property without leading slash (e.g. #confirmationPageContracts)
+        const ptr = jsonPointerValue(doc, `/${fragment}`);
+        if (ptr.found)
+            return ptr;
+        // 3. Dot-path property navigation (e.g. #contract.section)
+        if (fragment.includes('.')) {
+            const dot = getByDotPath(doc, fragment);
+            if (dot.found)
+                return dot;
+        }
+    }
+    // 4. Endpoint lookup by method + path or id
+    const endpoint = endpointValue(doc, fragment);
+    if (endpoint.found)
+        return endpoint;
+    // 5. Named entity lookup: route names, mail event triggers, DB schema tables
+    return findEntityInDoc(doc, fragment);
 }
 /**
  * Resolves specRefs ("ui_specs.md#anchor", "api_contracts.json#/paths/~1x",

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++;