@njeybe/nativ 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 2.9.1
+
+### Added
+
+- **Plan compaction.** `nativ milestone archive <ids> --summary "..."` moves a finished milestone into `.ai/archive/` once the regression suite passes, and `nativ milestone restore <id>` brings it back. `nativ task show <id>` reads one task, archived or not. MCP tools `nativ_milestone_archive` and `nativ_task_show` cover archive and show; restore stays CLI only.
+- **Archived milestones count everywhere.** `nativ status` and the Studio keep archived tasks in their totals, dependencies on archived tasks count as met, `nativ validate` fails when an archive file is missing or does not match, and `verify --all` skips archived tasks.
+- **`regressionCommand` setting.** The test suite `nativ milestone archive` runs, saved by `--check`.
+- **Project manager guide.** After the verifier passes a milestone: archive it, tell the human, suggest `/clear`.
+
+### Changed
+
+- **Smaller JSON by default.** `nativ status --json` returns full tasks only for the active milestone, and `nativ task list --json` (and `nativ tasks --json`) returns a short summary per task. Pass `--full` for the old output. Scripts that read these may need to change.
+
+### Fixed
+
+- **`--json` on `task list`.** The help promised a summary, but the CLI always printed every field. It now matches the MCP tool.
+- **Checks ran twice.** The worker guide told workers to run a task's check before `nativ task complete`, which runs it anyway.
+- **Startup instructions loaded twice.** With nativ installed as both a plugin and in the project, the plugin's hook now stays silent.
+- **Git Bash found by clean checks on Windows.** Clean check environments now pass `ProgramFiles` and `ProgramFiles(x86)` on Windows, so native runner checks find Git Bash without a `verifyEnv` workaround.
+
+## 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 +302,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

@@ -128,6 +128,7 @@ concrete result to the next.
 | 5. Check | let the worker complete the task | The gatekeeper runs your verify phases, then the task's command, then a code-style check. |
 | 6. Review | ask for a **verifier** pass | An independent read of the diff against the contracts. |
 | 7. Improve | approve lessons agents proposed | `nativ learn list --status proposed`, then `approve` or `reject`. |
+| 8. Compact | archive the finished milestone, then `/clear` | `nativ milestone archive` shrinks the plan to a one-line summary. The plan holds the state, so a fresh session loses nothing and costs fewer tokens. |
 
 ---
 
