@njeybe/nativ 2.9.0 → 2.9.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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 |
@@ -290,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
@@ -348,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`
 
@@ -390,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
@@ -470,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
@@ -747,6 +773,7 @@ Written by `setup`; every key is optional.
 | `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) |
@@ -846,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 |
@@ -863,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 |
@@ -878,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:**
 
@@ -966,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/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/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 };
+}

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

@@ -3,6 +3,7 @@ import { isSubagentType, SUBAGENT_TYPES, validateMasterPlanTask, } from '../../s
 import { configuredInvocation } from '../../core/setup/setup-planner.js';
 import { cliString, resolveCliInvocation } from '../../core/setup/types.js';
 import { withPlanLock } from '../../core/lock-manager.js';
+import { archivedTaskIds } from '../../core/milestone-archive.js';
 import { getPlanPath, getRoleGuide, } from './task-common.js';
 export const FAST_PATH_MILESTONE_NAME = 'Fast-Path Tasks';
 /** Next `<prefix><n>` after the highest existing number, keeping that ID's zero-padding. */
@@ -25,7 +26,8 @@ function nextNumberedId(ids, prefix, defaultWidth) {
     return candidate;
 }
 export function generateNextTaskId(plan) {
-    return nextNumberedId(plan.milestones.flatMap((m) => m.tasks.map((t) => t.id)), 'task-', 2);
+    const live = plan.milestones.flatMap((m) => m.tasks.map((t) => t.id));
+    return nextNumberedId([...live, ...archivedTaskIds(plan)], 'task-', 2);
 }
 export function generateNextMilestoneId(plan) {
     return nextNumberedId(plan.milestones.map((m) => m.id), 'm', 1);
@@ -87,7 +89,10 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
             ctx.abort();
             return failTaskAdd('INVALID_AGENT', `Unknown sub-agent "${agent}". Expected one of: ${SUBAGENT_TYPES.join(', ')}`, options.json);
         }
-        const existingIds = new Set(plan.milestones.flatMap((m) => m.tasks.map((t) => t.id)));
+        const existingIds = new Set([
+            ...plan.milestones.flatMap((m) => m.tasks.map((t) => t.id)),
+            ...archivedTaskIds(plan),
+        ]);
         const deps = [...new Set(splitList(options.deps))];
         const unknownDeps = deps.filter((d) => !existingIds.has(d));
         if (unknownDeps.length) {
@@ -132,7 +137,7 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
             milestone = found;
         }
         else if (fastPath) {
-            milestone = plan.milestones.find((m) => m.fastPath === true);
+            milestone = plan.milestones.find((m) => m.fastPath === true && !m.archived);
             if (!milestone) {
                 milestone = { id: generateNextMilestoneId(plan), name: FAST_PATH_MILESTONE_NAME, status: 'pending', fastPath: true, tasks: [] };
                 plan.milestones.push(milestone);
@@ -147,6 +152,11 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
                 return failTaskAdd('NO_OPEN_MILESTONE', 'Every milestone is completed. Pass --milestone <id> to reopen one, or --fast-path', options.json);
             }
         }
+        if (milestone.archived) {
+            ctx.abort();
+            const how = `Restore it first with: nativ milestone restore ${milestone.id}`;
+            return failTaskAdd('MILESTONE_ARCHIVED', `Milestone ${milestone.id} is archived. ${how}`, options.json);
+        }
         const specRefs = [...new Set(splitList(options.specRefs))];
         const acceptanceCriteria = (Array.isArray(options.accept) ? options.accept : options.accept ? [options.accept] : [])
             .map((item) => item.trim())

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

@@ -1,5 +1,7 @@
 import path from 'node:path';
+import { withArchivedAsDone } from '../../core/milestone-archive.js';
 import pc from 'picocolors';
+import { archivedTaskMessage, findArchivedMilestoneId } from './task-show.js';
 import { parseIsolation } from '../verify.js';
 import { resolveActiveProfileSettings } from '../../core/profiles.js';
 import { resolveMainRoot } from '../../core/root-resolver.js';
@@ -31,11 +33,15 @@ export async function runTaskStart(taskId, targetDirArg, options = {}) {
         }
         if (!foundTask) {
             ctx.abort();
-            console.error(pc.red(`\n✖ Task [${taskId}] not found in .ai/master_plan.json\n`));
+            const archivedIn = findArchivedMilestoneId(plan, taskId);
+            const why = archivedIn
+                ? archivedTaskMessage(taskId, archivedIn)
+                : `Task [${taskId}] not found in .ai/master_plan.json`;
+            console.error(pc.red(`\n✖ ${why}\n`));
             process.exitCode = 1;
             return;
         }
