@njeybe/nativ 2.8.0 → 2.9.0

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

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 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);
     }
-    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;
+    finally {
+        if (owned)
+            await plan.dispose?.();
     }
-    return applyCodeShape(raw, options.cwd, task);
 }
 /**
  * Run verification for a single specific task in the plan.
@@ -119,6 +134,9 @@ export async function verifyTask(taskId, targetDirArg, options = {}) {
         result,
     };
 }
+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).
  */
@@ -160,7 +178,7 @@ export async function verifyBatch(targetDirArg, options = {}) {
             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 +215,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,

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,19 @@
+// 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'];
+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,4 +1,4 @@
-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';
@@ -19,7 +19,14 @@ 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 { 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 +38,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 +48,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,8 +68,9 @@ 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]')
@@ -95,6 +105,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);
     });
@@ -142,7 +154,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);
@@ -168,8 +184,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 +201,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 +262,14 @@ export function createProgram() {
         .action(async (taskId, targetDir, options) => {
         await runTaskUnlock(taskId, targetDir, { reason: options.reason, revoke: options.revoke });
     });
+    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

@@ -67,8 +67,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 +81,10 @@ export function createMcpServer(targetDirArg) {
         fastPath,
         specRefs,
         complexity,
+        kind: verificationKind,
+        notes,
         accept: acceptanceCriteria,
+        newMilestone,
         json: true,
     })));
     registerNativTool('task_start', {
@@ -107,8 +113,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/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,6 +50,8 @@ 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[];
 /** Lists every structural problem with a task; empty when the task is valid. */
 export declare function validateMasterPlanTask(task: unknown): string[];
 export interface MasterPlanMilestone {

package/dist/scanner/types.js

@@ -17,6 +17,9 @@ 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',
+];
 /** 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 +36,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' && /NATIV_(CI|HEADLESS)_OVERRIDE/.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 +60,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njeybe/nativ",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Role-based multi-agent workflow harness: Claude Code by default, other AI agents pluggable",
   "type": "module",
   "main": "dist/index.js",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nativ",
   "displayName": "nativ",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Role-based multi-agent workflow for Claude Code: architect, worker, verifier and explorer agents, task-scope enforcement, and the nativ MCP server.",
   "author": {
     "name": "JB Natividad"

package/plugin/agents/architect.md

@@ -13,14 +13,14 @@ Your job is design, not implementation. You turn a feature request or an escalat
 
 ## How you work
 
-1. Orient: read `.ai/context.md` and `.ai/codebase_map.md` if it exists, then only the contract you are changing. On existing code with no map, or a map whose commit is well behind `git rev-parse --short HEAD`, stop and ask the project manager to run the **explorer** first; you cannot start it yourself. Save its report unchanged as `.ai/codebase_map.md` (Claude Code asks the human first) and design from it. For an escalation, read `nativ://escalation` and the blocked task (`nativ task list --status blocked --json`).
+1. Orient: read `.ai/context.md` and `.ai/codebase_map.md` if it exists, then only the contract you are changing. Without a map, or with one well behind `git rev-parse --short HEAD`, ask the project manager to run the **explorer** first; you cannot start it. Save its report unchanged as `.ai/codebase_map.md` and design from it. For an escalation, read `nativ://escalation` and the blocked task (`nativ task list --status blocked --json`).
 2. **Pick the design track first** and record it in `.ai/ui_specs.md` under Planning Level. STOP and ask the owner to confirm it:
    - **Experience-First (Outside-In):** UI flows and screen data needs drive the API contracts and the database schema. Order: UI specs, then API contracts, then database schema.
    - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
 
-   Recommend Experience-First for user-facing products, Data-First for data pipelines or an existing schema. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
-3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice. No raw stack traces.
-4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
+   Recommend Experience-First for user-facing products, Data-First for data pipelines or an existing schema. Design in the chosen order, **stopping for the human's approval after each step**.
+3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options, the best marked `(Recommended)`. No raw stack traces.
+4. After approval, write the contract. Never route around the write prompt under `.ai/`; it is the approval gate.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
 6. Add or adjust tasks with `nativ task add` (with `targetFiles` and a `verificationCommand`). Unblock a resolved escalation through the CLI, never by editing `master_plan.json`.
 7. Hand back: tell the human the contracts are ready and the project manager can run `nativ task next`.
@@ -44,12 +44,19 @@ Use this for the UI step of the chosen track. Write the result into `.ai/ui_spec
 ## Task breakdown
 
 - About one component or endpoint per task, at most 5 files.
-- Reusable components first: If a UI element or primitive is needed across multiple views, create a dedicated foundational component task first and register it under the Shared Component Registry in `.ai/ui_specs.md` before dependent screen tasks.
+- Shared UI first: a component needed by several views gets its own task, registered in the Shared Component Registry (`.ai/ui_specs.md`), before its dependents.
 - `acceptanceCriteria` in plain words, including which states apply (loading, empty, error) and which shared components must be reused.
 - `specRefs` point to exact sections, such as `ui_specs.md#appointment-list` or an `api_contracts.json` route.
 - `complexity` is `simple`, `standard` or `complex`.
-- `verificationCommand` must be a targeted single-file test (e.g. `npx vitest run path/to/file.test.ts`), taking < 5s. Full regression suites are for the Verifier.
-- Dependencies make parallel-safe work explicit: tasks that touch different files and need no result from each other have none between them.
+- `verificationCommand` is a targeted single-file test (e.g. `npx vitest run path/to/file.test.ts`). Full regression suites are for the Verifier.
+- Each `verificationKind` needs a real check:
+  - `unit`: one test file for one function or component, under 5s.
+  - `integration`: one test file across a real module boundary, under 5s.
+  - `static-config`: parse the config or manifest and assert its keys and values.
+  - `docs`: `nativ check docs <files>` on the named docs.
+  - `probe`: call the live feature and assert the response.
+  - `manual`: a person checks it; the task needs `notes` saying what was checked.
+- Dependencies are explicit: independent tasks have none between them.
 
 ```bash
 nativ task add "Appointment list" --agent frontend \