nubos-pilot 0.1.0

package/workflows/ai-integration-phase.md

@@ -0,0 +1,230 @@
+---
+command: np:ai-integration-phase
+description: Generate AI-SPEC.md for AI/ML phases via 4-agent chain (np-framework-selector → np-ai-researcher → np-domain-researcher → np-eval-planner) with a completeness validation gate.
+---
+
+# np:ai-integration-phase
+
+Produces `{phase_dir}/{padded}-AI-SPEC.md` by running a strict-serial 4-agent chain.
+Inserts between `/np:discuss-phase` and `/np:plan-phase`. Locks domain
+context, framework selection, implementation patterns, and evaluation
+strategy BEFORE the planner creates tasks.
+
+Every Task-spawn site is wrapped in the Plan 09-05 metrics + resolve-model
+pattern (D-06, D-01). `RUNTIME` is detected once at the top of the bash
+block and re-used by every `metrics record` call.
+
+## Initialize
+
+```bash
+PHASE="$1"
+if [[ -z "$PHASE" ]]; then
+  echo "Usage: /np:ai-integration-phase <phase-number>" >&2
+  exit 2
+fi
+
+INIT=$(node np-tools.cjs init ai-integration-phase "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+RUNTIME=$(node -e "console.log(require('./lib/runtime/index.cjs').detect().runtime)")
+```
+
+Parse JSON for: `phase`, `padded`, `phase_dir`, `ai_spec_path`,
+`has_ai_spec`, `template_path`, `agents.framework_selector`,
+`agents.ai_researcher`, `agents.domain_researcher`, `agents.eval_planner`.
+
+```bash
+PADDED=$(echo "$INIT" | jq -r '.padded')
+PHASE_DIR=$(echo "$INIT" | jq -r '.phase_dir')
+AI_SPEC_PATH=$(echo "$INIT" | jq -r '.ai_spec_path')
+HAS_AI_SPEC=$(echo "$INIT" | jq -r '.has_ai_spec')
+TEMPLATE_PATH=$(echo "$INIT" | jq -r '.template_path')
+PLAN_ID="${PADDED}-ai-integration"
+TASK_ID="${PADDED}-ai-integration"
+```
+
+## Pre-Flight Gates
+
+<pre_flight>
+
+### Gate 1 — AI-SPEC.md already exists
+
+If `has_ai_spec == true`:
+
+```bash
+if [[ "$HAS_AI_SPEC" == "true" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Existing AI-SPEC",
+    "question": "AI-SPEC.md already exists for Phase '"$PHASE"'. What would you like to do?",
+    "options": [
+      {"label": "Update — re-run with existing as baseline", "description": "Re-runs the 4-agent chain against the current spec."},
+      {"label": "View — display current AI-SPEC and exit",   "description": "Reads the file and exits without changes."},
+      {"label": "Skip — keep current AI-SPEC and exit",      "description": "Leaves the file untouched."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*) cat "$AI_SPEC_PATH"; exit 0 ;;
+    "Skip"*) exit 0 ;;
+  esac
+fi
+```
+
+</pre_flight>
+
+## Philosophy
+
+<philosophy>
+AI-SPEC.md locks the four things AI projects most often ship wrong: the
+framework choice (too early / for the wrong reason), the domain rubrics
+(assumed without asking an expert), the implementation pattern (copy-paste
+from outdated docs), and the evaluation strategy (retrofitted after code
+is merged). Running this workflow BEFORE `/np:plan-phase` surfaces those
+decisions as explicit artifacts the planner and plan-checker can then
+enforce.
+</philosophy>
+
+## Main Flow
+
+The 4 agents run in strict serial order. Each spawn is wrapped in the
+Plan-09-05 metrics pattern. A failure in any step aborts the chain — the
+next agent reads the partial AI-SPEC.md that prior agents wrote.
+
+### Step 0 — Initialize AI-SPEC.md from template
+
+```bash
+if [[ "$HAS_AI_SPEC" != "true" ]]; then
+  cp "$TEMPLATE_PATH" "$AI_SPEC_PATH"
+fi
+```
+
+### Step 1 — Framework selection (np-framework-selector, opus)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-framework-selector --profile balanced)
+# Spawn agent=np-framework-selector model=$MODEL
+#   input: phase_number=$PHASE, ai_spec_path=$AI_SPEC_PATH, context=$PHASE_DIR/$PADDED-CONTEXT.md
+#   output: section 2 of AI-SPEC.md (framework scoring + selected)
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-framework-selector --tier opus --resolved-model "$MODEL" \
+  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+  --started "$START" --ended "$END" \
+  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+  --retry-count 0 --status ok --runtime "$RUNTIME"
+```
+
+### Step 2 — AI researcher (np-ai-researcher, sonnet)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-ai-researcher --profile balanced)
+# Spawn agent=np-ai-researcher model=$MODEL
+#   input: ai_spec_path=$AI_SPEC_PATH (framework from step 1 already present)
+#   output: sections 3 (Implementation) + 4b (Pydantic models) of AI-SPEC.md
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-ai-researcher --tier sonnet --resolved-model "$MODEL" \
+  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+  --started "$START" --ended "$END" \
+  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+  --retry-count 0 --status ok --runtime "$RUNTIME"
+```
+
+### Step 3 — Domain researcher (np-domain-researcher, sonnet)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-domain-researcher --profile balanced)
+# Spawn agent=np-domain-researcher model=$MODEL
+#   input: ai_spec_path=$AI_SPEC_PATH
+#   output: section 1b (Domain Context) of AI-SPEC.md
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-domain-researcher --tier sonnet --resolved-model "$MODEL" \
+  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+  --started "$START" --ended "$END" \
+  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+  --retry-count 0 --status ok --runtime "$RUNTIME"
+```
+
+### Step 4 — Eval planner (np-eval-planner, opus)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-eval-planner --profile balanced)
+# Spawn agent=np-eval-planner model=$MODEL
+#   input: ai_spec_path=$AI_SPEC_PATH (domain rubrics from step 3 ground the dimensions)
+#   output: sections 5 (Eval Dimensions), 6 (Guardrails), 7 (Monitoring)
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-eval-planner --tier opus --resolved-model "$MODEL" \
+  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+  --started "$START" --ended "$END" \
+  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+  --retry-count 0 --status ok --runtime "$RUNTIME"
+```
+
+## Validation Gate
+
+After all 4 agents finish, grep the completed AI-SPEC.md for the required
+section headers. Missing any → ask the user to re-run that step or accept
+with warnings.
+
+```bash
+MISSING=""
+for SECTION in "## 1b. Domain Context" "## 2. Framework Selection" "## 3. Implementation" "## 5. Eval Dimensions" "## 6. Guardrails"; do
+  if ! grep -qF "$SECTION" "$AI_SPEC_PATH"; then
+    MISSING="$MISSING\n  - missing: $SECTION"
+  fi
+done
+
+if [[ -n "$MISSING" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "AI-SPEC validation — missing sections",
+    "question": "Some required AI-SPEC sections are missing. What would you like to do?",
+    "options": [
+      {"label": "Re-run eval planner",  "description": "Spawn np-eval-planner once more with current AI-SPEC state."},
+      {"label": "Accept with warnings", "description": "Proceed and surface the gaps in the commit message."},
+      {"label": "Abort",                "description": "Exit without committing."}
+    ]
+  }')
+  case "$CHOICE" in
+    "Abort") exit 1 ;;
+  esac
+fi
+```
+
+## Commit
+
+```bash
+git add "$AI_SPEC_PATH"
+git commit -m "docs(${PADDED}): generate AI-SPEC.md via 4-agent chain"
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Run the 4 agents in strict serial order (selector → ai → domain → eval).
+- Emit a metrics record AFTER every Task spawn (D-06).
+- Resolve every MODEL via `np-tools.cjs resolve-model` — no hardcoded IDs.
+- Use `np-tools.cjs askuser` for every prompt (Phase-3 INST-03 invariant).
+- Commit the final AI-SPEC.md when validation passes or the user accepts.
+
+**Don't:**
+- Invoke the host-specific prompt tool directly — always route through `np-tools.cjs askuser`.
+- Parallelize the chain — later agents read what earlier agents wrote.
+- Call any tools binary other than `np-tools.cjs` (the sole CLI entry per Plan 09-05 D-14).
+- Reference legacy homedir payload paths — those directories do not exist
+  in nubos-pilot projects.
+- Skip any metrics record block — the Phase-10 np:stats consumer expects
+  one record per Task spawn.
+</scope_guardrail>
+
+## Output
+
+- `{phase_dir}/{padded}-AI-SPEC.md` — filled-in AI design contract
+- 4 metrics records in `.nubos-pilot/metrics/phase-${PHASE}.jsonl`
+- One git commit (when validation passes or user accepts with warnings)

package/workflows/autonomous.md

@@ -0,0 +1,94 @@
+---
+command: np:autonomous
+description: In-session auto-advance loop — runs phase after phase, asking the user between phases. NOT a daemon (ADR-0001 No-Daemon Invariant).
+---
+
+# /np:autonomous
+
+<objective>
+Iterate `resolveGate` → `/np:execute-phase` → `/np:verify-work` → askUser
+until the user says stop. The loop is an in-session for-loop executed by
+the host agent — it does NOT fork, spawn a detached process, or survive
+session end (ADR-0001).
+</objective>
+
+## Initialize
+
+```bash
+PHASE="$1"
+GATE_JSON=$(node np-tools.cjs init autonomous "$PHASE")
+```
+
+Parse: `status` (ok | advancement-blocked), `gate.rule`, `gate.task`.
+
+If `status == advancement-blocked`:
+
+```bash
+CHOICE=$(node np-tools.cjs askuser --json '{
+  "type": "select",
+  "header": "Phase kann nicht fortschreiten",
+  "question": "Jede Pending-Task in Wave 1 ist skipped oder parked. Was tun?",
+  "options": [
+    {"label": "Unpark tasks and continue", "description": "Dispatch /np:unpark zur Reaktivierung, dann erneut /np:autonomous starten."},
+    {"label": "Abort",                      "description": "Exit; User entscheidet manuell."}
+  ]
+}')
+exit 0
+```
+
+## Execution — in-session loop (NO daemon, NO background)
+
+The loop runs inside the agent context. Each iteration:
+
+1. Re-read gate for `$PHASE`: `node np-tools.cjs init autonomous "$PHASE"`.
+2. If `gate.rule == 1` → dispatch `/np:discuss-phase $PHASE`, wait for
+   completion, continue.
+3. If `gate.rule == 2` → dispatch `/np:plan-phase $PHASE`, wait, continue.
+4. If `gate.rule == 3` → dispatch `/np:execute-phase $PHASE`, wait, continue.
+5. If `gate.rule == 4` → dispatch `/np:verify-work $PHASE`, wait, continue.
+6. If `gate.rule == 5` → phase verified. Ask the user:
+
+```bash
+CHOICE=$(node np-tools.cjs askuser --json '{
+  "type": "select",
+  "header": "Phase verifiziert",
+  "question": "Phase '"$PHASE"' ist verified. Weitermachen mit der nächsten Phase?",
+  "options": [
+    {"label": "Continue",  "description": "Nächste Phase automatisch starten."},
+    {"label": "Pause",     "description": "Stop, handoff via /np:pause-work."},
+    {"label": "Abort",     "description": "Exit."}
+  ]
+}')
+case "$CHOICE" in
+  "Continue") PHASE=$((PHASE + 1));;
+  "Pause")    node np-tools.cjs init pause-work; exit 0 ;;
+  "Abort")    exit 0 ;;
+esac
+```
+
+## Hard-stops (D-15)
+
+- Any `NubosPilotError` with severity fatal → exit non-zero immediately.
+- commit-task loud-fails (gitignored-only) → propagate, do not retry.
+- `advancement-blocked` → askUser gate above, never silent spin.
+
+## Scope Guardrail
+
+<!-- scope_guardrail -->
+**Do:**
+- Drive the loop inside the current agent session.
+- Ask the user at every phase boundary (D-14).
+- Respect `resolveGate` outputs verbatim.
+
+**Don't:**
+- Fork, `setInterval`, `nohup`, `spawn --detached`, or `&` the loop body —
+  ADR-0001 bans daemon behavior (T-06-14).
+- Skip the inter-phase askUser gate.
+- Silently advance past a Fail verdict from `/np:verify-work`.
+<!-- /scope_guardrail -->
+
+## Output
+
+- N phases advanced (N = user choice count).
+- Full audit trail in per-phase `PLAN-REVIEW.md` + `VERIFICATION.md`.
+- Session ends cleanly; resume via `/np:resume-work`.

package/workflows/cleanup.md

@@ -0,0 +1,325 @@
+---
+command: np:cleanup
+description: Archive completed milestones to .nubos-pilot/archive/v<X.Y>/ (D-06). Collapses each archived milestone's ROADMAP.md block into a <details> summary (D-07). Idempotent per D-08 (target-path existence check). One atomic chore commit (D-09). Path-preserving git mv (rename history kept).
+---
+
+# np:cleanup
+
+Implements UTIL-08. Enumerates milestones whose every phase is marked
+complete, previews the archive plan, moves phase directories into
+`.nubos-pilot/archive/v<X.Y>/` with `git mv` (preserving rename
+history), collapses the milestone's ROADMAP.md block into a
+`<details>` wrapper via `lib/roadmap.cjs.collapseMilestone` (landed
+Plan 10-01-T05), and commits the whole operation as a single atomic
+chore unit.
+
+Four deliberate design choices:
+
+- **D-06** — archive layout lives at `.nubos-pilot/archive/v<X.Y>/`,
+  the canonical home under the project-state tree (ADR-0005
+  3-file-tree invariant).
+- **D-07** — collapsed milestones render as `<details>` blocks in
+  the generated ROADMAP.md rather than being deleted. Milestone
+  history stays visible on demand.
+- **D-08** — idempotency. If `archive/v<X.Y>/` already exists for a
+  milestone, the workflow skips it. Partial-move recovery is safe
+  because per-milestone state is all-or-nothing.
+- **D-09** — single atomic commit per run. All milestones archived
+  in one invocation land in one commit (ADR-0004).
+
+Security-relevant defenses built in:
+
+- **T-10-06-03 (partial-move)** — idempotent skip + per-mv failure
+  abort + single commit after ALL mvs succeed.
+- **T-10-06-04 (symlink traversal)** — `lstat`-based reject before
+  every `git mv` (pattern reused from Phase 7 Plan 07-02 backup.cjs).
+
+Pure CRUD / filesystem workflow — no agent spawn, no resolve-model,
+no metrics record. Pitfall 9 / `workflow-missing-metrics` is exempt.
+
+## Initialize
+
+```bash
+STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+ARCHIVE_ROOT="${STATE_DIR}/archive"
+mkdir -p "$ARCHIVE_ROOT"
+
+DRY_RUN_FLAG=""
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN_FLAG="1" ;;
+  esac
+done
+```
+
+## Enumerate Completed Milestones
+
+All enumeration happens in Node so we can consume `lib/roadmap.cjs`
+parse output directly (not re-implement YAML parsing). The query
+filters: (a) skip the synthetic `backlog` milestone, (b) require
+every phase in the milestone to have `status === "complete"`, (c)
+skip if `archive/<id>/` already exists (D-08 idempotency), (d) list
+the phase directories that exist on disk.
+
+```bash
+ACTIONS_JSON=$(node -e '
+  const { parseRoadmap } = require("./lib/roadmap.cjs");
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const stateDir = process.argv[1];
+  const archive = path.join(stateDir, "archive");
+  const phasesRoot = path.join(stateDir, "phases");
+  const parsed = parseRoadmap(process.cwd());
+  const raw = parsed && parsed.doc ? parsed.doc : null;
+  const out = [];
+  for (const m of (raw && raw.milestones) || []) {
+    if (!m || m.id === "backlog") continue;
+    const phases = m.phases || [];
+    if (phases.length === 0) continue;
+    const allDone = phases.every((ph) => ph && ph.status === "complete");
+    if (!allDone) continue;
+    const target = path.join(archive, m.id);
+    if (fs.existsSync(target)) continue;
+    let entries = [];
+    try { entries = fs.readdirSync(phasesRoot, { withFileTypes: true }); } catch (_e) {}
+    const phaseDirs = [];
+    for (const ph of phases) {
+      const padded = String(ph.number).padStart(2, "0");
+      const match = entries.filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .find((n) => n === padded || n.startsWith(padded + "-"));
+      if (match) phaseDirs.push(path.join(phasesRoot, match));
+    }
+    if (phaseDirs.length === 0) continue;
+    out.push({ milestone_id: m.id, target_dir: target, phase_dirs: phaseDirs });
+  }
+  process.stdout.write(JSON.stringify(out));
+' "$STATE_DIR")
+
+ACTION_COUNT=$(echo "$ACTIONS_JSON" | jq 'length')
+if [[ "$ACTION_COUNT" -eq 0 ]]; then
+  echo "Nothing to archive (no complete + un-archived milestones)."
+  exit 0
+fi
+```
+
+## Symlink Safety Check (T-10-06-04)
+
+Before any `git mv`, `lstat` each phase directory and reject
+symlinks. A symlinked phase dir would escape the archive root on
+rename (the link target might point outside `.nubos-pilot/phases/`).
+Pattern reused from Phase 7 Plan 07-02 `backup.cjs`.
+
+```bash
+SYMLINK_FOUND=$(node -e '
+  const fs = require("node:fs");
+  const actions = JSON.parse(process.argv[1]);
+  for (const a of actions) {
+    for (const d of a.phase_dirs) {
+      try {
+        const st = fs.lstatSync(d);
+        if (st.isSymbolicLink()) { process.stdout.write(d); process.exit(0); }
+      } catch (_e) {}
+    }
+  }
+' "$ACTIONS_JSON")
+if [[ -n "$SYMLINK_FOUND" ]]; then
+  echo "Error: symlink detected at $SYMLINK_FOUND — refusing to archive. Remove or unlink and retry." >&2
+  exit 1
+fi
+```
+
+## Dry-Run Summary + askuser Confirm
+
+Show the plan before mutating anything. `--dry-run` exits after the
+preview; otherwise confirm via `askuser` Pattern S-3.
+
+```bash
+echo "$ACTIONS_JSON" | jq -r '.[] | "Milestone " + .milestone_id + ":\n  → " + .target_dir + "\n  Phases: " + ([.phase_dirs[] | split("/") | last] | join(", "))'
+
+if [[ -n "$DRY_RUN_FLAG" ]]; then
+  echo "Dry-run: no changes made."
+  exit 0
+fi
+
+CHOICE=$(node np-tools.cjs askuser --json '{
+  "type": "select",
+  "header": "Cleanup Preview",
+  "question": "Archive '"$ACTION_COUNT"' milestone(s) listed above?",
+  "options": [
+    {"label": "Yes — archive listed phases", "description": "Creates .nubos-pilot/archive/<id>/ + ROADMAP details-block + 1 atomic commit"},
+    {"label": "Cancel", "description": "Exits without mutation"}
+  ]
+}')
+case "$CHOICE" in
+  "Cancel"*) exit 0 ;;
+esac
+```
+
+## Execute Archive
+
+Per-milestone loop: create the archive target dir, re-`lstat` every
+phase directory IMMEDIATELY before each `git mv` and abort if a
+symlink is detected, then call `lib/roadmap.cjs.collapseMilestone`
+to flip the `collapsed: true` flag so `lib/roadmap-render.cjs` wraps
+the block in a `<details>` summary (landed Plan 10-01-T05).
+
+The symlink re-check is intentionally collocated with `git mv`
+inside ONE Node process (no intermediate bash fork) so there is no
+TOCTOU window between check and move. The earlier "Symlink Safety
+Check" section is a defense-in-depth pre-flight that fails fast
+before the askuser confirm; this block is the authoritative
+just-in-time guard (T-10-06-04 mitigation).
+
+```bash
+node -e '
+  const fs = require("node:fs");
+  const { execFileSync } = require("node:child_process");
+  const { collapseMilestone } = require("./lib/roadmap.cjs");
+  const actions = JSON.parse(process.argv[1]);
+  for (const a of actions) {
+    fs.mkdirSync(a.target_dir, { recursive: true });
+    for (const src of a.phase_dirs) {
+      const st = fs.lstatSync(src);
+      if (st.isSymbolicLink()) {
+        process.stderr.write("Error: symlink detected at " + src + " — refusing to archive.\n");
+        process.exit(1);
+      }
+      try {
+        execFileSync("git", ["mv", src, a.target_dir + "/"], { stdio: "inherit" });
+      } catch (err) {
+        process.stderr.write("git mv failed on " + src + "\n");
+        process.exit(1);
+      }
+    }
+    collapseMilestone(a.milestone_id);
+  }
+' "$ACTIONS_JSON"
+```
+
+`git mv` preserves rename history (per Plan §interfaces / Research
+§4) — later blame/log on the archived files still traces back
+through the rename.
+
+## Commit (D-09)
+
+Single atomic commit per run. All milestones archived together land
+in one `chore(10): ...` commit. Subject line names the first
+milestone and a count suffix when N > 1.
+
+```bash
+FIRST_MILESTONE=$(echo "$ACTIONS_JSON" | jq -r '.[0].milestone_id')
+SUFFIX=""
+if [[ "$ACTION_COUNT" -gt 1 ]]; then
+  SUFFIX=" and $((ACTION_COUNT - 1)) other(s)"
+fi
+node np-tools.cjs commit "chore(10): archive milestone ${FIRST_MILESTONE}${SUFFIX}" \
+  --files "${STATE_DIR}/archive/" "${STATE_DIR}/ROADMAP.md" "${STATE_DIR}/roadmap.yaml" "${STATE_DIR}/phases/"
+```
+
+## If a cleanup is interrupted
+
+If `git mv` fails mid-operation (power loss, Ctrl-C), the working
+tree may be in a mixed state — some phase dirs moved, some not.
+Running `/np:cleanup` again is SAFE because:
+
+- **Per-milestone idempotency (D-08):** milestones whose archive
+  target dir already exists are skipped.
+- Within a milestone, `git mv` on a non-existent source fails
+  loudly; the workflow aborts WITHOUT committing.
+
+If you see a partial state, either:
+
+1. Run `/np:cleanup` again — re-processes only the un-archived
+   milestones.
+2. Manually `git mv` the remaining phase dirs into their archive
+   target, then run
+   `node -e "require('./lib/roadmap.cjs').collapseMilestone('v<X.Y>')"`
+   and commit manually.
+
+No automatic `git reset --hard HEAD` is performed — that would
+destroy unrelated uncommitted work (Open Question #3 recommendation,
+T-10-06-03 mitigation).
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Use `git mv` (not plain `mv`) — preserves rename history for
+  `git blame` / `git log --follow`.
+- Check target-dir existence BEFORE attempting mvs (D-08
+  idempotency).
+- Reject symlinks via `lstat` before every `git mv` (T-10-06-04).
+- Single atomic commit after ALL mvs + `collapseMilestone` mutations
+  succeed (D-09).
+- Show the dry-run preview before any mutation (S-3 pattern).
+
+**Don't:**
+- `git reset --hard` on failure (destroys unrelated user work per
+  Open Question #3 / T-10-06-03).
+- Mutate archive targets that already exist (idempotency).
+- Skip the `collapseMilestone` call — ROADMAP must reflect the
+  archive state (D-07).
+- Invoke host-specific prompt tools directly (the BARE_ASKUSER lint
+  in `bin/check-workflows.cjs` blocks them) — route through
+  `node np-tools.cjs askuser --json '…'`.
+- Add a `metrics record` block. No Task/Spawn site; Pitfall 9 /
+  `workflow-missing-metrics` is exempt.
+</scope_guardrail>
+
+## Output
+
+- `.nubos-pilot/archive/v<X.Y>/` — one directory per archived
+  milestone containing the milestone's phase dirs (moved via
+  `git mv`, rename history preserved).
+- `.nubos-pilot/ROADMAP.md` — regenerated with `<details>` wrapper
+  around each archived milestone's block (D-07 via
+  `lib/roadmap.cjs.collapseMilestone`).
+- `.nubos-pilot/roadmap.yaml` — `collapsed: true` and `collapsed_at`
+  set for each archived milestone.
+- `.nubos-pilot/phases/` — archived phase dirs removed.
+- One atomic git commit
+  `chore(10): archive milestone <id> [and N other(s)]` (ADR-0004,
+  D-09).
+
+## Success Criteria
+
+- [ ] Synthetic `backlog` milestone is never archived.
+- [ ] Only milestones with `every phase status === "complete"` are
+      considered.
+- [ ] Milestones whose archive target already exists are skipped
+      (D-08 idempotency).
+- [ ] Symlinks in candidate phase dirs abort the workflow
+      (T-10-06-04 mitigation).
+- [ ] `--dry-run` exits after the preview with no mutation.
+- [ ] Confirmation via `askuser` Pattern S-3 before any mutation.
+- [ ] Phase dirs moved via `git mv` (preserves rename history).
+- [ ] `lib/roadmap.cjs.collapseMilestone` called for every archived
+      milestone (D-07).
+- [ ] Single atomic commit via `np-tools.cjs commit` after ALL mvs +
+      collapseMilestone calls succeed (D-09).
+- [ ] Commit subject shape `chore(10): archive milestone <id>
+      [and N other(s)]`.
+- [ ] Partial-move recovery is idempotent — re-running picks up
+      only un-archived milestones (T-10-06-03 mitigation).
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations, no DIRECT_READ matches.
+
+## Related Workflows
+
+- **`/np:session-report`** — per-session snapshot report (distinct
+  from milestone archival).
+- **`/np:stats`** — read-only current-state view.
+- **`/np:add-backlog <title>`** — adds ideas to the synthetic
+  backlog milestone (which `/np:cleanup` deliberately never
+  archives).
+
+## Design Notes
+
+D-06 fixes archive layout at `.nubos-pilot/archive/v<X.Y>/` — the
+canonical home under the project-state tree (ADR-0005). D-07 collapse
+renders archived milestones as `<details>` blocks instead of deleting
+them so history stays visible on demand. D-08 idempotency via
+existence-check enables safe re-runs. D-09 single-commit shape matches
+ADR-0004. Symlink rejection via `lstat` (T-10-06-04) and path-preserving
+`git mv` guard against filesystem-level surprises.