-        const refusal = options.force ? null : startRefusal(plan, foundTask, agent);
+        const refusal = options.force ? null : startRefusal(withArchivedAsDone(plan), foundTask, agent);
         if (refusal) {
             ctx.abort();
             console.error(pc.red(`\n✖ ${refusal}\n`));

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

@@ -5,6 +5,7 @@ import { resolveSpecSlices } from '../../core/spec-slices.js';
 import { resolveWorkerModel } from '../../core/model-routing.js';
 import { learningsForTask } from '../../core/learnings.js';
 import { taskEscalationHistory } from '../../governor/index.js';
+import { archivedTaskIds } from '../../core/milestone-archive.js';
 import { getPlanPath, getRoleGuide, getRecommendedContractSlice } from './task-common.js';
 export async function runTaskList(targetDirArg, options = {}) {
     const { planPath } = getPlanPath(targetDirArg);
@@ -13,7 +14,7 @@ export async function runTaskList(targetDirArg, options = {}) {
         process.exitCode = 1;
         return;
     }
-    const completedTaskIds = new Set();
+    const completedTaskIds = new Set(archivedTaskIds(plan));
     for (const m of plan.milestones) {
         for (const t of m.tasks) {
             if (t.status === 'completed') {
@@ -120,6 +121,7 @@ function briefTask(t, milestoneId, isAvailable) {
         isAvailable,
         ...(t.dependencies?.length ? { dependencies: t.dependencies } : {}),
         ...(t.targetFiles?.length ? { targetFiles: t.targetFiles } : {}),
+        ...(t.fastPath ? { fastPath: true } : {}),
         ...(t.status === 'blocked' && t.notes ? { notes: t.notes } : {}),
     };
 }
@@ -134,7 +136,7 @@ export async function runTaskNext(targetDirArg, options = {}) {
         process.exitCode = 1;
         return;
     }
-    const completedTaskIds = new Set();
+    const completedTaskIds = new Set(archivedTaskIds(plan));
     for (const m of plan.milestones) {
         for (const t of m.tasks) {
             if (t.status === 'completed') {

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

@@ -0,0 +1,9 @@
+import { MasterPlan } from '../../scanner/types.js';
+export interface TaskShowOptions {
+    json?: boolean;
+}
+/** The sentence shown when someone acts on a task that moved to an archive file. */
+export declare function archivedTaskMessage(taskId: string, milestoneId: string): string;
+export declare function findArchivedMilestoneId(plan: MasterPlan, taskId: string): string | undefined;
+/** Prints one task from the plan or, when archived, from its archive file. */
+export declare function runTaskShow(taskId: string, targetDirArg?: string, options?: TaskShowOptions): Promise<void>;

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

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { loadPlan } from '../../core/lock-manager.js';
+import { getPlanPath } from './task-common.js';
+/** The sentence shown when someone acts on a task that moved to an archive file. */
+export function archivedTaskMessage(taskId, milestoneId) {
+    return `Task [${taskId}] is archived (milestone ${milestoneId}). `
+        + `Run \`nativ milestone restore ${milestoneId}\` to bring its tasks back first.`;
+}
+export function findArchivedMilestoneId(plan, taskId) {
+    return plan.milestones.find((m) => m.archived?.taskIds.includes(taskId))?.id;
+}
+function readFromArchive(targetDir, plan, taskId) {
+    const milestone = plan.milestones.find((m) => m.archived?.taskIds.includes(taskId));
+    if (!milestone?.archived)
+        return null;
+    const file = path.join(targetDir, milestone.archived.file);
+    const saved = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const task = saved.tasks.find((t) => t.id === taskId);
+    if (!task)
+        throw new Error(`${milestone.archived.file} has no task ${taskId}`);
+    return { task, milestoneId: milestone.id };
+}
+function findTask(targetDir, plan, taskId) {
+    for (const m of plan.milestones) {
+        const task = m.tasks.find((t) => t.id === taskId);
+        if (task)
+            return { task, milestoneId: m.id, archived: false };
+    }
+    const found = readFromArchive(targetDir, plan, taskId);
+    return found && { ...found, archived: true };
+}
+/** Prints one task from the plan or, when archived, from its archive file. */
+export async function runTaskShow(taskId, targetDirArg, options = {}) {
+    const { targetDir, planPath } = getPlanPath(targetDirArg);
+    const plan = loadPlan(planPath);
+    if (!plan) {
+        process.exitCode = 1;
+        return;
+    }
+    let found;
+    try {
+        found = findTask(targetDir, plan, taskId);
+    }
+    catch (err) {
+        console.error(pc.red(`\n✖ The archive of task [${taskId}] cannot be read: ${err.message}\n`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!found) {
+        console.error(pc.red(`\n✖ Task [${taskId}] not found in .ai/master_plan.json\n`));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ...found.task, milestoneId: found.milestoneId, archived: found.archived }, null, 2));
+        return;
+    }
+    const { task } = found;
+    const where = found.archived ? `${found.milestoneId}, archived` : found.milestoneId;
+    console.log(pc.bold(pc.cyan(`\n[${task.id}] ${task.title}`)) + pc.dim(` (${where})`));
+    console.log(`  Status: ${task.status} | Agent: ${task.assignedSubagent}`);
+    console.log(`  Verify: \`${task.verificationCommand || 'none'}\``);
+    if (task.dependencies?.length)
+        console.log(`  Depends on: ${task.dependencies.join(', ')}`);
+    if (task.targetFiles?.length)
+        console.log(`  Files: ${task.targetFiles.join(', ')}`);
+    if (task.description)
+        console.log(`\n${task.description}`);
+    if (task.notes)
+        console.log(pc.dim(`\nNotes: ${task.notes}`));
+    console.log('');
+}

package/dist/commands/validate.js

@@ -33,6 +33,24 @@ export async function runValidate(targetDirArg) {
         console.log(pc.green(`  ✔ Present: ${relPath}`));
         return content;
     }
+    function checkArchive(m) {
+        const rel = `.ai/archive/${m.id}.json`;
+        let saved;
+        try {
+            saved = JSON.parse(fs.readFileSync(path.join(targetDir, rel), 'utf8'));
+        }
+        catch (err) {
+            console.log(pc.red(`  ✖ Archive file of ${m.id} is missing or unreadable: ${rel} (${err.message})`));
+            return false;
+        }
+        const ids = Array.isArray(saved?.tasks) ? saved.tasks.map((t) => t.id) : null;
+        if (saved?.id !== m.id || JSON.stringify(ids) !== JSON.stringify(m.archived.taskIds)) {
+            console.log(pc.red(`  ✖ ${rel} does not match the archived stub of ${m.id}`));
+            return false;
+        }
+        console.log(pc.green(`  ✔ Archive matches: ${rel}`));
+        return true;
+    }
     // Directives tell agents how to work; they are guidance, not contracts, and GEMINI.md is only an optional adapter guide.
     console.log(pc.bold('1. Directives:'));
     const directives = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].filter((f) => fs.existsSync(path.join(targetDir, f)));
@@ -66,6 +84,12 @@ export async function runValidate(targetDirArg) {
         for (const w of specWarnings)
             console.log(pc.yellow(`  ⚠ ${w}`));
     }
+    if (plan && Array.isArray(plan.milestones)) {
+        for (const m of plan.milestones) {
+            if (m?.archived && !checkArchive(m))
+                hasErrors = true;
+        }
+    }
     const escalationPath = path.join(targetDir, '.ai/escalation.json');
     if (fs.existsSync(escalationPath)) {
         const escData = checkFile('.ai/escalation.json', true);

package/dist/core/milestone-archive.d.ts

@@ -0,0 +1,40 @@
+import { type MasterPlan } from '../scanner/types.js';
+export declare const DEFAULT_SUITE_TIMEOUT_MS = 600000;
+/** An expected "no": the message is written for the person running the command. */
+export declare class ArchiveRefusal extends Error {
+}
+/** Seams so tests can make the read-back, the removal or the plan save fail. */
+export interface ArchiveDeps {
+    readBack?: (file: string) => string;
+    save?: (planPath: string, plan: MasterPlan) => boolean;
+    remove?: (file: string) => void;
+}
+export interface ArchiveRequest {
+    ids: string[];
+    summaries: Record<string, string>;
+    check?: string;
+    timeout?: number;
+}
+export interface ArchiveResult {
+    archived: Array<{
+        id: string;
+        file: string;
+        taskCount: number;
+    }>;
+    activeMilestoneId: string;
+    commit: string | null;
+    warnings: string[];
+}
+export interface RestoreResult {
+    id: string;
+    taskCount: number;
+    warnings: string[];
+}
+/** Ids of tasks moved out to archive files; they count as existing, completed tasks. */
+export declare function archivedTaskIds(plan: MasterPlan): string[];
+/** The plan as dependency checks should see it: archived tasks appear as completed. */
+export declare function withArchivedAsDone(plan: MasterPlan): MasterPlan;
+/** Refuses without side effects, runs the suite once outside the lock, then re-checks and commits. */
+export declare function archiveMilestones(targetDir: string, request: ArchiveRequest, deps?: ArchiveDeps): Promise<ArchiveResult>;
+/** Puts the tasks back; the archive file goes only after the plan is safely saved. */
+export declare function restoreMilestone(targetDir: string, id: string, deps?: ArchiveDeps): Promise<RestoreResult>;