@njeybe/nativ 2.8.0 → 2.9.1

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

@@ -1,5 +1,6 @@
 import { MasterPlan, MasterPlanTask } from '../../scanner/types.js';
-import type { BatchVerificationResult, PhasesOutcome, TaskVerificationResult, VerificationResult } from './types.js';
+import type { RunOptions } from './isolation.js';
+import type { BatchVerificationResult, TaskVerificationResult, VerificationResult } from './types.js';
 export declare function loadMasterPlan(targetDir: string): {
     planPath: string;
     plan: MasterPlan | null;
@@ -12,14 +13,10 @@ export declare function loadMasterPlan(targetDir: string): {
 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.
+ * first failure, then the task's own command (both in a clean copy when isolation is on),
+ * then the code-shape check on the real tree.
  */
-export declare function runTaskVerification(task: MasterPlanTask, options: {
-    cwd: string;
-    configDir?: string;
-    timeout?: number;
-    phases?: PhasesOutcome;
-}): Promise<VerificationResult>;
+export declare function runTaskVerification(task: MasterPlanTask, options: RunOptions): Promise<VerificationResult>;
 /**
  * Run verification for a single specific task in the plan.
  */
@@ -34,4 +31,5 @@ export declare function verifyBatch(targetDirArg?: string, options?: {
     milestoneId?: string;
     all?: boolean;
     timeout?: number;
+    isolation?: 'none' | 'clean';
 }): Promise<BatchVerificationResult>;

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

@@ -1,8 +1,9 @@
 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';
+import { resolveActiveProfileSettings } from '../profiles.js';
+import { resolveMainRoot } from '../root-resolver.js';
+import { NO_ISOLATION, needsRun, openIsolation, runPhasesIn, runInPlan, diagnose, } from './isolation.js';
 export function loadMasterPlan(targetDir) {
     const planPath = path.join(targetDir, '.ai', 'master_plan.json');
     if (!fs.existsSync(planPath)) {
@@ -25,37 +26,51 @@ export function applyCodeShape(result, targetDir, task) {
     if (result.skipped || !result.success)
         return result;
     const report = checkCodeShape(targetDir, task.targetFiles || []);
-    if (report.mode === 'off')
+    if (report.issues.length === 0)
         return result;
     result.codeShape = report;
     const summary = formatCodeShapeReport(report);
     if (summary)
         console.error(summary);
-    if (report.mode === 'block' && report.issues.length > 0) {
+    const blocking = report.issues.filter((i) => (i.category === 'config' ? report.configMode : report.mode) === 'block');
+    if (blocking.length > 0) {
+        const names = [...new Set(blocking.filter((i) => i.category === 'config')
+                .map((i) => i.message.split(' ')[0]))];
+        const config = names.length > 0 ? `; unset-variable fallbacks: ${names.join(', ')}` : '';
         result.success = false;
         result.exitCode = 1;
-        result.error = `Code shape check failed: ${report.issues.length} issue(s) (codeStyle.mode is "block")`;
+        result.error = `Code shape check failed: ${blocking.length} issue(s) set to block${config}`;
     }
     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.
+ * first failure, then the task's own command (both in a clean copy when isolation is on),
+ * then the code-shape check on the real tree.
  */
 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);
+    const settings = resolveActiveProfileSettings(resolveMainRoot(configDir));
+    const wanted = options.isolation ?? settings.verifyIsolation;
+    const owned = !options.plan;
+    const plan = options.plan
+        ?? (needsRun([task.verificationCommand], configDir, !!options.phases)
+            ? await openIsolation(options.cwd, configDir, wanted)
+            : NO_ISOLATION);
+    try {
+        let result = await runInPlan(task, options, plan);
+        result.isolation = plan.mode;
+        if (plan.warnings.length)
+            result.warnings = [...plan.warnings];
+        if (plan.mode === 'clean' && !result.success) {
+            result = await diagnose(task, options, result, settings.verifyIsolationFailure);
+        }
+        return applyCodeShape(result, options.cwd, task);
+    }
+    finally {
+        if (owned)
+            await plan.dispose?.();
+    }
 }
 /**
  * Run verification for a single specific task in the plan.
@@ -91,6 +106,15 @@ export async function verifyTask(taskId, targetDirArg, options = {}) {
             break;
         }
     }
+    const archivedIn = plan.milestones.find((m) => m.archived?.taskIds.includes(taskId));
+    if (!foundTask && archivedIn) {
+        const error = archivedMessage(taskId, archivedIn.id);
+        return {
+            taskId, title: 'Archived', milestoneId: archivedIn.id, milestoneName: archivedIn.name,
+            status: 'archived',
+            result: { success: false, exitCode: 1, command: '', stdout: '', stderr: error, durationMs: 0, error },
+        };
+    }
     if (!foundTask || !foundMilestone) {
         return {
             taskId,
@@ -119,6 +143,13 @@ export async function verifyTask(taskId, targetDirArg, options = {}) {
         result,
     };
 }
+function archivedMessage(what, milestoneId) {
+    return `${what} is archived (milestone ${milestoneId}). `
+        + `Run \`nativ milestone restore ${milestoneId}\` to bring its tasks back first.`;
+}
+function matchesMilestone(m, wanted) {
+    return m.id === wanted || m.name.toLowerCase() === wanted.toLowerCase();
+}
 /**
  * Verify a batch of tasks (by milestone, all completed tasks, or the active in-progress task).
  */
@@ -155,12 +186,19 @@ export async function verifyBatch(targetDirArg, options = {}) {
     }
     // Filter tasks to run
     const candidates = [];
+    const archivedWanted = options.milestoneId
+        ? plan.milestones.find((m) => m.archived && matchesMilestone(m, options.milestoneId))
+        : undefined;
+    if (archivedWanted) {
+        return refusedBatch(plan.projectName, archivedWanted, archivedMessage(`Milestone ${archivedWanted.id}`, archivedWanted.id));
+    }
+    // verify --all leaves archived milestones out: their stubs hold no tasks.
     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())) {
+            else if (options.milestoneId && matchesMilestone(m, options.milestoneId)) {
                 candidates.push({ task: t, milestone: m });
             }
             else if (options.all) {
@@ -197,29 +235,40 @@ 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 vResult = await runTaskVerification(task, { cwd: targetDir, timeout: options.timeout, phases });
-        totalDuration += vResult.durationMs;
-        if (vResult.skipped) {
-            skipped++;
-        }
-        else if (vResult.success) {
-            passed++;
-        }
-        else {
-            failed++;
+    // The phases check the whole project, so one run (and one clean tree) serves every task.
+    const wanted = options.isolation
+        ?? resolveActiveProfileSettings(resolveMainRoot(targetDir)).verifyIsolation;
+    const commands = candidates.map((c) => c.task.verificationCommand);
+    const isolation = candidates.length && needsRun(commands, targetDir, false)
+        ? await openIsolation(targetDir, targetDir, wanted)
+        : NO_ISOLATION;
+    try {
+        const phases = candidates.length
+            ? await runPhasesIn(isolation.dir ?? targetDir, targetDir, options.timeout, isolation.env)
+            : { reports: [] };
+        totalDuration += phases.reports.reduce((sum, r) => sum + r.durationMs, 0);
+        for (const { task, milestone } of candidates) {
+            const runOpts = { cwd: targetDir, timeout: options.timeout, phases, plan: isolation, isolation: wanted };
+            const vResult = await runTaskVerification(task, runOpts);
+            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,
+            });
         }
-        results.push({
-            taskId: task.id,
-            title: task.title,
-            milestoneId: milestone.id,
-            milestoneName: milestone.name,
-            status: task.status,
-            result: vResult,
-        });
+    }
+    finally {
+        await isolation.dispose?.();
     }
     return {
         projectName: plan.projectName,
@@ -231,3 +280,8 @@ export async function verifyBatch(targetDirArg, options = {}) {
         tasks: results,
     };
 }
+function refusedBatch(projectName, m, error) {
+    const result = { success: false, exitCode: 1, command: '', stdout: '', stderr: error, durationMs: 0, error };
+    const task = { taskId: m.id, title: 'Archived milestone', milestoneId: m.id, milestoneName: m.name, status: 'archived', result };
+    return { projectName, total: 1, passed: 0, failed: 1, skipped: 0, durationMs: 0, tasks: [task] };
+}

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

@@ -11,6 +11,10 @@ export interface VerificationResult {
     codeShape?: CodeShapeReport;
     /** Results of the configured `verifyPhases`, when any ran. */
     phases?: PhaseResult[];
+    /** Which isolation actually ran the check. */
+    isolation?: 'none' | 'clean';
+    /** Notes the reader should see, such as a fallback or a pass that holds only locally. */
+    warnings?: string[];
 }
 export interface PhaseResult {
     name: string;

package/dist/core/verifier/verify-env.d.ts

@@ -0,0 +1,2 @@
+/** Allowlisted variables from the parent env, plus the extra names, plus the sandbox markers. */
+export declare function buildVerifyEnv(extra?: string[], source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/core/verifier/verify-env.js

@@ -0,0 +1,22 @@
+// Builds the minimal environment a verification command runs with.
+const BASE = ['PATH', 'HOME', 'USERPROFILE', 'LANG', 'LC_ALL', 'TMPDIR', 'TEMP', 'TMP'];
+const WINDOWS = [
+    'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', 'APPDATA', 'LOCALAPPDATA',
+    'ProgramFiles', 'ProgramFiles(x86)',
+];
+const TOOLS = ['VIRTUAL_ENV', 'GOPATH', 'GOROOT', 'GOCACHE', 'GOMODCACHE'];
+/** Allowlisted variables from the parent env, plus the extra names, plus the sandbox markers. */
+export function buildVerifyEnv(extra = [], source = process.env) {
+    const names = new Set([...BASE, ...TOOLS, ...(process.platform === 'win32' ? WINDOWS : []), ...extra].map((n) => n.toLowerCase()));
+    const out = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined || !names.has(key.toLowerCase()))
+            continue;
+        if (key.startsWith('NATIV_') || key === 'CI')
+            continue;
+        out[key] = value;
+    }
+    out.CI = 'true';
+    out.NATIV_VERIFY_SANDBOX = '1';
+    return out;
+}

package/dist/index.js

@@ -1,8 +1,9 @@
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { runInit } from './commands/init.js';
 import { runStatus } from './commands/status.js';
 import { runValidate } from './commands/validate.js';
 import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskReclaim, runTaskEscalate, runTaskAdd, runTaskProposePatch, runTaskUnlock, } from './commands/task.js';
+import { runTaskShow } from './commands/task/task-show.js';
 import { runHookCheck, runHookStatus } from './commands/hook.js';
 import { runSetup } from './commands/setup.js';
 import { runDoctor } from './commands/doctor.js';
@@ -19,7 +20,15 @@ import { runNotifyTest } from './commands/notify.js';
 import { runLearnPropose, runLearnDecide, runLearnList } from './commands/learn.js';
 import { runProfileCommand } from './commands/profile.js';
 import { runDesignCheck } from './commands/design-check.js';
+import { runCheckDocs } from './commands/check.js';
+import { registerMilestoneCommands } from './commands/milestone.js';
 import { packageVersion } from './core/version.js';
+function parseGitVisibility(value) {
+    if (value !== 'hidden' && value !== 'shared') {
+        throw new InvalidArgumentError('Use hidden or shared.');
+    }
+    return value;
+}
 export function createProgram() {
     const program = new Command();
     program
@@ -31,6 +40,7 @@ export function createProgram() {
         .description('Scaffold the workflow (.ai/, AGENTS.md, directives) and the Claude Code configuration in the target directory')
         .option('-f, --force', 'Overwrite existing specification and directive files')
         .option('--design <profile>', 'Design profile: nativ, taste-v1 or taste-v2')
+        .option('--git-visibility <mode>', 'Git visibility of generated files: hidden (default) or shared', parseGitVisibility)
         .action(async (targetDir, options) => {
         await runInit(targetDir, options);
     });
@@ -40,10 +50,11 @@ export function createProgram() {
         .option('--command <cli>', 'How Claude Code should start nativ, e.g. "npx -y @njeybe/nativ" (default: nativ when installed globally)')
         .option('--enforcement <mode>', 'Role enforcement mode: warn (default), block or off')
         .option('--dry-run', 'Show what would change without writing anything')
+        .option('--git-visibility <mode>', 'Git visibility of generated files: hidden (default) or shared', parseGitVisibility)
         .option('-f, --force', 'Also overwrite agent and directive files that were edited by hand')
         .option('--json', 'Output the result as JSON')
         .action(async (targetDir, options) => {
-        await runSetup(targetDir, { command: options.command, enforcement: options.enforcement, dryRun: options.dryRun, force: options.force, json: options.json });
+        await runSetup(targetDir, { command: options.command, enforcement: options.enforcement, dryRun: options.dryRun, force: options.force, gitVisibility: options.gitVisibility, json: options.json });
     });
     program
         .command('doctor [targetDir]')
@@ -59,14 +70,16 @@ export function createProgram() {
         .command('update [targetDir]')
         .description('Refresh directives, role guides and the Claude Code configuration to the latest templates. Files you edited are kept; contracts and the plan are never touched')
         .option('-f, --force', 'Also replace directive and role-guide files that were edited by hand')
+        .option('--git-visibility <mode>', 'Git visibility of generated files: hidden (default) or shared', parseGitVisibility)
         .action(async (targetDir, options) => {
-        await runUpdate(targetDir, { force: options.force });
+        await runUpdate(targetDir, { force: options.force, gitVisibility: options.gitVisibility });
     });
     program
         .command('status [targetDir]')
         .description('Inspect current execution progress and telemetry from .ai/master_plan.json')
         .option('-t, --telemetry', 'Display token usage, duration, and cost estimation telemetry')
-        .option('--json', 'Output project status and telemetry as JSON')
+        .option('--json', 'Output project status and telemetry as JSON (compact)')
+        .option('--full', 'With --json, include every milestone task and per-task telemetry')
         .action(async (targetDir, options) => {
         await runStatus(targetDir, options);
     });
@@ -86,7 +99,7 @@ export function createProgram() {
         .option('--json', 'Output filtered tasks as JSON (a summary per task)')
         .option('--full', 'With --json, include every task field')
         .action(async (targetDir, options) => {
-        await runTaskList(targetDir, options);
+        await runTaskList(targetDir, { ...options, brief: !options.full });
     });
     program
         .command('verify [taskId] [targetDir]')
@@ -95,6 +108,8 @@ export function createProgram() {
         .option('-m, --milestone <id>', 'Run verification commands for all tasks in a specific milestone')
         .option('--json', 'Output verification telemetry as JSON')
         .option('--timeout <ms>', 'Execution timeout in milliseconds per command (default 120000)', parseInt)
+        .option('--isolation <mode>', 'Run checks in place (none) or in a clean copy (clean)')
+        .option('--clean', 'Short for --isolation clean')
         .action(async (taskId, targetDir, options) => {
         await runVerify(taskId, targetDir, options);
     });
@@ -128,7 +143,7 @@ export function createProgram() {
         .option('--json', 'Output filtered tasks as JSON (a summary per task)')
         .option('--full', 'With --json, include every task field')
         .action(async (targetDir, options) => {
-        await runTaskList(targetDir, options);
+        await runTaskList(targetDir, { ...options, brief: !options.full });
     });
     task
         .command('add <title> [targetDir]')
@@ -142,7 +157,11 @@ export function createProgram() {
         .option('--deps <ids>', 'Comma-separated dependency task IDs')
         .option('--spec-refs <refs>', 'Comma-separated spec anchors, e.g. ui_specs.md#appointment-list')
         .option('--complexity <level>', 'Task complexity: simple, standard or complex')
-        .option('--accept <text>', 'Acceptance ("done when") line; repeatable or "|"-separated', (value, prev = []) => [...prev, value])
+        .option('--kind <kind>', 'Verification kind: unit, integration, static-config, docs, probe or manual')
+        .option('--notes <text>', 'Task notes (required with --kind manual)')
+        .option('--accept <text>', 'Acceptance ("done when") line; repeatable, each value kept whole', (value, prev = []) => [...prev, value])
+        .option('--new-milestone <name>', 'Create the next milestone with this name and add the task to it')
+        .option('--force', 'With --new-milestone, allow it while a planned milestone is still open')
         .option('--json', 'Output the created task as JSON')
         .action(async (title, targetDir, options) => {
         await runTaskAdd(title, targetDir, options);
@@ -154,6 +173,13 @@ export function createProgram() {
         .action(async (targetDir, options) => {
         await runTaskNext(targetDir, options);
     });
+    task
+        .command('show <taskId> [targetDir]')
+        .description('Show one task in full, from the plan or from its archive file')
+        .option('--json', 'Output the task as JSON')
+        .action(async (taskId, targetDir, options) => {
+        await runTaskShow(taskId, targetDir, options);
+    });
     task
         .command('start <taskId> [targetDir]')
         .description('Claim a pending task whose dependencies are done and mark it in_progress')
@@ -168,8 +194,11 @@ export function createProgram() {
         .option('-n, --notes <notes>', 'Completion notes or summary')
         .option('--no-verify', 'Skip automated verification command execution')
         .option('--timeout <ms>', 'Verification execution timeout in milliseconds', parseInt)
+        .option('--isolation <mode>', 'Run the check in place (none) or in a clean copy (clean)')
+        .option('--clean', 'Short for --isolation clean')
         .action(async (taskId, targetDir, options) => {
         await runTaskComplete(taskId, targetDir, {
+            isolation: options.clean ? 'clean' : options.isolation,
             notes: options.notes,
             skipVerify: options.verify === false,
             timeout: options.timeout,
@@ -182,6 +211,8 @@ export function createProgram() {
         .option('-m, --milestone <id>', 'Run verification commands for all tasks in a specific milestone')
         .option('--json', 'Output verification telemetry as JSON')
         .option('--timeout <ms>', 'Execution timeout in milliseconds per command (default 120000)', parseInt)
+        .option('--isolation <mode>', 'Run checks in place (none) or in a clean copy (clean)')
+        .option('--clean', 'Short for --isolation clean')
         .action(async (taskId, targetDir, options) => {
         await runVerify(taskId, targetDir, options);
     });
@@ -241,6 +272,15 @@ export function createProgram() {
         .action(async (taskId, targetDir, options) => {
         await runTaskUnlock(taskId, targetDir, { reason: options.reason, revoke: options.revoke });
     });
+    registerMilestoneCommands(program);
+    const check = program.command('check').description('Checks on project files');
+    check
+        .command('docs <files...>')
+        .description('Check backticked paths, placeholders, settings and nativ flags in markdown files')
+        .option('--json', 'Output findings as JSON')
+        .action(async (files, options) => {
+        await runCheckDocs(files, options);
+    });
     const design = program.command('design').description('Design profile tools');
     design
         .command('check [paths...]')

package/dist/mcp/server.js

@@ -10,6 +10,8 @@ import { runTriage } from '../commands/triage.js';
 import { runStatus } from '../commands/status.js';
 import { runDoctor } from '../commands/doctor.js';
 import { runValidate } from '../commands/validate.js';
+import { runMilestoneArchive } from '../commands/milestone.js';
+import { runTaskShow } from '../commands/task/task-show.js';
 import { runWorktreeCreate, runWorktreeList, runWorktreeMerge, runWorktreeRemove, } from '../commands/worktree.js';
 import { runDbStatus, runDbInspect, runDbDiff } from '../commands/db.js';
 import { runVerify } from '../commands/verify.js';
@@ -52,6 +54,22 @@ export function createMcpServer(targetDirArg) {
             full: z.boolean().optional().describe('Return every task field; the default is a short summary per task'),
         },
     }, ({ available, status, milestone, fastPath, full }) => captureOutput(() => runTaskList(targetDir, { available, status, milestone, fastPath, json: true, brief: !full })));
+    registerNativTool('task_show', {
+        description: 'Print one task by id, from the plan or from its milestone archive (JSON). Use it for old or archived tasks.',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+        },
+    }, ({ taskId }) => captureOutput(() => runTaskShow(taskId, targetDir, { json: true })));
+    registerNativTool('milestone_archive', {
+        description: 'Archive finished milestones (comma-separated ids) after their regression suite passes. Needs a summary or summaries file.',
+        inputSchema: {
+            ids: z.string().min(1).describe('Milestone ID, or comma-separated IDs'),
+            summary: z.string().optional().describe('One-line summary (required for one milestone)'),
+            summaries: z.string().optional().describe('Path to a JSON file of milestone ID to summary'),
+            check: z.string().optional().describe('Regression command; saved as regressionCommand'),
+            timeout: z.number().int().optional().describe('Suite timeout in ms (default 10 minutes)'),
+        },
+    }, ({ ids, summary, summaries, check, timeout }) => captureOutput(() => runMilestoneArchive(ids, targetDir, { summary, summaries, check, timeout })));
     registerNativTool('task_add', {
         description: 'Append a task to .ai/master_plan.json with an auto-incremented ID (JSON). Goes to the given milestone, else the active one; ' +
             'fastPath routes it to the fast-path milestone (created on first use).',
@@ -67,8 +85,11 @@ export function createMcpServer(targetDirArg) {
             specRefs: z.array(z.string()).optional().describe('Spec anchors, e.g. ui_specs.md#appointment-list'),
             complexity: z.string().optional().describe('simple, standard or complex'),
             acceptanceCriteria: z.array(z.string()).optional().describe('Plain-language "done when" lines'),
+            verificationKind: z.string().optional().describe('unit, integration, static-config, docs, probe or manual'),
+            notes: z.string().optional().describe('Task notes; required for a manual check'),
+            newMilestone: z.string().optional().describe('Create the next milestone with this name and add the task to it'),
         },
-    }, ({ title, description, assignedSubagent, milestone, verificationCommand, targetFiles, dependencies, fastPath, specRefs, complexity, acceptanceCriteria }) => captureOutput(() => runTaskAdd(title, targetDir, {
+    }, ({ title, description, assignedSubagent, milestone, verificationCommand, targetFiles, dependencies, fastPath, specRefs, complexity, acceptanceCriteria, verificationKind, notes, newMilestone }) => captureOutput(() => runTaskAdd(title, targetDir, {
         description,
         agent: assignedSubagent,
         milestone,
@@ -78,7 +99,10 @@ export function createMcpServer(targetDirArg) {
         fastPath,
         specRefs,
         complexity,
+        kind: verificationKind,
+        notes,
         accept: acceptanceCriteria,
+        newMilestone,
         json: true,
     })));
     registerNativTool('task_start', {
@@ -107,8 +131,9 @@ export function createMcpServer(targetDirArg) {
             taskId: z.string().optional().describe('Task ID to verify. Defaults to active in_progress task.'),
             milestone: z.string().optional().describe('Filter by milestone ID or name'),
             all: z.boolean().optional().describe('Run verification commands for all completed tasks to detect regressions'),
+            isolation: z.enum(['none', 'clean']).optional().describe('In place or clean copy; default is the profile'),
         },
-    }, ({ taskId, milestone, all }) => captureOutput(() => runVerify(taskId, targetDir, { milestone, all, json: true })));
+    }, ({ taskId, milestone, all, isolation }) => captureOutput(() => runVerify(taskId, targetDir, { milestone, all, isolation, json: true })));
     registerNativTool('task_block', {
         description: 'Mark a task as blocked with a required reason (e.g. verification failed after 3 attempts).',
         inputSchema: {

package/dist/runner/agent-supervisor.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import Anthropic from '@anthropic-ai/sdk';
 import { loadMasterPlan } from '../core/verifier.js';
 import { writeJsonAtomicSync } from '../core/lock-manager.js';
+import { withArchivedAsDone } from '../core/milestone-archive.js';
 import { cacheHitRate, computeActualCostUsd, emptyActualUsage, recordRunnerUsage, } from '../core/telemetry.js';
 import { resolveProjectRoot, linkWorktreeAiDirectory, safeUnlinkWorktreeAiDirectory, linkWorktreeNodeModules, safeUnlinkWorktreeNodeModules, } from '../core/root-resolver.js';
 import { resolveWorkerModel, toNativeModelId } from '../core/model-routing.js';
@@ -316,10 +317,12 @@ export class AgentSupervisor extends EventEmitter {
         const { plan } = loadMasterPlan(this.rootDir);
         if (!plan)
             return;
+        // Archived tasks are gone from live milestones; count them as completed.
         const byId = new Map();
-        for (const milestone of plan.milestones)
+        for (const milestone of withArchivedAsDone(plan).milestones) {
             for (const t of milestone.tasks)
                 byId.set(t.id, t);
+        }
         const unmet = task.dependencies.filter((id) => byId.get(id)?.status !== 'completed');
         if (unmet.length) {
             throw new SupervisorError('UNMET_DEPENDENCIES', `Task '${task.id}' has unmet dependencies: ${unmet.join(', ')}`);

package/dist/scanner/types.d.ts

@@ -40,6 +40,8 @@ export interface MasterPlanTask {
     /** Spec anchors, e.g. "ui_specs.md#appointment-list" or "api_contracts.json#/paths/~1appointments". */
     specRefs?: string[];
     complexity?: TaskComplexity;
+    /** What kind of check proves the task; absent means unspecified. */
+    verificationKind?: VerificationKind;
     /** Plain-language "done when" lines. */
     acceptanceCriteria?: string[];
     /** Set by `task start` while in_progress: who claimed it (NATIV_AGENT_ID or --agent) and when. */
@@ -48,8 +50,22 @@ export interface MasterPlanTask {
 }
 export type TaskComplexity = 'simple' | 'standard' | 'complex';
 export declare const TASK_COMPLEXITIES: readonly TaskComplexity[];
+export type VerificationKind = 'unit' | 'integration' | 'static-config' | 'docs' | 'probe' | 'manual';
+export declare const TASK_VERIFICATION_KINDS: readonly VerificationKind[];
+/** Names that lift the human gate; a check command must never set them. */
+export declare const CHECK_OVERRIDE_NAMES: RegExp;
 /** Lists every structural problem with a task; empty when the task is valid. */
 export declare function validateMasterPlanTask(task: unknown): string[];
+/** What the plan keeps about a milestone whose tasks moved to an archive file. */
+export interface MilestoneArchiveInfo {
+    summary: string;
+    commit: string | null;
+    check: string;
+    archivedAt: string;
+    taskCount: number;
+    taskIds: string[];
+    file: string;
+}
 export interface MasterPlanMilestone {
     id: string;
     name: string;
@@ -57,6 +73,8 @@ export interface MasterPlanMilestone {
     tasks: MasterPlanTask[];
     /** True for the milestone that collects fast-path tasks. */
     fastPath?: boolean;
+    /** Set when the tasks live in an archive file; `tasks` is then empty. */
+    archived?: MilestoneArchiveInfo;
 }
 export interface MasterPlan {
     $schema?: string;

package/dist/scanner/types.js

@@ -17,6 +17,11 @@ export function isSubagentType(value) {
 }
 export const TASK_STATUSES = ['pending', 'in_progress', 'completed', 'blocked'];
 export const TASK_COMPLEXITIES = ['simple', 'standard', 'complex'];
+export const TASK_VERIFICATION_KINDS = [
+    'unit', 'integration', 'static-config', 'docs', 'probe', 'manual',
+];
+/** Names that lift the human gate; a check command must never set them. */
+export const CHECK_OVERRIDE_NAMES = /NATIV_(CI|HEADLESS)_OVERRIDE/;
 /** Lists every structural problem with a task; empty when the task is valid. */
 export function validateMasterPlanTask(task) {
     if (!task || typeof task !== 'object' || Array.isArray(task))
@@ -33,6 +38,9 @@ export function validateMasterPlanTask(task) {
         errors.push(`${label}: "description" must be a string`);
     if (typeof t.verificationCommand !== 'string')
         errors.push(`${label}: "verificationCommand" must be a string`);
+    if (typeof t.verificationCommand === 'string' && CHECK_OVERRIDE_NAMES.test(t.verificationCommand)) {
+        errors.push(`${label}: "verificationCommand" must not set NATIV_CI_OVERRIDE or NATIV_HEADLESS_OVERRIDE`);
+    }
     if (typeof t.assignedSubagent !== 'string' || !isSubagentType(t.assignedSubagent)) {
         errors.push(`${label}: "assignedSubagent" must be one of ${SUBAGENT_TYPES.join(', ')}`);
     }
@@ -54,6 +62,9 @@ export function validateMasterPlanTask(task) {
     if (t.complexity !== undefined && !TASK_COMPLEXITIES.includes(t.complexity)) {
         errors.push(`${label}: "complexity" must be one of ${TASK_COMPLEXITIES.join(', ')}`);
     }
+    if (t.verificationKind !== undefined && !TASK_VERIFICATION_KINDS.includes(t.verificationKind)) {
+        errors.push(`${label}: "verificationKind" must be one of ${TASK_VERIFICATION_KINDS.join(', ')}`);
+    }
     return errors;
 }
 export const ESCALATION_TYPES = [

package/dist/server/routes/task-routes.d.ts

@@ -70,6 +70,7 @@ export declare function handlePipelineTasks(root: string): {
             fastPath?: boolean;
             specRefs?: string[];
             complexity?: import("../../scanner/types.js").TaskComplexity;
+            verificationKind?: import("../../scanner/types.js").VerificationKind;
             acceptanceCriteria?: string[];
             claimedBy?: string;
             claimedAt?: string;
@@ -78,6 +79,7 @@ export declare function handlePipelineTasks(root: string): {
         name: string;
         status: "pending" | "in_progress" | "completed";
         fastPath?: boolean;
+        archived?: import("../../scanner/types.js").MilestoneArchiveInfo;
     }[];
 };
 /** POST /api/pipeline/tasks/action: the same lock-guarded transitions as `nativ task start|complete|block`. */