@njeybe/nativ 2.8.0 → 2.9.1

package/dist/core/setup/pm-playbook.js

@@ -19,7 +19,13 @@ When told to run autonomously ("run the queue", "execute milestone", AFK mode):
 2. Delegate to the \`worker\` agent with the task id and recommended model.
 3. The worker completes the task itself; \`nativ task complete\` already ran the check. Do not run \`nativ_verify\` or \`nativ_task_complete\` again for it.
 4. Loop to the next task immediately, without asking the human.
-5. Stop only when the milestone is done (ask the \`verifier\` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).
+5. Stop only when the milestone is done or when a task is blocked or escalated (present the four-part summary).
+
+## Finished milestones
+
+- Ask the \`verifier\` for the milestone check. If it passes, run \`nativ milestone archive <id> --summary "<one line>"\` (MCP: \`nativ_milestone_archive\`).
+- Tell the human what was archived, then suggest \`/clear\`: the plan holds the state, so a fresh context loses nothing.
+- For an old task, use \`nativ task show <id>\` instead of opening the plan.
 
 ## Talking to the human
 

package/dist/core/setup/session-context.d.ts

@@ -1,4 +1,12 @@
 /** A few lines of orientation for a new Claude Code session, or null when this is not a nativ project. */
 export declare function buildSessionContext(cwd: string, env?: NodeJS.ProcessEnv): string | null;
+/** Marks the plugin's copy of the hook so it can stay silent when the project has its own. */
+export declare const FROM_PLUGIN_FLAG = "--from-plugin";
+export interface SessionContextOptions {
+    /** Set by the plugin's hook: stay silent when the project already runs the hook. */
+    fromPlugin?: boolean;
+}
+/** True when .claude/settings.json already runs `nativ hook context` without the plugin flag. */
+export declare function projectHasNativSessionHook(root: string): boolean;
 /** `nativ hook context`: prints the SessionStart hook output. Never throws and always prints valid JSON or nothing. */
-export declare function runSessionContext(targetDirArg?: string, write?: (text: string) => void): void;
+export declare function runSessionContext(targetDirArg?: string, write?: (text: string) => void, options?: SessionContextOptions): void;

package/dist/core/setup/session-context.js

@@ -85,10 +85,32 @@ export function buildSessionContext(cwd, env = process.env) {
         lines.push('', PM_PLAYBOOK);
     return lines.join('\n');
 }
+/** Marks the plugin's copy of the hook so it can stay silent when the project has its own. */
+export const FROM_PLUGIN_FLAG = '--from-plugin';
+/** True when .claude/settings.json already runs `nativ hook context` without the plugin flag. */
+export function projectHasNativSessionHook(root) {
+    let settings;
+    try {
+        settings = parseJsonLoose(fs.readFileSync(path.join(root, '.claude', 'settings.json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const commands = (settings.hooks?.SessionStart ?? []).flatMap((group) => group.hooks ?? []);
+    return commands.some(({ command }) => {
+        if (typeof command !== 'string' || command.includes(FROM_PLUGIN_FLAG))
+            return false;
+        return /\bhook context\b/.test(command) && /nativ|cli\.js/.test(command);
+    });
+}
 /** `nativ hook context`: prints the SessionStart hook output. Never throws and always prints valid JSON or nothing. */
-export function runSessionContext(targetDirArg, write = (t) => process.stdout.write(t)) {
+export function runSessionContext(targetDirArg, write = (t) => process.stdout.write(t), options = {}) {
     try {
-        const context = buildSessionContext(targetDirArg ? path.resolve(targetDirArg) : process.env.CLAUDE_PROJECT_DIR || process.cwd());
+        const cwd = targetDirArg ? path.resolve(targetDirArg) : process.env.CLAUDE_PROJECT_DIR || process.cwd();
+        // With both installs, the project hook prints the orientation and the plugin's copy stays quiet.
+        if (options.fromPlugin && projectHasNativSessionHook(resolveProjectRoot(cwd)))
+            return;
+        const context = buildSessionContext(cwd);
         if (context)
             write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context } }));
     }

package/dist/core/setup/setup-planner.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MCP_SERVER_NAME, AGENT_FILES, resolveCliInvocation, isMachineBoundPath, stampManaged, managedState, } from './types.js';
 import { buildDesiredConfig, mergeClaudeSettings, mergeMcpConfig, isObject, } from './config-merger.js';
+import { applyBlock, listGeneratedPaths, trackedNativPaths } from './gitignore-block.js';
 import { loadEnforcementMode, parseJsonLoose } from '../enforcement.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export function getTemplatesDir() {
@@ -44,6 +45,18 @@ export function configuredInvocation(root) {
         return null;
     }
 }
+/** Disk-derived paths plus files this run creates, in a fixed order so reruns match. */
+function blockPaths(root, visibility, changes) {
+    const disk = listGeneratedPaths(root, visibility);
+    if (visibility === 'shared')
+        return disk;
+    const created = new Set(changes.filter((c) => c.action === 'created').map((c) => `/${c.path}`));
+    const canonical = [
+        '/.ai/', '/.nativ/', '/.worktrees/', '/AGENTS.md', '/CLAUDE.md', '/GEMINI.md',
+        ...AGENT_FILES.map((f) => `/.claude/agents/${f}`), '/.mcp.json', '/.claude/settings.json',
+    ];
+    return canonical.filter((p) => disk.includes(p) || created.has(p));
+}
 /** Computes what `nativ setup` would do, without touching disk. */
 export function planSetup(rootArg, options = {}) {
     const root = path.resolve(rootArg);
@@ -55,6 +68,7 @@ export function planSetup(rootArg, options = {}) {
     const changes = [];
     const warnings = [];
     const writes = new Map();
+    let visibility = options.gitVisibility ?? 'hidden';
     if (!invocation.portable) {
         warnings.push('nativ is not on PATH, so the generated config points at this machine\'s install. ' +
             'Install it globally (npm i -g @njeybe/nativ) or pass --command "npx -y @njeybe/nativ" so the config works for your team.');
@@ -143,7 +157,7 @@ export function planSetup(rootArg, options = {}) {
     for (const [file, title] of [['CLAUDE.md', 'Claude Code'], ['GEMINI.md', 'Gemini / Antigravity']]) {
         const existing = readText(path.join(root, file));
         if (existing === null)
-            record(file, null, `# ${title} directive\n\n@AGENTS.md\n`);
+            record(file, null, stampManaged(`# ${title} directive\n\n@AGENTS.md\n`));
         else
             changes.push({ path: file, action: 'unchanged', detail: /AGENTS\.md/.test(existing) ? undefined : 'exists; does not reference AGENTS.md' });
     }
