@njeybe/nativ 2.4.0 → 2.5.0

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/tier1-liaison.d.ts

@@ -108,6 +108,8 @@ export declare function hasGeminiApiKey(root?: string): boolean;
  * text leaves the machine. `extraSecrets` (e.g. the Gemini key itself) are masked verbatim.
  */
 export declare function redactSecrets(text: string, extraSecrets?: string[]): string;
+export declare function loadTriageConfig(root: string): Partial<TriageConfig>;
+export declare function saveTriageConfig(root: string, update: Partial<TriageConfig>): void;
 /**
  * Tier 1 AI Strategist Liaison instance managing escalation evaluation,
  * auto-patch application, and configuration.

package/dist/core/tier1-liaison.js

@@ -90,6 +90,62 @@ function loadContracts(root) {
         uiSpecs: read('ui_specs.md') ?? undefined,
     };
 }
+export function loadTriageConfig(root) {
+    const configFile = path.join(root, '.nativ', 'config.json');
+    try {
+        if (!fs.existsSync(configFile))
+            return {};
+        const parsed = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+        if (parsed && typeof parsed === 'object' && parsed.triage) {
+            const res = {};
+            if (typeof parsed.triage.autoTriageEnabled === 'boolean') {
+                res.autoTriageEnabled = parsed.triage.autoTriageEnabled;
+            }
+            if (parsed.triage.riskThreshold === 'safe_contracts_only' || parsed.triage.riskThreshold === 'all_non_destructive') {
+                res.riskThreshold = parsed.triage.riskThreshold;
+            }
+            if (typeof parsed.triage.model === 'string' && parsed.triage.model.trim()) {
+                res.model = parsed.triage.model.trim();
+            }
+            return res;
+        }
+    }
+    catch {
+        // Ignore corrupt or unreadable config file
+    }
+    return {};
+}
+export function saveTriageConfig(root, update) {
+    const nativDir = path.join(root, '.nativ');
+    const configFile = path.join(nativDir, 'config.json');
+    try {
+        if (!fs.existsSync(nativDir))
+            fs.mkdirSync(nativDir, { recursive: true });
+        let existing = {};
+        if (fs.existsSync(configFile)) {
+            try {
+                existing = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+            }
+            catch {
+                existing = {};
+            }
+        }
+        const currentTriage = (existing.triage && typeof existing.triage === 'object') ? existing.triage : {};
+        if (typeof update.autoTriageEnabled === 'boolean')
+            currentTriage.autoTriageEnabled = update.autoTriageEnabled;
+        if (update.riskThreshold)
+            currentTriage.riskThreshold = update.riskThreshold;
+        if (update.model)
+            currentTriage.model = update.model;
+        existing.triage = currentTriage;
+        const tmp = `${configFile}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+        fs.renameSync(tmp, configFile);
+    }
+    catch {
+        // Ignore write failures gracefully
+    }
+}
 /**
  * Tier 1 AI Strategist Liaison instance managing escalation evaluation,
  * auto-patch application, and configuration.
@@ -106,11 +162,12 @@ export class Tier1Liaison {
     constructor(root, options = {}) {
         this.root = root;
         this.options = options;
+        const saved = loadTriageConfig(root);
         this.config = {
             // Off by default: even a fix classified as safe waits for confirmation unless auto-triage is enabled.
-            autoTriageEnabled: options.config?.autoTriageEnabled ?? false,
-            riskThreshold: options.config?.riskThreshold ?? 'safe_contracts_only',
-            model: options.model ?? DEFAULT_MODEL,
+            autoTriageEnabled: options.config?.autoTriageEnabled ?? saved.autoTriageEnabled ?? false,
+            riskThreshold: options.config?.riskThreshold ?? saved.riskThreshold ?? 'safe_contracts_only',
+            model: options.model ?? saved.model ?? DEFAULT_MODEL,
         };
     }
     /** Provider options after the legacy `apiKey` and `model` hints are folded in. */
