@njeybe/nativ 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2.9.0
+
+### Added
+
+- **Clean checks.** A task's check runs in a throwaway copy of the repo with only the files git ships and a minimal environment. Defaults: prototype off, solo on, enterprise on. Use `--isolation none|clean` (or `--clean`) on `nativ verify` and `nativ task complete`. Under enterprise, `--isolation none` on `task complete` needs an interactive terminal. Config keys: `verifyIsolation`, `verifyIsolationFailure`, `verifyEnv`, `verifyLinks`.
+- **Portability warnings.** When a check passes only on your machine, a failure in the clean copy warns "Passes only on this machine". nativ names the test lines that read gitignored files or spawn `nativ`.
+- **Check types.** Tasks take a `verificationKind` (unit, integration, static-config, docs, probe, manual) through `nativ task add --kind`, plus `--notes`. `--kind docs` defaults its check to `nativ check docs`. A manual task needs notes.
+- **Skipped-check policy.** `skippedCheck` allows a skip in prototype, warns in solo and blocks in enterprise. A skip passes quietly only for a manual task with notes. Tasks with no kind only warn.
+- **`nativ check docs <files>`.** Checks backticked file paths, `<PLACEHOLDER>` tokens against the file the paragraph names, setting names used in assignments or as variable references, and nativ subcommands and flags. Supports `--json`. Skip lines with `<!-- nativ-check-ignore -->`, or wrap them in the `-start` and `-end` pair.
+- **Fail-loud config rule.** Code-shape reports "config" findings for reads of settings that silently fall back to empty, such as `?? ''`, `|| ''`, `?? null`, Python `os.getenv('X', '')` and unchecked Go `os.Getenv`. Setting: `codeStyle.configFallback` (off, warn or block; default warn). Opt out per line with `nativ-allow-fallback`.
+- **nativ stays out of git.** `nativ init`, `setup` and `update` add a managed `# >>> nativ (managed) >>>` block to the project's `.gitignore`, listing only files nativ generated. `--git-visibility hidden|shared` sets it (default hidden); shared keeps only secret and machine files ignored. `nativ doctor` warns when the block is missing (`--fix` adds it) and prints the `git rm --cached` command for nativ files already committed. It never runs that command.
+- **`nativ task add --new-milestone <name>`.** Starts the next milestone when the others are done. `--force` works only from the CLI.
+
+### Changed
+
+- **Verification environment.** Checks get an allowlisted environment, and a timed-out check stops its whole process tree. `CI` inside a check no longer bypasses human-only steps. A check command may not set `NATIV_CI_OVERRIDE` or `NATIV_HEADLESS_OVERRIDE`; `nativ validate` and `task add` reject it.
+- **`--accept` keeps each value whole.** A `|` no longer splits a criterion.
+- **Guides.** AGENTS.md says required settings fail loudly and tests read only tracked files. The verifier has a "Weak verification" step and a config-fallback checklist item. The architect says what a real check looks like for each kind.
+
+<!-- nativ-check-ignore-start -->
 ## 2.8.0
 
 ### Changed