@@ -160,9 +174,21 @@ export function planSetup(rootArg, options = {}) {
             next.enforcement = loadEnforcementMode(root);
             detail = `enforcement=${String(next.enforcement)}`;
         }
+        if (options.gitVisibility && next.gitVisibility !== options.gitVisibility) {
+            next.gitVisibility = options.gitVisibility;
+            detail = [detail, `gitVisibility=${options.gitVisibility}`].filter(Boolean).join(', ');
+        }
         record('.nativ/config.json', config.text, detail || config.text === null ? serializeJson(next) : (config.text ?? ''), detail);
+        visibility = options.gitVisibility ?? (next.gitVisibility === 'shared' ? 'shared' : 'hidden');
     }
-    return { root, invocation, changes, warnings, writes };
+    // .gitignore: the managed block, from what is on disk plus what this run creates
+    const paths = blockPaths(root, visibility, changes);
+    const ignore = readText(path.join(root, '.gitignore'));
+    record('.gitignore', ignore, applyBlock(ignore, paths), 'nativ block');
+    const gitRmCommand = trackedNativPaths(root, paths).command;
+    if (gitRmCommand)
+        warnings.push(`nativ files are already tracked by git. To stop tracking them, run: ${gitRmCommand}`);
+    return { root, invocation, changes, warnings, writes, gitRmCommand: gitRmCommand || undefined };
 }
 /** Writes the planned differences. Idempotent: applying twice changes nothing the second time. */
 export function applySetup(rootArg, options = {}) {
@@ -176,5 +202,12 @@ export function applySetup(rootArg, options = {}) {
             fs.renameSync(tmp, file);
         }
     }