@@ -155,6 +212,10 @@ export class Tier1Liaison {
         if (body.riskThreshold === 'safe_contracts_only' || body.riskThreshold === 'all_non_destructive') {
             this.config.riskThreshold = body.riskThreshold;
         }
+        if (typeof body.model === 'string' && body.model.trim()) {
+            this.config.model = body.model.trim();
+        }
+        saveTriageConfig(this.root, this.config);
         return { ok: true, config: { ...this.config } };
     }
     async evaluate(escalationId) {

package/dist/core/verifier/executor.d.ts

@@ -0,0 +1,5 @@
+import type { VerificationResult } from './types.js';
+/**
+ * Execute a verification command in the workspace directory with timeout and output capture.
+ */
+export declare function executeVerification(command: string, cwd: string, timeoutMs?: number): Promise<VerificationResult>;

package/dist/core/verifier/executor.js

@@ -0,0 +1,62 @@
+import { exec } from 'node:child_process';
+/**
+ * Execute a verification command in the workspace directory with timeout and output capture.
+ */
+export async function executeVerification(command, cwd, timeoutMs = 120_000) {
+    const trimmed = (command || '').trim();
+    // Treat empty, 'none', or 'skip' as an informational pass
+    if (!trimmed || trimmed.toLowerCase() === 'none' || trimmed.toLowerCase() === 'skip') {
+        return {
+            success: true,
+            exitCode: 0,
+            command: trimmed || 'none',
+            stdout: '',
+            stderr: '',
+            durationMs: 0,
+            skipped: true,
+        };
+    }
+    // Cross-platform compatibility for common test commands on Windows cmd.exe
+    let finalCommand = trimmed;
+    if (process.platform === 'win32') {
+        if (trimmed === 'true')
+            finalCommand = 'exit 0';
+        else if (trimmed === 'false')
+            finalCommand = 'exit 1';
+    }
+    const start = Date.now();
+    return new Promise((resolve) => {
+        exec(finalCommand, {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer: 10 * 1024 * 1024,
+            env: process.env,
+        }, (err, stdout, stderr) => {
+            const durationMs = Date.now() - start;
+            const out = (stdout || '').toString();
+            const errOut = (stderr || '').toString();
+            if (err) {
+                const exitCode = typeof err.code === 'number' ? err.code : 1;
+                resolve({
+                    success: false,
+                    exitCode,
+                    command: trimmed,
+                    stdout: out,
+                    stderr: errOut || err.message,
+                    durationMs,
+                    error: err.killed ? `Command timed out after ${timeoutMs}ms` : err.message,
+                });
+            }
+            else {
+                resolve({
+                    success: true,
+                    exitCode: 0,
+                    command: trimmed,
+                    stdout: out,
+                    stderr: errOut,
+                    durationMs,
+                });
+            }
+        });
+    });
+}

package/dist/core/verifier/phases.d.ts

@@ -0,0 +1,5 @@
+import type { PhasesOutcome, VerifyPhasesConfig } from './types.js';
+/** `verifyPhases` from the main checkout's `.nativ/config.json`, never from a worktree's own copy. */
+export declare function loadVerifyPhases(configDir: string): VerifyPhasesConfig;
+/** Runs the configured phases in order and stops at the first failure. */
+export declare function runVerifyPhases(cwd: string, configDir: string, timeout?: number): Promise<PhasesOutcome>;

package/dist/core/verifier/phases.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseJsonLoose } from '../enforcement.js';
+import { resolveMainRoot } from '../root-resolver.js';
+import { executeVerification } from './executor.js';
+/** 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 };
+}

package/dist/core/verifier/task-verifier.d.ts

@@ -0,0 +1,37 @@
+import { MasterPlan, MasterPlanTask } from '../../scanner/types.js';
+import type { BatchVerificationResult, PhasesOutcome, TaskVerificationResult, VerificationResult } from './types.js';
+export declare function loadMasterPlan(targetDir: string): {
+    planPath: string;
+    plan: MasterPlan | null;
+    error?: string;
+};
+/**
+ * Run the code-shape check on a task's target files and print a short summary to stderr.
+ * 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;
+/**
+ * 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.
+ */
+export declare function verifyTask(taskId: string, targetDirArg?: string, options?: {
+    timeout?: number;
+}): Promise<TaskVerificationResult>;
+/**
+ * Verify a batch of tasks (by milestone, all completed tasks, or the active in-progress task).
+ */
+export declare function verifyBatch(targetDirArg?: string, options?: {
+    taskId?: string;
+    milestoneId?: string;
+    all?: boolean;
+    timeout?: number;
+}): Promise<BatchVerificationResult>;