@@ -152,6 +153,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`hook status`](#nativ-hook) | Enforcement mode, role and active task scope | You, Agent |
 | [`task next`](#nativ-task-next) | The next executable task with its context | Agent |
 | [`task list`](#nativ-task-list) / `tasks` | List tasks with filters | You, Agent |
+| [`task show`](#nativ-task-show) | One task from the plan or its archive | You, Agent |
 | [`task add`](#nativ-task-add) | Add a task | Architect |
 | [`task start`](#nativ-task-start) | Mark a task in progress | Agent |
 | [`task reclaim`](#nativ-task-reclaim) | Free tasks left in progress by a stopped agent | You, Agent |
@@ -160,6 +162,7 @@ Every command takes an optional `[targetDir]` (default: the current directory) a
 | [`task escalate`](#nativ-task-escalate) | Escalate a contract gap to the architect | Agent |
 | [`task propose-patch`](#nativ-task-propose-patch) | Propose a governed contract change | Agent |
 | [`task unlock`](#nativ-task-unlock) | Lift a task's file scope in an emergency | *You only* |
+| [`milestone archive` / `restore`](#nativ-milestone-archive--restore) | Move a finished milestone out of the plan, or bring it back | You, Agent (`restore` by CLI) |
 | [`verify`](#nativ-verify) | Run verification for a task, a milestone or all | You, Agent |
 | [`learn propose`](#nativ-learn-propose) | Propose a lesson for later workers | Agent |
 | [`learn list`](#nativ-learn-list) | List lessons | You, Agent |
@@ -193,6 +196,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 +264,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`
@@ -287,9 +293,11 @@ nativ validate [targetDir]
 Progress per milestone; with `--telemetry`, durations, token and cost estimates, pass rates and role violations.
 
 ```bash
-nativ status [targetDir] [-t, --telemetry] [--json]
+nativ status [targetDir] [-t, --telemetry] [--json] [--full]
 ```
 
+`--json` returns full tasks only for the active milestone, one line for each other milestone and the telemetry summary. Add `--full` for every task and per-task telemetry. Archived milestones count toward the totals.
+
 #### `nativ hook`
 
 ```bash
@@ -345,7 +353,8 @@ nativ task list [targetDir] [options]      # also available as: nativ tasks
 | `-s, --status <status>` | `pending`, `in_progress`, `completed` or `blocked` |
 | `-m, --milestone <id>` | Milestone ID or name |
 | `--fast-path` | Only fast-path tasks |
-| `--json` | Output as JSON |
+| `--json` | Output a short summary per task as JSON |
+| `--full` | With `--json`, include every task field |
 
 #### `nativ task add`
 
@@ -365,8 +374,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
@@ -384,6 +396,26 @@ nativ task start <taskId> [targetDir] [--agent <id>] [--force]
 
 Claims the task, marks it `in_progress` and records the baseline the test-integrity guard compares against. The task must be pending and its dependencies completed; a blocked task goes through `nativ triage` first, and only a person can override with `--force`. The claim records `claimedBy` (`--agent` or `$NATIV_AGENT_ID`) and `claimedAt`, so a parallel agent cannot take a task another agent holds. Running `task start` again on your own task refreshes the claim; a claim older than 4 hours counts as abandoned.
 
+#### `nativ task show`
+
+```bash
+nativ task show <taskId> [targetDir] [--json]
+```
+
+Prints one task from the plan, or from its milestone archive when the milestone is archived. Use it for an old task instead of opening the plan.
+
+#### `nativ milestone archive` / `restore`
+
+```bash
+nativ milestone archive <ids> --summary "Studio redesign: shell, routing, pages"
+nativ milestone archive m1,m2 --summaries summaries.json [--check "npm test"] [--timeout 600000]
+nativ milestone restore <id>
+```
+
+Archives finished milestones after the regression suite passes. Every task must be completed, and the working tree must be clean. The archive is written to `.ai/archive/<id>.json` and read back before the plan changes. The suite is the `regressionCommand` in `.nativ/config.json`; `--check` overrides and saves it. Default timeout is 10 minutes. Archived task ids still count for numbering and dependencies. `restore` is CLI only.
+
+A summaries file maps each milestone id to its one-line summary, and the suite runs once for the whole batch. `.ai/` is usually not in git, so keep archive files: they are the only full copy of those tasks.
+
 #### `nativ task reclaim`
 
 ```bash
@@ -404,6 +436,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`
@@ -462,7 +496,7 @@ nativ task unlock <taskId> --revoke
 
 #### `nativ verify`
 
-Re-run verification for one task, a milestone or every completed task. Also available as `nativ task verify`.
+Re-run verification for one task, a milestone or every completed task. Also available as `nativ task verify`. `--all` skips archived tasks, because their old checks may no longer apply; naming an archived task or milestone explains how to restore it.
 
 ```bash
 nativ verify task-01
@@ -475,6 +509,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 +528,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 +768,12 @@ 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 |
+| `regressionCommand` | none | The test suite `nativ milestone archive` runs before archiving; `--check` sets it |
 | `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) |
@@ -821,6 +873,7 @@ A deterministic firewall between agents and the contracts:
 | `.ai/db_schema.json`, `.ai/api_contracts.json`, `.ai/ui_specs.md` | architect | The contracts |
 | `.ai/design/style-tile.html` | architect | The chosen visual direction |
 | `.ai/master_plan.json` | `nativ task` commands | Milestones and tasks |
+| `.ai/archive/<id>.json` | `nativ milestone archive` | Full copy of an archived milestone; the plan keeps a one-line summary |
 | `.ai/subagents/*.md` | init, update | One guide per worker role |
 | `.ai/escalation.json` | `task escalate`, triage | Escalations and how they were settled |
 | `.ai/learnings.json` | `nativ learn` | Proposed, approved and rejected lessons |
@@ -838,7 +891,8 @@ Files nativ wrote carry a marker, so `update` and `doctor` can tell untouched fi
 
 | Tools | Purpose |
 | :--- | :--- |
-| `nativ_task_next`, `nativ_task_list`, `nativ_task_add` | Find and add work |
+| `nativ_task_next`, `nativ_task_list`, `nativ_task_show`, `nativ_task_add` | Find and add work (`task_show` also reads archived tasks) |
+| `nativ_milestone_archive` | Archive finished milestones after the regression suite passes. A slow suite can outlast a client's tool timeout; use the CLI for those |
 | `nativ_task_start`, `nativ_task_complete`, `nativ_task_block`, `nativ_task_reclaim` | Move a task through its lifecycle (complete always runs the gatekeeper; reclaim frees stale claims) |
 | `nativ_validate` | Check the `.ai/` contracts, plan and role guides; returns only problems and a verdict |
 | `nativ_triage` | Self-heal: evaluate pending escalations, apply sandbox-proven safe fixes, return decision cards for the rest |
@@ -853,7 +907,7 @@ Files nativ wrote carry a marker, so `update` and `doctor` can tell untouched fi
 | :--- |
 | `nativ://context`, `nativ://master-plan`, `nativ://db-schema`, `nativ://api-contracts`, `nativ://escalation`, `nativ://telemetry` |
 
-There is deliberately no MCP tool to unlock a task, approve a lesson, write a contract, sync a database schema or run setup.
+There is deliberately no MCP tool to unlock a task, approve a lesson, write a contract, sync a database schema, restore an archived milestone or run setup.
 
 **Manual registration:**
 
@@ -941,6 +995,8 @@ npm test
 npm run sync-plugin      # after changing a template or the setup generator; a test fails if plugin/ is stale
 ```
 
+Some suites need a temp folder outside any git repository. If your home folder is a git repository and temp sits inside it, `learnings`, `verify-gatekeeper` and `clean-tree` fail; point `TEMP`, `TMP` and `TMPDIR` elsewhere when you run `npm test`.
+
 ---
 
 ## License

package/bin/cli.js

@@ -14,7 +14,7 @@ if (group === 'hook' && (subcommand === 'check' || subcommand === 'context')) {
       await runHookCheck(targetDir);
     } else {
       const { runSessionContext } = await import('../dist/core/setup-assets.js');
-      runSessionContext(targetDir);
+      runSessionContext(targetDir, undefined, { fromPlugin: rest.includes('--from-plugin') });
     }
   } catch (err) {
     // A hook must never fail the tool call it guards.

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/milestone.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+export interface MilestoneArchiveOptions {
+    summary?: string;
+    summaries?: string;
+    check?: string;
+    timeout?: number;
+}
+export declare function runMilestoneArchive(idList: string, targetDirArg: string | undefined, options: MilestoneArchiveOptions): Promise<void>;
+export declare function runMilestoneRestore(id: string, targetDirArg?: string): Promise<void>;
+export declare function registerMilestoneCommands(program: Command): void;

package/dist/commands/milestone.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { archiveMilestones, ArchiveRefusal, restoreMilestone, DEFAULT_SUITE_TIMEOUT_MS, } from '../core/milestone-archive.js';
+function readSummaries(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new ArchiveRefusal(`--summaries file cannot be read (${err?.message}).`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ArchiveRefusal('--summaries file must be a JSON object of milestone id to summary.');
+    }
+    return parsed;
+}
+function collectSummaries(ids, options) {
+    if (options.summary !== undefined && options.summaries) {
+        throw new ArchiveRefusal('Use --summary or --summaries, not both.');
+    }
+    if (options.summaries)
+        return readSummaries(options.summaries);
+    if (options.summary === undefined)
+        return {};
+    if (ids.length > 1)
+        throw new ArchiveRefusal('Several milestones need --summaries <file.json>.');
+    return { [ids[0]]: options.summary };
+}
+async function report(work, onDone) {
+    try {
+        onDone(await work());
+    }
+    catch (err) {
+        if (!(err instanceof ArchiveRefusal))
+            throw err;
+        console.error(pc.red(`\n✖ ${err.message}\n`));
+        process.exitCode = 1;
+    }
+}
+export async function runMilestoneArchive(idList, targetDirArg, options) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const ids = idList.split(',').map((id) => id.trim()).filter(Boolean);
+    await report(async () => archiveMilestones(targetDir, {
+        ids,
+        summaries: collectSummaries(ids, options),
+        check: options.check,
+        timeout: options.timeout,
+    }), (result) => {
+        for (const m of result.archived) {
+            console.log(pc.green(`\n✔ Archived [${m.id}]: ${m.taskCount} tasks moved to ${m.file}`));
+        }
+        console.log(pc.dim(`  Active milestone: ${result.activeMilestoneId}\n`));
+        result.warnings.forEach((w) => console.log(pc.yellow(`⚠ ${w}`)));
+    });
+}
+export async function runMilestoneRestore(id, targetDirArg) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    await report(() => restoreMilestone(targetDir, id), (result) => {
+        console.log(pc.green(`\n✔ Restored [${result.id}]: ${result.taskCount} tasks are back\n`));
+        result.warnings.forEach((w) => console.log(pc.yellow(`⚠ ${w}`)));
+    });
+}
+export function registerMilestoneCommands(program) {
+    const milestone = program
+        .command('milestone')
+        .description('Move finished milestones out of .ai/master_plan.json and back');
+    milestone
+        .command('archive <ids> [targetDir]')
+        .description('Archive finished milestones (comma-separated ids) after the test suite passes')
+        .option('--summary <text>', 'What the milestone delivered (required for one milestone)')
+        .option('--summaries <file>', 'JSON file of milestone id to summary, for several milestones')
+        .option('--check <command>', 'Suite to run; saved as regressionCommand in .nativ/config.json')
+        .option('--timeout <ms>', `Suite timeout in ms (default ${DEFAULT_SUITE_TIMEOUT_MS})`, parseInt)
+        .action(async (ids, targetDir, options) => {
+        await runMilestoneArchive(ids, targetDir, options);
+    });
+    milestone
+        .command('restore <id> [targetDir]')
+        .description('Put an archived milestone and its tasks back into the plan')
+        .action(async (id, targetDir) => {
+        await runMilestoneRestore(id, targetDir);
+    });
+}

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/status.d.ts

@@ -1,5 +1,6 @@
 export interface StatusOptions {
     telemetry?: boolean;
     json?: boolean;
+    full?: boolean;
 }
 export declare function runStatus(targetDirArg?: string, options?: StatusOptions): Promise<void>;

package/dist/commands/status.js

@@ -17,14 +17,7 @@ export async function runStatus(targetDirArg, options = {}) {
         const plan = JSON.parse(raw);
         const telemetry = loadTelemetry(telemetryPath, plan.projectName);
         if (options.json) {
-            console.log(JSON.stringify({
-                projectName: plan.projectName,
-                overallStatus: plan.overallStatus,
-                activeMilestoneId: plan.activeMilestoneId,
-                milestones: plan.milestones,
-                telemetry: telemetry.summary,
-                tasksTelemetry: telemetry.tasks,
-            }, null, 2));
+            console.log(JSON.stringify(buildStatusJson(plan, telemetry, !!options.full), null, 2));
             return;
         }
         console.log(pc.bold(pc.cyan(`\n📊 AI Agent Workflow Status: ${plan.projectName}`)));
@@ -34,6 +27,14 @@ export async function runStatus(targetDirArg, options = {}) {
         let inProgressTasks = 0;
         let blockedTasks = 0;
         for (const m of plan.milestones) {
+            if (m.archived) {
+                // Archived work still counts, so progress does not drop after archiving.
+                totalTasks += m.archived.taskCount;
+                completedTasks += m.archived.taskCount;
+                const line = `🚩 Milestone [${m.id}]: ${m.name} (archived, ${m.archived.taskCount} tasks)`;
+                console.log(pc.bold(`\n${line}`) + pc.dim(` - ${m.archived.summary}`));
+                continue;
+            }
             console.log(pc.bold(`\n🚩 Milestone [${m.id}]: ${m.name} (${m.status})`));
             for (const t of m.tasks) {
                 totalTasks++;
@@ -73,3 +74,33 @@ export async function runStatus(targetDirArg, options = {}) {
         process.exitCode = 1;
     }
 }
+function buildStatusJson(plan, telemetry, full) {
+    const base = {
+        projectName: plan.projectName,
+        overallStatus: plan.overallStatus,
+        activeMilestoneId: plan.activeMilestoneId,
+    };
+    if (full) {
+        return { ...base, milestones: plan.milestones, telemetry: telemetry.summary, tasksTelemetry: telemetry.tasks };
+    }
+    const milestones = plan.milestones.map((m) => m.archived
+        ? {
+            id: m.id,
+            name: m.name,
+            status: m.status,
+            taskCount: m.archived.taskCount,
+            completedCount: m.archived.taskCount,
+            archived: true,
+            summary: m.archived.summary,
+        }
+        : m.id === plan.activeMilestoneId
+            ? m
+            : {
+                id: m.id,
+                name: m.name,
+                status: m.status,
+                taskCount: m.tasks.length,
+                completedCount: m.tasks.filter((t) => t.status === 'completed').length,
+            });
+    return { ...base, milestones, telemetry: telemetry.summary };
+}