@njeybe/nativ 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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
+
+- **One set of Studio state words.** Every page says Up next, Running, Done or Stuck. "Ready", "Blocked", "Waiting", "Just finished", "Idle" and "completed / started" are gone. A failed run shows as Stuck. A stopped run, or a claim older than 4 hours with no active run, shows as Up next.
+- **Plain agent names.** Home, Tasks and Team show names such as "QA tester" instead of `qa-tester`. Team merges alias rows of the same agent.
+- **Quieter shell.** The pulse strip shows only non-zero counts and hides when everything is zero. The dispatch button hides when nothing is ready instead of showing a grey "Nothing ready". "Abort" is now "Stop". The Benchmarks nav badge is gone. The workspace path no longer breaks mid-word.
+- **Slimmer runner console.** Stop shows only while a run is active. Open diff, Clear and Auto-scroll sit in a More menu. An idle console hides its empty stepper and zero totals.
+- **Tasks page.** A list row opens the task drawer, the same as a Board card. Filters with no tasks are hidden. The Board always shows its four lanes, and an empty lane says "None". The drawer has "Watch live", and "How it is checked" wraps.
+- **Home.** Recent activity shows one row per task with its title and state, for example "Done, took 4m 00s".
+- **Flow.** Plan cards show titles on up to two lines.
+- **Database and Benchmarks.** "Not set up" is neutral, and red means only a configured connection that is offline. The header Connection Settings button is the single way in. Benchmarks lists scenarios that were not run on one line.
+- **Option trade-offs.** The architect, the project manager and the shared directive add one line on when the non-recommended option would be the better choice.
+- **Verifier report.** The verifier reports contract findings and code style findings in separate parts.
+
 ## 2.7.0
 
 ### Added
@@ -247,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[];