package/dist/core/verifier/task-verifier.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkCodeShape, formatCodeShapeReport } from '../code-shape.js';
+import { executeVerification } from './executor.js';
+import { runVerifyPhases } from './phases.js';
+export function loadMasterPlan(targetDir) {
+    const planPath = path.join(targetDir, '.ai', 'master_plan.json');
+    if (!fs.existsSync(planPath)) {
+        return { planPath, plan: null, error: `No .ai/master_plan.json found at: ${planPath}` };
+    }
+    try {
+        const raw = fs.readFileSync(planPath, 'utf8');
+        const plan = JSON.parse(raw);
+        return { planPath, plan };
+    }
+    catch (err) {
+        return { planPath, plan: null, error: `Failed to parse .ai/master_plan.json: ${err.message}` };
+    }
+}
+/**
+ * Run the code-shape check on a task's target files and print a short summary to stderr.
+ * In 'warn' mode (default) the result is untouched; in 'block' mode issues fail it with a reason.
+ */
+export function applyCodeShape(result, targetDir, task) {
+    if (result.skipped || !result.success)
+        return result;
+    const report = checkCodeShape(targetDir, task.targetFiles || []);
+    if (report.mode === 'off')
+        return result;
+    result.codeShape = report;
+    const summary = formatCodeShapeReport(report);
+    if (summary)
+        console.error(summary);
+    if (report.mode === 'block' && report.issues.length > 0) {
+        result.success = false;
+        result.exitCode = 1;
+        result.error = `Code shape check failed: ${report.issues.length} issue(s) (codeStyle.mode is "block")`;
+    }
+    return result;
+}
+/**
+ * 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.
+ */
+export async function verifyTask(taskId, targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const { plan, error } = loadMasterPlan(targetDir);
+    if (!plan) {
+        return {
+            taskId,
+            title: 'Unknown',
+            milestoneId: 'unknown',
+            milestoneName: 'Unknown',
+            status: 'unknown',
+            result: {
+                success: false,
+                exitCode: 1,
+                command: '',
+                stdout: '',
+                stderr: error || 'Failed to load master plan',
+                durationMs: 0,
+                error: error || 'Failed to load master plan',
+            },
+        };
+    }
+    let foundTask = null;
+    let foundMilestone = null;
+    for (const m of plan.milestones) {
+        const t = m.tasks.find((item) => item.id === taskId);
+        if (t) {
+            foundTask = t;
+            foundMilestone = m;
+            break;
+        }
+    }
+    if (!foundTask || !foundMilestone) {
+        return {
+            taskId,
+            title: 'Not Found',
+            milestoneId: 'unknown',
+            milestoneName: 'Unknown',
+            status: 'unknown',
+            result: {
+                success: false,
+                exitCode: 1,
+                command: '',
+                stdout: '',
+                stderr: `Task [${taskId}] not found in .ai/master_plan.json`,
+                durationMs: 0,
+                error: `Task [${taskId}] not found`,
+            },
+        };
+    }
+    const result = await runTaskVerification(foundTask, { cwd: targetDir, timeout: options.timeout });
+    return {
+        taskId: foundTask.id,
+        title: foundTask.title,
+        milestoneId: foundMilestone.id,
+        milestoneName: foundMilestone.name,
+        status: foundTask.status,
+        result,
+    };
+}
+/**
+ * Verify a batch of tasks (by milestone, all completed tasks, or the active in-progress task).
+ */
+export async function verifyBatch(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const { plan, error } = loadMasterPlan(targetDir);
+    if (!plan) {
+        return {
+            projectName: 'unknown',
+            total: 0,
+            passed: 0,
+            failed: 1,
+            skipped: 0,
+            durationMs: 0,
+            tasks: [
+                {
+                    taskId: 'init',
+                    title: 'Plan Loader',
+                    milestoneId: 'unknown',
+                    milestoneName: 'Unknown',
+                    status: 'unknown',
+                    result: {
+                        success: false,
+                        exitCode: 1,
+                        command: '',
+                        stdout: '',
+                        stderr: error || 'Plan not found',
+                        durationMs: 0,
+                        error: error || 'Plan not found',
+                    },
+                },
+            ],
+        };
+    }
+    // Filter tasks to run
+    const candidates = [];
+    for (const m of plan.milestones) {
+        for (const t of m.tasks) {
+            if (options.taskId && t.id === options.taskId) {
+                candidates.push({ task: t, milestone: m });
+            }
+            else if (options.milestoneId && (m.id === options.milestoneId || m.name.toLowerCase() === options.milestoneId.toLowerCase())) {
+                candidates.push({ task: t, milestone: m });
+            }
+            else if (options.all) {
+                // All tasks with verification commands (prefer completed or in_progress, but include all)
+                candidates.push({ task: t, milestone: m });
+            }
+        }
+    }
+    // If no filters specified, find the current in_progress task, or next ready task
+    if (!options.taskId && !options.milestoneId && !options.all) {
+        let activeTask = null;
+        for (const m of plan.milestones) {
+            const inProgress = m.tasks.find((t) => t.status === 'in_progress');
+            if (inProgress) {
+                activeTask = { task: inProgress, milestone: m };
+                break;
+            }
+        }
+        if (!activeTask) {
+            for (const m of plan.milestones) {
+                const pending = m.tasks.find((t) => t.status === 'pending');
+                if (pending) {
+                    activeTask = { task: pending, milestone: m };
+                    break;
+                }
+            }
+        }
+        if (activeTask) {
+            candidates.push(activeTask);
+        }
+    }
+    const results = [];
+    let passed = 0;
+    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 vResult = await runTaskVerification(task, { cwd: targetDir, timeout: options.timeout, phases });
+        totalDuration += vResult.durationMs;
+        if (vResult.skipped) {
+            skipped++;
+        }
+        else if (vResult.success) {
+            passed++;
+        }
+        else {
+            failed++;
+        }
+        results.push({
+            taskId: task.id,
+            title: task.title,
+            milestoneId: milestone.id,
+            milestoneName: milestone.name,
+            status: task.status,
+            result: vResult,
+        });
+    }
+    return {
+        projectName: plan.projectName,
+        total: candidates.length,
+        passed,
+        failed,
+        skipped,
+        durationMs: totalDuration,
+        tasks: results,
+    };
+}