-    return { root: plan.root, dryRun: options.dryRun === true, invocation: plan.invocation, changes: plan.changes, warnings: plan.warnings };
+    return {
+        root: plan.root,
+        dryRun: options.dryRun === true,
+        invocation: plan.invocation,
+        changes: plan.changes,
+        warnings: plan.warnings,
+        gitRmCommand: plan.gitRmCommand,
+    };
 }

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

@@ -1,4 +1,5 @@
 import type { EnforcementMode } from '../enforcement.js';
+import type { GitVisibility } from './gitignore-block.js';
 export declare const MCP_SERVER_NAME = "nativ";
 export declare const AGENT_FILES: readonly ["architect.md", "worker.md", "verifier.md", "explorer.md"];
 export declare const MANAGED_PREFIX = "<!-- nativ:managed sha256=";
@@ -27,6 +28,8 @@ export interface SetupOptions {
     enforcement?: EnforcementMode;
     /** Also overwrite agent files that were edited by hand or are not nativ's. */
     force?: boolean;
+    /** Whether nativ's files stay out of git (hidden, the default) or are shared with the team. */
+    gitVisibility?: GitVisibility;
     hasBinary?: (name: string) => boolean;
     templatesDir?: string;
 }
@@ -37,6 +40,8 @@ export interface SetupPlan {
     warnings: string[];
     /** Full new content per changed path, keyed by the same relative path. */
     writes: Map<string, string>;
+    /** `git rm --cached` command for nativ files git already tracks; never run by nativ. */
+    gitRmCommand?: string;
 }
 export interface SetupResult {
     root: string;
@@ -44,6 +49,7 @@ export interface SetupResult {
     invocation: CliInvocation;
     changes: AssetChange[];
     warnings: string[];
+    gitRmCommand?: string;
 }
 export interface TemplateFilePlan {
     action: AssetAction;

package/dist/core/verifier/clean-tree.d.ts

@@ -0,0 +1,14 @@
+export declare const CLEAN_TREE_PREFIX = "nativ-verify-";
+export type CleanTree = {
+    ok: true;
+    dir: string;
+    dispose: () => Promise<void>;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function disposeTree(root: string, dir: string, names: string[], unlink?: (dir: string, name: string) => boolean): Promise<void>;
+export declare function createCleanTree(root: string, opts?: {
+    links?: string[];
+}): Promise<CleanTree>;
+export declare function sweepStaleCleanTrees(root: string): Promise<number>;

package/dist/core/verifier/clean-tree.js

@@ -0,0 +1,151 @@
+import { execFile } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { linkWorktreeDir, safeUnlinkWorktreeDir } from '../root-resolver.js';
+export const CLEAN_TREE_PREFIX = 'nativ-verify-';
+const STALE_MS = 60 * 60 * 1000;
+function git(cwd, args) {
+    const opts = { cwd, maxBuffer: 64 * 1024 * 1024, windowsHide: true };
+    return new Promise((resolve) => {
+        execFile('git', args, opts, (err, stdout) => {
+            const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+            resolve({ code, out: String(stdout ?? '') });
+        });
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function removeDir(dir) {
+    for (let i = 0; i < 6; i++) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            if (!fs.existsSync(dir))
+                return;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'EBUSY' && code !== 'EPERM' && code !== 'ENOTEMPTY')
+                return;
+        }
+        await sleep(150 * (i + 1));
+    }
+}
+// Links go first: removing a tree can follow a junction into the real folder.
+function linkRemains(dir, names) {
+    return names.some((n) => {
+        try {
+            return fs.lstatSync(path.join(dir, n)).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+// unlink is injectable so tests can simulate a link that refuses to go away.
+export async function disposeTree(root, dir, names, unlink = safeUnlinkWorktreeDir) {
+    try {
+        for (const n of names)
+            unlink(dir, n);
+        // A surviving link means a recursive delete could reach the real folder: leave it for the sweep.
+        if (linkRemains(dir, names))
+            return;
+        for (let i = 0; i < 4; i++) {
+            const r = await git(root, ['worktree', 'remove', '--force', dir]);
+            if (r.code === 0 || !fs.existsSync(dir))
+                break;
+            await sleep(150 * (i + 1));
+        }
+        await removeDir(dir);
+        await git(root, ['worktree', 'prune']);
+    }
+    catch {
+        // Cleanup never throws.
+    }
+}
+async function copyUntracked(root, dir) {
+    const r = await git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    for (const rel of r.out.split('\0').filter(Boolean)) {
+        const from = path.join(root, rel);
+        const to = path.join(dir, rel);
+        try {
+            if (!fs.statSync(from).isFile())
+                continue;
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(from, to);
+        }
+        catch {
+            // A file that vanished mid-copy is not worth failing the tree.
+        }
+    }
+}
+export async function createCleanTree(root, opts = {}) {
+    const inRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
+    if (inRepo.code !== 0)
+        return { ok: false, reason: 'clean isolation needs a git repository' };
+    const head = await git(root, ['rev-parse', '--verify', 'HEAD']);
+    if (head.code !== 0)
+        return { ok: false, reason: 'clean isolation needs at least one commit' };
+    const stash = await git(root, ['stash', 'create']);
+    const commit = stash.code === 0 && stash.out.trim() ? stash.out.trim() : head.out.trim();
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), CLEAN_TREE_PREFIX));
+    fs.rmdirSync(dir);
+    const args = ['-c', 'core.autocrlf=false', 'worktree', 'add', '--detach', dir, commit];
+    const add = await git(root, args);
+    if (add.code !== 0) {
+        await removeDir(dir);
+        return { ok: false, reason: 'could not create the clean tree' };
+    }
+    await copyUntracked(root, dir);
+    const linked = (opts.links ?? []).filter((n) => linkWorktreeDir(dir, root, n));
+    return { ok: true, dir, dispose: () => disposeTree(root, dir, linked) };
+}
+function ownedBy(root, dir) {
+    try {
+        const text = fs.readFileSync(path.join(dir, '.git'), 'utf8');
+        const gitdir = text.replace(/^gitdir:\s*/, '').trim();
+        const main = realOf(path.resolve(root, '.git')).toLowerCase();
+        return realOf(path.resolve(gitdir)).toLowerCase().startsWith(main);
+    }
+    catch {
+        return false;
+    }
+}
+// Real paths make Windows short (8.3) and aliased paths compare equal.
+function realOf(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+function linkNames(dir) {
+    return fs.readdirSync(dir).filter((n) => fs.lstatSync(path.join(dir, n)).isSymbolicLink());
+}
+export async function sweepStaleCleanTrees(root) {
+    let removed = 0;
+    try {
+        const tmp = os.tmpdir();
+        for (const name of fs.readdirSync(tmp)) {
+            if (!name.startsWith(CLEAN_TREE_PREFIX))
+                continue;
+            const dir = path.join(tmp, name);
+            try {
+                if (Date.now() - fs.statSync(dir).mtimeMs < STALE_MS)
+                    continue;
+                if (!ownedBy(root, dir))
+                    continue;
+                await disposeTree(root, dir, linkNames(dir));
+                if (!fs.existsSync(dir))
+                    removed++;
+            }
+            catch {
+                // Skip entries we cannot read.
+            }
+        }
+    }
+    catch {
+        // Nothing to sweep.
+    }
+    return removed;
+}

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

@@ -2,4 +2,6 @@ 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>;
+export declare function executeVerification(command: string, cwd: string, timeoutMs?: number, options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<VerificationResult>;

package/dist/core/verifier/executor.js

@@ -1,8 +1,9 @@
-import { exec } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
+const MAX_OUTPUT = 10 * 1024 * 1024;
 /**
  * Execute a verification command in the workspace directory with timeout and output capture.
  */
-export async function executeVerification(command, cwd, timeoutMs = 120_000) {
+export async function executeVerification(command, cwd, timeoutMs = 120_000, options = {}) {
     const trimmed = (command || '').trim();
     // Treat empty, 'none', or 'skip' as an informational pass
     if (!trimmed || trimmed.toLowerCase() === 'none' || trimmed.toLowerCase() === 'skip') {
@@ -26,37 +27,59 @@ export async function executeVerification(command, cwd, timeoutMs = 120_000) {
     }
     const start = Date.now();
     return new Promise((resolve) => {
-        exec(finalCommand, {
+        let timedOut = false;
+        let out = '';
+        let errOut = '';
+        const child = spawn(finalCommand, {
             cwd,
-            timeout: timeoutMs,
-            maxBuffer: 10 * 1024 * 1024,
-            env: process.env,
-        }, (err, stdout, stderr) => {
+            shell: true,
+            env: options.env ?? { ...process.env, NATIV_VERIFY_SANDBOX: '1' },
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+        });
+        const cap = (cur, chunk) => cur.length < MAX_OUTPUT ? cur + chunk.toString() : cur;
+        child.stdout?.on('data', (c) => (out = cap(out, c)));
+        child.stderr?.on('data', (c) => (errOut = cap(errOut, c)));
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+        }, timeoutMs);
+        const finish = (code, message) => {
+            clearTimeout(timer);
             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,
-                });
+            if (code === 0 && !message && !timedOut) {
+                resolve({ success: true, exitCode: 0, command: trimmed, stdout: out, stderr: errOut, durationMs });
+                return;
             }
-        });
+            const error = timedOut
+                ? `Command timed out after ${timeoutMs}ms`
+                : message ?? `Command failed: ${trimmed}`;
+            resolve({
+                success: false,
+                exitCode: typeof code === 'number' && code !== 0 ? code : 1,
+                command: trimmed,
+                stdout: out,
+                stderr: errOut || error,
+                durationMs,
+                error,
+            });
+        };
+        child.on('error', (e) => finish(null, e.message));
+        child.on('close', (code) => finish(code));
     });
 }
+/** Kills the process and all its descendants. */
+function killTree(pid) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        execFile('taskkill', ['/pid', String(pid), '/T', '/F'], () => { });
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // Group already gone
+    }
+}

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

@@ -0,0 +1,25 @@
+import { MasterPlanTask } from '../../scanner/types.js';
+import type { PhasesOutcome, VerificationResult } from './types.js';
+/** Where a verification runs: the real tree, or a disposable clean copy. */
+export interface IsolationPlan {
+    mode: 'none' | 'clean';
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+    warnings: string[];
+    dispose?: () => Promise<void>;
+}
+export declare const NO_ISOLATION: IsolationPlan;
+export declare function needsRun(commands: string[], configDir: string, sharedPhases: boolean): boolean;
+export declare function openIsolation(cwd: string, configDir: string, wanted: 'none' | 'clean'): Promise<IsolationPlan>;
+/** Like runVerifyPhases, but with an explicit environment for each phase. */
+export declare function runPhasesIn(dir: string, configDir: string, timeout: number | undefined, env?: NodeJS.ProcessEnv): Promise<PhasesOutcome>;
+export interface RunOptions {
+    cwd: string;
+    configDir?: string;
+    timeout?: number;
+    phases?: PhasesOutcome;
+    isolation?: 'none' | 'clean';
+    plan?: IsolationPlan;
+}
+export declare function runInPlan(task: MasterPlanTask, o: RunOptions, plan: IsolationPlan): Promise<VerificationResult>;
+export declare function diagnose(task: MasterPlanTask, o: RunOptions, failed: VerificationResult, failure: 'warn' | 'block'): Promise<VerificationResult>;

package/dist/core/verifier/isolation.js

@@ -0,0 +1,77 @@
+import { loadVerifySettings } from '../profiles.js';
+import { resolveMainRoot } from '../root-resolver.js';
+import { executeVerification } from './executor.js';
+import { createCleanTree, sweepStaleCleanTrees } from './clean-tree.js';
+import { lintPortability } from './portability-lint.js';
+import { buildVerifyEnv } from './verify-env.js';
+import { loadVerifyPhases, runVerifyPhases } from './phases.js';
+export const NO_ISOLATION = { mode: 'none', warnings: [] };
+function isSkipped(command) {
+    const t = (command || '').trim().toLowerCase();
+    return !t || t === 'none' || t === 'skip';
+}
+export function needsRun(commands, configDir, sharedPhases) {
+    if (commands.some((c) => !isSkipped(c)))
+        return true;
+    return !sharedPhases && loadVerifyPhases(configDir).phases.length > 0;
+}
+export async function openIsolation(cwd, configDir, wanted) {
+    if (wanted !== 'clean')
+        return NO_ISOLATION;
+    await sweepStaleCleanTrees(cwd);
+    const settings = loadVerifySettings(resolveMainRoot(configDir));
+    const tree = await createCleanTree(cwd, { links: settings.verifyLinks });
+    if (!tree.ok) {
+        return { mode: 'none', warnings: [`Clean isolation unavailable (${tree.reason}); ran in place.`] };
+    }
+    const env = buildVerifyEnv(settings.verifyEnv);
+    return { mode: 'clean', dir: tree.dir, env, warnings: [], dispose: tree.dispose };
+}
+/** Like runVerifyPhases, but with an explicit environment for each phase. */
+export async function runPhasesIn(dir, configDir, timeout, env) {
+    const config = loadVerifyPhases(configDir);
+    if (!env || config.error)
+        return runVerifyPhases(dir, configDir, timeout);
+    const reports = [];
+    for (const phase of config.phases) {
+        const res = await executeVerification(phase.run, dir, timeout, { env });
+        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 phases then the task command, in the plan's directory; code-shape is not part of this.
+export async function runInPlan(task, o, plan) {
+    const configDir = o.configDir ?? o.cwd;
+    const dir = plan.dir ?? o.cwd;
+    const outcome = o.phases ?? (await runPhasesIn(dir, configDir, o.timeout, plan.env));
+    // 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, ...(o.phases ? { durationMs: 0 } : {}) };
+    }
+    const raw = await executeVerification(task.verificationCommand, dir, o.timeout, { env: plan.env });
+    if (outcome.reports.length) {
+        raw.phases = outcome.reports;
+        raw.durationMs += o.phases ? 0 : outcome.reports.reduce((sum, r) => sum + r.durationMs, 0);
+        raw.skipped = false;
+    }
+    return raw;
+}
+// A clean failure is re-run in place only to learn whether the clean copy is the cause.
+export async function diagnose(task, o, failed, failure) {
+    if (failed.error?.startsWith('Command timed out'))
+        return failed;
+    const local = await runInPlan(task, { ...o, phases: undefined }, NO_ISOLATION);
+    if (!local.success)
+        return failed;
+    const base = 'Passes only on this machine: it failed in a clean copy of the project.';
+    const note = [base, ...lintPortability(o.cwd, task.targetFiles || [])].join(' ');
+    if (failure === 'warn') {
+        return { ...local, isolation: 'clean', warnings: [...(failed.warnings ?? []), note] };
+    }
+    const error = `${failed.error ?? 'Verification failed'}. ${note} Isolation failure is set to block.`;
+    return { ...failed, error, warnings: [...(failed.warnings ?? []), note] };
+}

package/dist/core/verifier/portability-lint.d.ts

@@ -0,0 +1,2 @@
+export declare function isPortabilityTarget(file: string): boolean;
+export declare function lintPortability(cwd: string, targetFiles: string[]): string[];

package/dist/core/verifier/portability-lint.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const TEST_DIR = /(^|\/)(test|tests|__tests__|scripts)\//;
+const TEST_NAME = /(\.test\.|\.spec\.)|(^|\/)test_[^/]*\.py$|_test\.go$/;
+const LITERAL = /(["'`])([^"'`\n$]{3,200}?)\1/g;
+const SPAWN_NATIV = /(spawn|spawnSync|exec|execSync|execFile|execFileSync)\(\s*['"`]nativ\b/;
+const AI_HINT = 'track a fixture copy in the repo instead';
+export function isPortabilityTarget(file) {
+    const f = file.split(String.fromCharCode(92)).join('/');
+    return TEST_DIR.test(f) || TEST_NAME.test(f);
+}
+function looksLikePath(s) {
+    if (/^[a-z]+:\/\//i.test(s) || /\s/.test(s) || s.startsWith('-'))
+        return false;
+    return /^\.{0,2}\/?[\w.@-]+(\/[\w.@-]+)+\/?$/.test(s) || /^\.[\w-]+(\/|$)/.test(s);
+}
+function scan(cwd, file, hits, spawns) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(cwd, file), 'utf8');
+    }
+    catch {
+        return;
+    }
+    text.split(/\r?\n/).forEach((line, i) => {
+        if (SPAWN_NATIV.test(line))
+            spawns.push(`${file}:${i + 1} spawns nativ, which may not be installed in CI`);
+        for (const m of line.matchAll(LITERAL)) {
+            if (looksLikePath(m[2]))
+                hits.push({ file, line: i + 1, lit: m[2] });
+        }
+    });
+}
+function ignoredSet(cwd, paths) {
+    const r = spawnSync('git', ['check-ignore', '--stdin'], {
+        cwd, input: paths.join('\n'), encoding: 'utf8',
+    });
+    if (r.error || (r.status !== 0 && r.status !== 1))
+        return null;
+    return new Set(r.stdout.split(/\r?\n/).filter(Boolean));
+}
+// Cheap warning pass: findings only, never changes a result.
+export function lintPortability(cwd, targetFiles) {
+    const files = targetFiles.map((f) => f.split(String.fromCharCode(92)).join('/')).filter(isPortabilityTarget);
+    if (!files.length)
+        return [];
+    const hits = [];
+    const out = [];
+    for (const f of files)
+        scan(cwd, f, hits, out);
+    const uniq = [...new Set(hits.map((h) => h.lit.replace(/^\.\//, '')))];
+    const ignored = uniq.length ? ignoredSet(cwd, uniq) : new Set();
+    if (!ignored)
+        return [];
+    for (const h of hits) {
+        const key = h.lit.replace(/^\.\//, '');
+        if (!ignored.has(key) && !ignored.has(`${key}/`))
+            continue;
+        const hint = key.startsWith('.ai/') ? `; ${AI_HINT}` : '';
+        out.push(`${h.file}:${h.line} reads ${h.lit}, which is gitignored: this check cannot run in CI${hint}`);
+    }
+    return out;
+}

package/dist/core/verifier/skip-policy.d.ts

@@ -0,0 +1,8 @@
+import { MasterPlanTask } from '../../scanner/types.js';
+export type SkipMode = 'allow' | 'warn' | 'block';
+export interface SkipDecision {
+    action: 'pass' | 'warn' | 'block';
+    message?: string;
+}
+/** Decides what a skipped check (empty, none or skip) means for a task under the profile. */
+export declare function evaluateSkip(task: MasterPlanTask, mode: SkipMode): SkipDecision;

package/dist/core/verifier/skip-policy.js

@@ -0,0 +1,13 @@
+const FIX = 'Add a real verificationCommand, or set verificationKind "manual" with notes saying how it was checked.';
+/** Decides what a skipped check (empty, none or skip) means for a task under the profile. */
+export function evaluateSkip(task, mode) {
+    if (task.verificationKind === 'manual' && (task.notes ?? '').trim())
+        return { action: 'pass' };
+    if (mode === 'allow')
+        return { action: 'pass' };
+    const why = `Task [${task.id}] has no real check, so nothing proves it works. ${FIX}`;
+    // Older plans without a kind only warn, so work already in progress does not stall.
+    if (mode === 'block' && task.verificationKind !== undefined)
+        return { action: 'block', message: why };
+    return { action: 'warn', message: why };
+}