@@ -262,3 +282,4 @@ nativ is now role-based and Claude-first. The roles (architect, project manager,
 ## 1.0.0
 
 Initial release.
+<!-- nativ-check-ignore-end -->

package/README.md

@@ -193,6 +193,7 @@ nativ init [targetDir] [-f, --force]
 | :--- | :--- |
 | `-f, --force` | Overwrite existing specification and directive files |
 | `--design <taste-v1|taste-v2>` | Set the design profile in `.ai/ui_specs.md` and install the taste-skill bundle |
+| `--git-visibility <mode>` | `hidden` (default) adds a managed `.gitignore` block listing only nativ's generated files; `shared` ignores only secret and machine files |
 
 #### `nativ design check`
 
@@ -260,6 +261,8 @@ nativ doctor [targetDir] [options]
 | `--no-deep` | Skip asking Claude Code (`claude mcp list`) whether the server connects |
 | `--json` | Output the report as JSON |
 
+It also warns when the managed `.gitignore` block is missing (`--fix` adds it) and prints the `git rm --cached` command for nativ files already committed. It never runs that command.
+
 Run it after updating Claude Code or nativ.
 
 #### `nativ update`
@@ -365,8 +368,11 @@ nativ task add <title> [targetDir] [options]
 | `--deps <ids>` | Comma-separated dependency task IDs |
 | `--spec-refs <refs>` | Contract anchors, e.g. `ui_specs.md#appointment-list` or `api_contracts.json#GET /appointments` |
 | `--complexity <level>` | `simple`, `standard` or `complex` (routes the worker's model) |
-| `--accept <text>` | "Done when" line; repeatable or `\|`-separated |
+| `--accept <text>` | "Done when" line; repeatable, each value kept whole |
 | `--fast-path` | Route to the fast-path milestone for quick fixes |
+| `--kind <kind>` | Verification kind: `unit`, `integration`, `static-config`, `docs`, `probe` or `manual`. `docs` defaults the check to `nativ check docs` |
+| `--notes <text>` | Task notes; required with `--kind manual` |
+| `--new-milestone <name>` | Create the next milestone with this name and add the task to it. Refused while another planned milestone is open, unless `--force` |
 | `--json` | Output the created task as JSON |
 
 ```bash
@@ -404,6 +410,8 @@ nativ task complete <taskId> [targetDir] [options]
 | :--- | :--- |
 | `-n, --notes <notes>` | Completion notes |
 | `--timeout <ms>` | Verification timeout (default 120000) |
+| `--isolation <mode>` | Run the check in place (`none`) or in a clean copy of the repo (`clean`). Accepts `none` or `clean`. See [Verification](#verification) |
+| `--clean` | Short for `--isolation clean` |
 | `--no-verify` | Skip verification. *You only*: needs an interactive terminal, is denied to agents, and the MCP tool refuses it |
 
 #### `nativ task block`
@@ -475,6 +483,8 @@ nativ verify --all --json
 | `-a, --all` | Every completed task |
 | `-m, --milestone <id>` | Every task in a milestone |
 | `--timeout <ms>` | Per command (default 120000) |
+| `--isolation <mode>` | In place, or in a clean copy with only the files git ships and a minimal environment |
+| `--clean` | Short for `--isolation clean` |
 | `--json` | Output as JSON |
 
 **What runs, in order** (the same for `verify`, the `task complete` gatekeeper and Studio dispatch):
@@ -492,6 +502,16 @@ nativ verify --all --json
 
 With no phases configured, verification is just the task's command and the style check. The settings always come from the main checkout, never a task worktree's copy. If `.nativ/config.json` cannot be read, or a phase has no `name` or `run`, verification fails with a clear message instead of skipping the checks.
 
+#### `nativ check docs`
+
+Checks markdown files for drift: backticked file paths, `<PLACEHOLDER>` tokens against the file the paragraph names, setting names used in assignments or as variable references, and nativ subcommands and flags.
+
+```bash
+nativ check docs README.md CHANGELOG.md [--json]
+```
+
+Skip a line with `<!-- nativ-check-ignore -->`, or wrap a block in `<!-- nativ-check-ignore-start -->` and `<!-- nativ-check-ignore-end -->`.
+
 [Back to contents](#contents)
 
 ---
@@ -722,6 +742,11 @@ Written by `setup`; every key is optional.
 | `codeStyle.mode` | `warn` | `warn`, `block` or `off` for the line-length and comment check |
 | `codeStyle.maxLineLength` | `120` | Longest allowed line |
 | `codeStyle.maxCommentLines` | `2` | Longest allowed comment block |
+| `codeStyle.configFallback` | `warn` | `off`, `warn` or `block` for reads of settings that silently fall back to empty. Opt out per line with `nativ-allow-fallback` |
+| `verifyIsolation` | `none` (`clean` in solo and enterprise) | Run checks in a clean copy of the repo. See [`nativ verify`](#verification) |
+| `verifyIsolationFailure` | `warn` | `warn` or `block` when a check fails in the clean copy but passes in place |
+| `verifyEnv` | none | Extra environment variable names a check may read |
+| `verifyLinks` | `node_modules`, `.venv`, `venv` | Files linked into the clean copy, for example dependency folders |
 | `providers` | see [Providers](#providers) | Provider order per role: `architect`, `pm`, `worker`, `verifier`, `triage` |
 | `models` | provider default | Model per provider |
 | `notify` | off | `webhook`, `command` and `events` for human notifications. See [`nativ notify test`](#nativ-notify-test) |

package/dist/commands/check.d.ts

@@ -0,0 +1,3 @@
+export declare function runCheckDocs(files: string[], options: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/check.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectRoot } from '../core/root-resolver.js';
+import { listProjectEnvNames } from '../core/env-reads.js';
+import { checkDocText } from '../core/checks/docs-check.js';
+function specOf(cmd) {
+    const flags = cmd.options.flatMap((o) => [o.long, o.short].filter((f) => !!f));
+    const subs = {};
+    for (const sub of cmd.commands)
+        subs[sub.name()] = specOf(sub);
+    return { flags, subs };
+}
+export async function runCheckDocs(files, options) {
+    const root = resolveProjectRoot(process.cwd());
+    const { createProgram } = await import('../index.js');
+    const ctx = { root, envNames: new Set(listProjectEnvNames(root)), program: specOf(createProgram()) };
+    const findings = [];
+    for (const f of files) {
+        const full = path.resolve(process.cwd(), f);
+        if (!fs.existsSync(full)) {
+            console.error(`Cannot read ${f}`);
+            process.exitCode = 1;
+            return;
+        }
+        findings.push(...checkDocText(fs.readFileSync(full, 'utf8'), path.relative(root, full), ctx));
+    }
+    if (options.json)
+        console.log(JSON.stringify({ ok: findings.length === 0, findings }, null, 2));
+    else if (findings.length === 0)
+        console.log('Docs check: no problems found.');
+    else
+        for (const x of findings)
+            console.log(`${x.file}:${x.line}  ${x.kind}  ${x.message}`);
+    if (findings.length > 0)
+        process.exitCode = 1;
+}

package/dist/commands/doctor.js

@@ -100,7 +100,11 @@ export function collectChecks(root, options = {}) {
     add('cli-runs', version.ok ? 'ok' : 'fail', version.ok ? `\`${cli.join(' ')}\` runs (${version.output})` : `\`${cli.join(' ')}\` does not run: ${version.output || 'no output'}. The hooks and MCP server would fail.`);
     // Generated assets: whatever setup would still change is drift
     for (const change of plan.changes) {
-        if (change.action === 'created')
+        if (change.path === '.gitignore' && change.action !== 'unchanged') {
+            const what = change.action === 'created' ? 'has no' : 'has an outdated';
+            add('gitignore', 'warn', `.gitignore ${what} nativ block, so generated files may be committed by accident`, true);
+        }
+        else if (change.action === 'created')
             add(`asset:${change.path}`, 'fail', `${change.path} is missing`, true);
         else if (change.action === 'updated')
             add(`asset:${change.path}`, 'warn', `${change.path} is out of date${change.detail ? ` (${change.detail})` : ''}`, true);
@@ -109,6 +113,8 @@ export function collectChecks(root, options = {}) {
         else if (change.detail)
             add(`asset:${change.path}`, 'info', `${change.path}: ${change.detail}`);
     }
+    if (plan.gitRmCommand)
+        add('gitignore-tracked', 'info', `nativ files are already tracked by git. To stop tracking them, run: ${plan.gitRmCommand}`);
     if (!plan.changes.some((c) => c.action === 'created' || c.action === 'updated'))
         add('assets', 'ok', 'MCP server, hooks, permissions, agents and directives are in place');
     // Claude Code's own view (opt-in: it connects to every configured MCP server)

package/dist/commands/init.d.ts

@@ -1,4 +1,5 @@
 export declare function runInit(targetDirArg?: string, options?: {
     force?: boolean;
     design?: string;
+    gitVisibility?: 'hidden' | 'shared';
 }): Promise<void>;

package/dist/commands/init.js

@@ -175,7 +175,7 @@ export async function runInit(targetDirArg, options = {}) {
     }
     // 10. Claude Code configuration: MCP server, hooks, permissions, agents, AGENTS.md. Merges; never overwrites.
     console.log(pc.yellow('Configuring Claude Code (MCP server, hooks, agents)...'));
-    const setup = await runSetup(targetDir, { quiet: true });
+    const setup = await runSetup(targetDir, { quiet: true, gitVisibility: options.gitVisibility });
     if (setup) {
         printSetupResult(setup);
     }

package/dist/commands/setup.d.ts

@@ -4,6 +4,7 @@ export interface SetupCommandOptions {
     enforcement?: string;
     dryRun?: boolean;
     force?: boolean;
+    gitVisibility?: 'hidden' | 'shared';
     json?: boolean;
     /** Suppresses the report; `nativ init` prints its own. */
     quiet?: boolean;

package/dist/commands/setup.js

@@ -32,6 +32,7 @@ export async function runSetup(targetDirArg, options = {}) {
         command: options.command,
         enforcement: options.enforcement,
         force: options.force,
+        gitVisibility: options.gitVisibility,
         dryRun: options.dryRun,
     };
     const result = applySetup(targetDir, setupOptions);

package/dist/commands/task/task-add.js

@@ -1,5 +1,7 @@
 import pc from 'picocolors';
 import { isSubagentType, SUBAGENT_TYPES, validateMasterPlanTask, } from '../../scanner/types.js';
+import { configuredInvocation } from '../../core/setup/setup-planner.js';
+import { cliString, resolveCliInvocation } from '../../core/setup/types.js';
 import { withPlanLock } from '../../core/lock-manager.js';
 import { getPlanPath, getRoleGuide, } from './task-common.js';
 export const FAST_PATH_MILESTONE_NAME = 'Fast-Path Tasks';
@@ -43,6 +45,15 @@ function failTaskAdd(code, message, json) {
     process.exitCode = 1;
     return null;
 }
+/** Default check for a docs task: `nativ check docs` on its markdown files, or '' without any. */
+function defaultDocsCheck(targetFiles) {
+    const docs = targetFiles.filter((f) => /\.md$/i.test(f));
+    if (!docs.length)
+        return '';
+    const root = process.cwd();
+    const cli = cliString(configuredInvocation(root) ?? resolveCliInvocation({}));
+    return `${cli} check docs ${docs.join(' ')}`;
+}
 /** Resolves a milestone by exact ID, exact name, or a unique partial name (all case-insensitive). */
 function findMilestone(plan, query) {
     const q = query.trim().toLowerCase();
@@ -86,7 +97,29 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
         const fastPath = options.fastPath === true;
         let milestone;
         let createdMilestone = false;
-        if (options.milestone) {
+        const newName = options.newMilestone?.trim();
+        if (options.newMilestone !== undefined && !newName) {
+            ctx.abort();
+            return failTaskAdd('INVALID_MILESTONE_NAME', 'A new milestone needs a name', options.json);
+        }
+        if (newName && (options.milestone || fastPath)) {
+            ctx.abort();
+            return failTaskAdd('CONFLICTING_OPTIONS', '--new-milestone cannot be used with --milestone or --fast-path', options.json);
+        }
+        const stillOpen = plan.milestones.filter((m) => !m.fastPath && m.status !== 'completed');
+        if (newName && stillOpen.length && !options.force) {
+            ctx.abort();
+            const ids = stillOpen.map((m) => m.id).join(', ');
+            return failTaskAdd('MILESTONE_STILL_OPEN', `Milestone ${ids} is not completed yet. Finish it first, or pass --force`, options.json);
+        }
+        if (newName) {
+            milestone = { id: generateNextMilestoneId(plan), name: newName, status: 'in_progress', tasks: [] };
+            plan.milestones.push(milestone);
+            plan.activeMilestoneId = milestone.id;
+            plan.overallStatus = 'in_progress';
+            createdMilestone = true;
+        }
+        else if (options.milestone) {
             const found = findMilestone(plan, options.milestone);
             if (Array.isArray(found)) {
                 ctx.abort();
@@ -116,23 +149,33 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
         }
         const specRefs = [...new Set(splitList(options.specRefs))];
         const acceptanceCriteria = (Array.isArray(options.accept) ? options.accept : options.accept ? [options.accept] : [])
-            .flatMap((item) => item.split('|'))
             .map((item) => item.trim())
             .filter(Boolean);
         const complexity = options.complexity?.trim().toLowerCase();
+        const kind = options.kind?.trim().toLowerCase();
+        const notes = (options.notes ?? '').trim();
+        if (kind === 'manual' && !notes) {
+            ctx.abort();
+            return failTaskAdd('MANUAL_NEEDS_NOTES', 'A manual check needs --notes saying what the person must confirm', options.json);
+        }
+        const files = splitList(options.files);
+        let verify = (options.verify ?? '').trim();
+        if (kind === 'docs' && !verify)
+            verify = defaultDocsCheck(files);
         const task = {
             id: generateNextTaskId(plan),
             title: cleanTitle,
             description: (options.description ?? '').trim(),
             assignedSubagent: agent,
             dependencies: deps,
-            targetFiles: splitList(options.files),
+            targetFiles: files,
             status: 'pending',
-            verificationCommand: (options.verify ?? '').trim(),
-            notes: (options.notes ?? '').trim(),
+            verificationCommand: verify,
+            notes,
             ...(fastPath ? { fastPath: true } : {}),
             ...(specRefs.length ? { specRefs } : {}),
             ...(complexity ? { complexity: complexity } : {}),
+            ...(kind ? { verificationKind: kind } : {}),
             ...(acceptanceCriteria.length ? { acceptanceCriteria } : {}),
         };
         const problems = validateMasterPlanTask(task);
@@ -154,7 +197,7 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
         const track = fastPath ? pc.magenta(' [fast path]') : '';
         console.log(pc.green(`\n✔ Task [${pc.bold(task.id)}] added to [${milestone.id}] ${milestone.name}`) + track);
         if (createdMilestone)
-            console.log(pc.cyan(`  Created fast-path milestone [${milestone.id}]`));
+            console.log(pc.cyan(`  Created ${fastPath ? 'fast-path ' : ''}milestone [${milestone.id}]`));
         if (reopenedMilestone)
             console.log(pc.yellow(`  Reopened completed milestone [${milestone.id}]`));
         console.log(pc.dim('  Title:    ') + task.title);

package/dist/commands/task/task-common.d.ts

@@ -34,8 +34,14 @@ export interface TaskAddOptions {
     specRefs?: string | string[];
     /** simple | standard | complex. */
     complexity?: string;
+    /** unit | integration | static-config | docs | probe | manual. */
+    kind?: string;
     /** "Done when" lines: an array, or one string with "|" separators. */
     accept?: string | string[];
+    /** Create the next milestone with this name and add the task to it. */
+    newMilestone?: string;
+    /** With newMilestone, allow it while a planned milestone is still open (CLI only). */
+    force?: boolean;
     json?: boolean;
 }
 export interface TaskAddResult {

package/dist/commands/task/task-lifecycle.d.ts

@@ -7,5 +7,7 @@ export interface TaskStartOptions {
 }
 export declare function runTaskStart(taskId: string, targetDirArg?: string, options?: TaskStartOptions): Promise<void | null>;
 export declare function runTaskUnlock(taskId: string, targetDirArg?: string, options?: TaskUnlockOptions): Promise<void>;
-export declare function runTaskComplete(taskId: string, targetDirArg?: string, options?: TaskCompleteOptions): Promise<void>;
+export declare function runTaskComplete(taskId: string, targetDirArg?: string, options?: TaskCompleteOptions & {
+    isolation?: string;
+}): Promise<void>;
 export declare function runTaskBlock(taskId: string, reason: string, targetDirArg?: string): Promise<void | null>;

package/dist/commands/task/task-lifecycle.js

@@ -1,5 +1,10 @@
+import path from 'node:path';
 import pc from 'picocolors';
+import { parseIsolation } from '../verify.js';
+import { resolveActiveProfileSettings } from '../../core/profiles.js';
+import { resolveMainRoot } from '../../core/root-resolver.js';
 import { runTaskVerification } from '../../core/verifier.js';
+import { evaluateSkip } from '../../core/verifier/skip-policy.js';
 import { digestFailure } from '../../core/verifier/output-digest.js';
 import { CircuitBreaker, TestIntegrityGuard, resolveGitHead, closeEscalationsForTask, } from '../../governor/index.js';
 import { loadPlan, withPlanLock } from '../../core/lock-manager.js';
@@ -91,6 +96,23 @@ export async function runTaskUnlock(taskId, targetDirArg, options = {}) {
 export async function runTaskComplete(taskId, targetDirArg, options = {}) {
     if (options.skipVerify && refuseHeadless('nativ task complete --no-verify'))
         return;
+    let isolation;
+    try {
+        isolation = parseIsolation(options);
+    }
+    catch (e) {
+        console.error(pc.red(`
+✖ ${e.message}
+`));
+        process.exitCode = 1;
+        return;
+    }
+    const root = resolveMainRoot(path.resolve(targetDirArg || process.cwd()));
+    const profile = resolveActiveProfileSettings(root);
+    if (isolation === 'none' &&
+        profile.verifyIsolationFailure === 'block' &&
+        refuseHeadless('nativ task complete --isolation none'))
+        return;
     const { targetDir, planPath } = getPlanPath(targetDirArg);
     const plan = loadPlan(planPath);
     if (!plan) {
@@ -145,7 +167,7 @@ export async function runTaskComplete(taskId, targetDirArg, options = {}) {
     // ── Verification Gatekeeper ────────────────────────────────────────────────
     let vResult = null;
     if (!options.skipVerify) {
-        vResult = await runTaskVerification(foundTask, { cwd: targetDir, timeout: options.timeout });
+        vResult = await runTaskVerification(foundTask, { cwd: targetDir, timeout: options.timeout, isolation });
         if (!vResult.success) {
             console.error(pc.red(`\n✖ Task [${pc.bold(taskId)}] verification FAILED with exit code ${vResult.exitCode}:`));
             const failedPhase = vResult.phases?.find((p) => !p.success);
@@ -173,11 +195,27 @@ export async function runTaskComplete(taskId, targetDirArg, options = {}) {
             return;
         }
         if (vResult.skipped) {
+            const skip = evaluateSkip(foundTask, profile.skippedCheck);
+            if (skip.action === 'block') {
+                console.error(pc.red(`
+✖ Task [${pc.bold(taskId)}] cannot complete: ${skip.message}`));
+                console.error(pc.yellow(`  Task remains '${foundTask.status}'.
+`));
+                process.exitCode = 1;
+                return;
+            }
+            if (skip.action === 'warn')
+                console.log(pc.yellow(`
+⚠ ${skip.message}`));
             console.log(pc.dim(`\n○ Verification skipped: no verification command specified for [${taskId}]`));
         }
         else {
             const elapsed = (vResult.durationMs / 1000).toFixed(2);
-            console.log(pc.green(`\n✔ Verification passed (${elapsed}s): `) + pc.yellow(`\`${foundTask.verificationCommand}\``));
+            const used = vResult.isolation ?? 'none';
+            console.log(pc.green(`\n✔ Verification passed (${elapsed}s, isolation: ${used}): `) +
+                pc.yellow(`\`${foundTask.verificationCommand}\``));
+            for (const w of vResult.warnings ?? [])
+                console.log(pc.yellow(`  ⚠ ${w}`));
         }
     }
     else {

package/dist/commands/update.d.ts

@@ -1,6 +1,7 @@
 export interface UpdateOptions {
     /** Also replace directive and role-guide files that were edited by hand. */
     force?: boolean;
+    gitVisibility?: 'hidden' | 'shared';
 }
 /**
  * `nativ update`: brings a project up to the current templates without destroying its own work.

package/dist/commands/update.js

@@ -110,7 +110,7 @@ export async function runUpdate(targetDirArg, options = {}) {
     kept += syncTasteBundle(templatesDir, aiDir, options.force);
     // 2. Everything `nativ setup` manages: AGENTS.md, .claude/agents/, settings, MCP server
     console.log(pc.bold('\nClaude Code configuration'));
-    const setup = applySetup(targetDir, { force: options.force });
+    const setup = applySetup(targetDir, { force: options.force, gitVisibility: options.gitVisibility });
     printSetupResult(setup);
     // 3. Backfill missing core contracts safely (NEVER overwrite existing project state)
     console.log(pc.bold('\nContracts'));

package/dist/commands/verify.d.ts

@@ -4,5 +4,12 @@ export interface VerifyOptions {
     milestone?: string;
     json?: boolean;
     timeout?: number;
+    isolation?: string;
+    clean?: boolean;
 }
+/** Reads --isolation / --clean; undefined means use the profile. */
+export declare function parseIsolation(o: {
+    isolation?: string;
+    clean?: boolean;
+}): 'none' | 'clean' | undefined;
 export declare function runVerify(taskId?: string, targetDirArg?: string, options?: VerifyOptions): Promise<BatchVerificationResult>;

package/dist/commands/verify.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
 import pc from 'picocolors';
 import { verifyBatch } from '../core/verifier.js';
+import { loadPlan } from '../core/lock-manager.js';
+import { evaluateSkip } from '../core/verifier/skip-policy.js';
+import { resolveActiveProfileSettings } from '../core/profiles.js';
 import { digestFailure } from '../core/verifier/output-digest.js';
 /** Passing runs need no output; failing ones get a digest and the path to the full log. */
 function compactBatch(batch, root) {
@@ -14,6 +17,15 @@ function compactBatch(batch, root) {
         }),
     };
 }
+/** Reads --isolation / --clean; undefined means use the profile. */
+export function parseIsolation(o) {
+    const v = o.clean ? 'clean' : o.isolation;
+    if (v === undefined)
+        return undefined;
+    if (v !== 'none' && v !== 'clean')
+        throw new Error(`--isolation must be none or clean, got "${v}"`);
+    return v;
+}
 export async function runVerify(taskId, targetDirArg, options = {}) {
     const targetDir = path.resolve(targetDirArg || process.cwd());
     const batch = await verifyBatch(targetDir, {
@@ -21,6 +33,7 @@ export async function runVerify(taskId, targetDirArg, options = {}) {
         milestoneId: options.milestone,
         all: options.all,
         timeout: options.timeout,
+        isolation: parseIsolation(options),
     });
     if (options.json) {
         console.log(JSON.stringify(compactBatch(batch, targetDir)));
@@ -35,24 +48,35 @@ export async function runVerify(taskId, targetDirArg, options = {}) {
         console.log(pc.yellow('No candidate tasks found to verify. Specify a taskId, --milestone, or --all.\n'));
         return batch;
     }
+    const skipMode = resolveActiveProfileSettings(targetDir).skippedCheck;
+    const plan = loadPlan(path.join(targetDir, '.ai', 'master_plan.json'), { silent: true });
+    const planTasks = plan?.milestones.flatMap((m) => m.tasks) ?? [];
     for (const t of batch.tasks) {
         const elapsed = (t.result.durationMs / 1000).toFixed(2);
         if (t.result.skipped) {
             console.log(pc.dim(`  ○ [${t.taskId}] ${t.title} — no verification command (skipped)`));
+            const pt = planTasks.find((x) => x.id === t.taskId);
+            const skip = pt && evaluateSkip(pt, skipMode);
+            if (skip?.message)
+                console.log(pc.yellow(`    ⚠ ${skip.message}`));
             continue;
         }
         if (t.result.success) {
             console.log(pc.green(`  ✔ [${pc.bold(t.taskId)}] ${t.title}`) +
-                pc.dim(` (${elapsed}s)`) +
+                pc.dim(` (${elapsed}s, isolation: ${t.result.isolation ?? 'none'})`) +
                 pc.yellow(` \`${t.result.command}\``));
+            for (const w of t.result.warnings ?? [])
+                console.log(pc.yellow(`    ⚠ ${w}`));
             if (t.result.phases?.length) {
                 console.log(pc.dim(`    Phases passed: ${t.result.phases.map((p) => p.name).join(', ')}`));
             }
         }
         else {
             console.log(pc.red(`  ✖ [${pc.bold(t.taskId)}] ${t.title}`) +
-                pc.dim(` (${elapsed}s, exit code: ${t.result.exitCode})`) +
+                pc.dim(` (${elapsed}s, exit ${t.result.exitCode}, isolation: ${t.result.isolation ?? 'none'})`) +
                 pc.yellow(` \`${t.result.command}\``));
+            for (const w of t.result.warnings ?? [])
+                console.log(pc.yellow(`    ⚠ ${w}`));
             const failedPhase = t.result.phases?.find((p) => !p.success);
             if (failedPhase)
                 console.log(pc.red(`    Failed in phase "${failedPhase.name}"`));

package/dist/core/checks/docs-check.d.ts

@@ -0,0 +1,18 @@
+/** One nativ command: its own flags and its subcommands. */
+export interface CommandSpec {
+    flags: string[];
+    subs: Record<string, CommandSpec>;
+}
+export interface DocFinding {
+    file: string;
+    line: number;
+    kind: 'path' | 'placeholder' | 'setting' | 'flag';
+    token: string;
+    message: string;
+}
+export interface DocsContext {
+    root: string;
+    envNames: Set<string>;
+    program: CommandSpec;
+}
+export declare function checkDocText(text: string, docFile: string, ctx: DocsContext): DocFinding[];