nubos-pilot 0.7.0 → 0.7.2

package/bin/np-tools/worktree-list.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+const { listSliceWorktrees } = require('../../lib/worktree.cjs');
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const list = listSliceWorktrees(cwd);
+  stdout.write(JSON.stringify(list) + '\n');
+  return 0;
+}
+
+module.exports = { run };

package/bin/np-tools/worktree-remove.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { removeSliceWorktree } = require('../../lib/worktree.cjs');
+
+function _parseArgs(args) {
+  const out = { sliceFullId: null, force: false, keepBranch: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--force') { out.force = true; continue; }
+    if (a === '--keep-branch') { out.keepBranch = true; continue; }
+    if (!a.startsWith('-') && !out.sliceFullId) out.sliceFullId = a;
+  }
+  return out;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+  if (!parsed.sliceFullId) {
+    throw new NubosPilotError(
+      'worktree-remove-missing-slice',
+      'slice full-id required (e.g. M001-S001)',
+      {},
+    );
+  }
+  const result = removeSliceWorktree(
+    parsed.sliceFullId,
+    cwd,
+    { force: parsed.force, deleteBranch: !parsed.keepBranch },
+  );
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/docs/adr/0008-worktree-isolation-per-slice.md

@@ -0,0 +1,140 @@
+# ADR-0008: Worktree Isolation per Slice
+
+* Status: **Accepted**
+* Date: 2026-04-23
+* Accepted: 2026-04-23 (all 11 decisions D-8.1..D-8.11 ratified at defaults)
+* Supersedes: None
+* Relates-to: [ADR-0001](0001-no-daemon-invariant.md), [ADR-0004](0004-atomic-commit-per-unit.md), [ADR-0005](0005-three-orthogonal-file-trees.md)
+
+## Context and Problem Statement
+
+Today the `np-executor` edits, verifies, and commits directly on the user's active branch. Three failure modes follow:
+
+* **Cross-contamination** — if execution is interrupted mid-slice (crash, timeout, manual abort), half-applied edits pollute the user's working tree. Recovery requires manual `git restore` judgment calls.
+* **No inspection point** — once a slice is merged (or aborted) its intermediate state is lost. Post-mortem analysis of "what did the executor do before it broke" requires git-stash archaeology.
+* **No parallelism pathway** — two unrelated slices of the same milestone cannot run concurrently because they share one working tree. Even when parallelism is NOT the immediate goal, the single-working-tree assumption blocks it forever.
+
+Octogent (hesamsheikh/octogent) solves adjacent problems via per-job "tentacle" worktrees. The question is whether a similar isolation layer fits nubos-pilot without violating existing invariants (ADR-0001 no-daemon, ADR-0004 atomic commits, ADR-0005 three file-trees).
+
+## Decision Drivers
+
+* **Reversibility** — a failed slice must not leave the user's working tree dirty. Rollback = delete worktree.
+* **Inspectability** — post-execution, the worktree of a slice (passed or failed) can be opened in an editor and examined like any git-checkout.
+* **No-daemon preservation** — the mechanism must work with plain `git worktree add/remove` inside the bash blocks of each workflow; no long-running coordinator, no RPC.
+* **ADR-0004 preservation** — atomic-commit-per-unit survives. Each task commit lands as-is on the slice branch; merge-back must be fast-forward so history stays linear and `np:undo-task` still resolves to a single SHA.
+* **ADR-0005 preservation** — the Project-State tree (`.nubos-pilot/`) stays single-writer-single-location; worktrees reference it, do not duplicate it.
+* **Backward compatibility** — existing projects and existing slices must continue to work without worktree mode. The feature is additive, not a hard migration.
+* **Host-simplicity** — nubos-pilot must not require the user to clean up stray worktrees manually in the common case.
+
+## Considered Options
+
+* **A — Status quo (no worktree isolation).** Rejected: the failure modes above are real and will only compound as nubos-pilot is used on longer milestones.
+* **B — Worktree per task.** Rejected: per-task worktrees multiply disk usage and setup/teardown cost without proportional benefit — tasks within a slice are already atomic via ADR-0004; the isolation need is at slice boundaries (multiple tasks running as one unit of work).
+* **C — Worktree per slice, opt-in via config, merge-back fast-forward.** **Chosen.**
+* **D — Branch-only isolation (no separate working tree).** Rejected: still shares one working tree across slices; solves nothing that's actually broken.
+* **E — External worktree location (`~/.nubos-pilot/worktrees/<hash>/`).** Rejected: cross-project path management, cleanup ambiguity, surprises for users who expect `rm -rf .nubos-pilot/` to remove everything.
+
+## Decision Outcome
+
+Chosen: **Option C — Worktree per slice, opt-in via config, merge-back fast-forward.**
+
+### Open Decisions (need explicit sign-off before implementation)
+
+The ADR captures the currently-recommended defaults; each is marked **[DEFAULT]** and the alternative is documented so a reviewer can dissent before code is written.
+
+#### D-8.1 — Activation
+
+* **[DEFAULT]** Opt-in via `workflow.worktree_isolation: false` in `.nubos-pilot/config.json`. Default off.
+* **Alternative:** Default on for all new projects (detected via absent config key).
+* **Rationale for default:** Additive feature; zero surprise for existing projects. Opting in is one line of config.
+
+#### D-8.2 — Worktree Location
+
+* **[DEFAULT]** `.nubos-pilot/worktrees/<milestone-id>/<slice-id>/` — inside the Project-State tree.
+* **Alternative A:** `../<repo-name>-worktrees/<milestone-id>/<slice-id>/` — sibling directory.
+* **Alternative B:** `~/.nubos-pilot/worktrees/<project-hash>/…` — user-home, cross-project.
+* **Rationale for default:** Matches octogent convention; single cleanup target (`rm -rf .nubos-pilot/`); survives ADR-0005 because worktrees are a git-runtime artifact adjacent to state (analog to `.nubos-pilot/checkpoints/`), not a fourth file-tree.
+
+#### D-8.3 — Shared State Resolution
+
+* **[DEFAULT]** `.nubos-pilot/` lives **only** in the main workspace. The worktree references it via its absolute path (resolved on worktree-create, stored in `.nubos-pilot/worktrees/<mid>/<sid>/.np-origin` for recovery).
+* **Alternative:** Symlink `.nubos-pilot/` into each worktree.
+* **Rationale for default:** Symlinks break on Windows without developer mode; absolute-path reference is portable. All CLI commands already accept a `cwd` argument — we pass the main-workspace path explicitly from inside the worktree.
+
+#### D-8.4 — Branch Naming
+
+* **[DEFAULT]** `np/<milestone-id>-<slice-id>` (e.g. `np/M001-S001`).
+* **Alternative:** `np/<milestone-id>-<slice-id>-<slug>`.
+* **Rationale for default:** Deterministic, short, scriptable. Slug adds no machine value and may drift from the slice-name frontmatter.
+
+#### D-8.5 — Base Branch
+
+* **[DEFAULT]** Worktree branches off the **current HEAD of the invoking workspace** at slice-start time.
+* **Alternative:** Always branches off a configured base (`config.git.base_branch`, e.g. `development`).
+* **Rationale for default:** Matches user expectation ("executor works from where I am"). Users on Nubos-Platform are on `development` per memory; this is already handled.
+
+#### D-8.6 — Commit Flow
+
+* **[DEFAULT]** Executor `cd`s into the worktree; `commit-task` runs inside the worktree and commits to `np/<mid>-<sid>`. Each task is its own atomic commit (ADR-0004 preserved).
+* **Alternative:** Executor stays in main workspace, operates on worktree via `git -C <worktree-path> …`.
+* **Rationale for default:** `cd`-based is what every other `np:*` workflow already assumes. `git -C` would require every child command to know about the worktree path.
+
+#### D-8.7 — Merge-Back Strategy
+
+* **[DEFAULT]** Fast-forward merge only. After all tasks of a slice pass verify + commit, the workflow runs `git merge --ff-only np/<mid>-<sid>` from the main workspace. If FF is impossible (main branch advanced during execution), workflow stops and surfaces the conflict to the user for manual resolve.
+* **Alternative A:** Rebase the slice branch onto current main, then FF.
+* **Alternative B:** Three-way merge with auto-commit.
+* **Rationale for default:** Preserves linear history (so `git log --oneline --grep='^task('` stays a plan-trace per ADR-0004). Surfacing conflicts to the user is the honest failure mode; auto-rebase can silently rewrite task commits, breaking `np:undo-task` SHA resolution.
+
+#### D-8.8 — Parallelism
+
+* **[DEFAULT]** Sequential execution only in this ADR. The worktree mechanism *enables* parallelism but does not introduce it. Parallel execution would require a disjoint-file-set check between slices and is **out of scope for ADR-0008** — a separate ADR-0009 would address it.
+* **Rationale:** Isolation ≠ speedup. Ship the isolation property first; measure real-world merge-conflict rates before adding concurrency.
+
+#### D-8.9 — Cleanup Policy
+
+* **[DEFAULT]** After successful merge-back and commit, worktree is removed via `git worktree remove` and branch `np/<mid>-<sid>` is deleted. A failed slice leaves the worktree in place for inspection; cleanup is manual via `np:reset-slice`.
+* **Alternative:** Retention period (e.g. keep successful worktrees for 24h).
+* **Rationale for default:** Disk usage and clutter dominate once many slices ship. Retention complicates reasoning; inspection of successful slices is served by `git log` on main.
+
+#### D-8.10 — Crash Recovery
+
+* **[DEFAULT]** `resume-work` detects `.nubos-pilot/worktrees/<mid>/<sid>/` and re-enters it. If the worktree is unsalvageable (corrupt git state), `np:reset-slice` now also runs `git worktree remove --force` on the slice's worktree.
+* **Rationale:** Maps the existing crash-recovery story onto the new artifact.
+
+#### D-8.11 — Gitignore / Commit Policy
+
+* **[DEFAULT]** `.nubos-pilot/worktrees/` is **always gitignored**, regardless of `workflow.commit_artifacts`. Committing worktree contents would duplicate the repo inside itself.
+* **Rationale:** Hard safety rule. Install step adds `.nubos-pilot/worktrees/` to `.gitignore` when worktree isolation is first enabled.
+
+### Consequences
+
+**Good, because:**
+
+* A failed slice leaves the main workspace clean; recovery is deletion, not fix-up.
+* Post-mortem of any slice (passed or failed) is a `cd .nubos-pilot/worktrees/<mid>/<sid>/` away.
+* Linear task-commit history survives (FF-merge); ADR-0004 undo semantics unchanged.
+* Opt-in model: legacy projects untouched until a user flips the config flag.
+* Worktree mechanism paves the path to parallel slices (ADR-0009, future) without re-architecting.
+
+**Bad, because:**
+
+* Disk usage grows per active slice (full working-tree copy — git worktrees share `.git` but not working-tree contents).
+* Users must learn one new directory (`.nubos-pilot/worktrees/`) and one new CLI surface (`worktree list|prune|inspect` if we add it).
+* FF-merge constraint is strict: if the user force-updates the main branch mid-slice, the slice must be rebased or discarded. This is an intentional sharp edge.
+* Merge-back semantics may surprise users on Nubos-Platform's `development` → `main` reconcile flow (memory: "MRs development→main werden gesquasht"). The ADR does not change squash-merge — that happens at MR time, not slice time. Needs explicit test.
+
+## More Information
+
+* **ADR-0004 preservation test:** after implementing, `git log --oneline --grep='^task(' origin/main` must still return one line per committed task — no squash, no merge-commit noise.
+* **ADR-0005 preservation:** the worktree physically contains code under `.nubos-pilot/worktrees/`, but that code is a git-working-tree view of the Source tree, not a copy, not state. `.nubos-pilot/` (state) still lives once, in the main workspace.
+* **Out of scope:** parallel slices (ADR-0009), cross-milestone worktree pooling, worktree-based dev-mode (`np:dev --worktree` shell), TUI dashboard for worktree status (part of #4 in the octogent roadmap).
+* **Implementation phasing (post-approval):**
+  1. `lib/worktree.cjs` — create/list/remove/prune/ff-merge.
+  2. `lib/worktree.test.cjs` — unit + integration (spawned git in sandbox).
+  3. `bin/np-tools/worktree-*.cjs` — CLI surfaces (`worktree-create`, `worktree-remove`, `worktree-list`, `worktree-ff-merge`).
+  4. `workflows/execute-phase.md` — conditional worktree-create at slice-start, ff-merge at slice-end.
+  5. `bin/np-tools/reset-slice.cjs` — worktree teardown path.
+  6. `bin/np-tools/resume-work.cjs` — worktree re-entry.
+  7. `bin/install/` — add `.nubos-pilot/worktrees/` to `.gitignore` when `worktree_isolation=true` is first set.
+  8. `lib/config-defaults.cjs` — `workflow.worktree_isolation: false`.

package/docs/adr/0009-tui-framework-for-dashboard.md

@@ -0,0 +1,95 @@
+# ADR-0009: TUI Framework for Interactive Dashboard (Amendment to ADR-0002)
+
+* Status: **Accepted — Option D (no TUI framework adopted)**
+* Date: 2026-04-23
+* Accepted: 2026-04-23
+* Amends: [ADR-0002](0002-zero-runtime-dependencies.md) — **no amendment takes effect.** ADR-0002's `dependencies: []` invariant stays intact.
+* Relates-to: [ADR-0001](0001-no-daemon-invariant.md), [ADR-0006](0006-yaml-dependency-amendment.md)
+
+## Context and Problem Statement
+
+The one-shot dashboard (`np-tools.cjs dashboard`, ADR-0008 adjacent, already shipped) renders milestone/slice/handoff/worktree state as a formatted block with ANSI colors, plus an optional `--watch <seconds>` mode that repeatedly clear-screens and re-renders. This satisfies read-only inspection well.
+
+A second user-facing surface is being requested: an **interactive** dashboard that supports keyboard-driven navigation — arrow keys through milestones/slices, `Enter` to drill into handoffs or task plans, `s`/`p` hotkeys to `skip`/`park` tasks in flight, flicker-free differential repainting. This is a concrete usability ask, not speculative scope.
+
+The question: **does nubos-pilot adopt a terminal-UI library to implement this, and if so, which one?**
+
+ADR-0002 makes `dependencies: []` the invariant. Only `yaml@^2.8` has been amended in (ADR-0006). Any TUI library is a new runtime dependency — so a new amendment is required per the ADR lifecycle.
+
+## Decision Drivers
+
+* **Install-anywhere preservation** — every extra transitive dep is payload size pulled on every `npx nubos-pilot` run.
+* **Supply-chain surface** — each dep (and each of its transitives) is attack surface and a future maintenance risk.
+* **Feature value** — does the interactive surface justify the cost?
+* **Maintenance status** — nubos-pilot survives by zero-surprise dependencies; a library abandoned by its author is a liability we do not want to inherit.
+* **ADR-0001 preservation** — a TUI library must not pull in a long-running daemon. Foreground, synchronous, user-interactive processes are fine (analog to `htop` / `top`).
+
+## Considered Options
+
+* **A — Adopt `ink` + React** — "React for the terminal", virtual-DOM diffing, component model, flicker-free repaint.
+* **B — Adopt `neo-blessed`** — fork of Christopher Jeffrey's `blessed`, maintained, ncurses-style widget framework. No React.
+* **C — Home-grown TUI on `readline` + ANSI escapes** — no dep. Manual cursor movement, manual double-buffer to avoid flicker, manual key-binding dispatch.
+* **D — Do nothing, ship only A+B (one-shot + `--watch`)** — no new dep, no interactive surface. Accept that drill-down lives in separate `handoff-read <id>` / `render-todo <slice>` calls.
+
+## Decision Outcome
+
+**Chosen: Option D — no TUI framework, no dependency.** The existing one-shot + `--watch` dashboard (shipped alongside ADR-0008) remains the only dashboard surface. Interactive drill-down is served by composing the existing CLI commands (`handoff-list`, `handoff-read`, `render-todo`, `checkpoint show`) — no bespoke TUI.
+
+ADR-0002's `dependencies: []` invariant (as amended by ADR-0006 for `yaml`) remains unchanged. No new runtime dependency is introduced by this ADR.
+
+### Why Option D was chosen
+
+1. **A+B already cover 80% of the value.** Read-only status at-a-glance is what most people mean by "dashboard". Drill-down is one CLI command away.
+2. **The drill-down surface exists already:** `handoff-read`, `render-todo`, `checkpoint show`, `metrics record`. All callable without a custom TUI.
+3. **Any dep is a one-way door** for `nubos-pilot`, given the install-anywhere promise. Reversing it later is a second ADR cycle.
+4. **Interactive hotkey mutation** (e.g. `p` to park a task from the dashboard) is a convenience, not a capability — `np:park <task-id>` already exists.
+
+### Revisiting this decision
+
+If concrete interactive-workflow gaps emerge from real use that A+B + existing CLI cannot serve, this ADR should be **superseded** (not rewritten) by a new ADR that adopts a specific framework. The recommended order at that time:
+
+* **B — `neo-blessed`** first: minimal transitive tree, no React, API stable, one library to audit.
+* **A — `ink`** second: React baggage (hooks, fiber, dev-tools) for a status view is heavy. The React mental model is a force-multiplier for teams already fluent in it; standalone it is overhead.
+* **C — home-grown** last: feasible but expensive. Cursor math, key-binding dispatch, double-buffer, Unicode-width calculation, terminal-capability detection — all must be hand-written. For a feature that's "nice to have" this trade is poor.
+
+### Consequences per option
+
+**If A (ink) is chosen:**
+- Good: React-literate maintainers can iterate fast.
+- Good: Flicker-free diff repainting via Virtual-DOM.
+- Bad: React transitive tree (`react`, `react-reconciler`, scheduler, several small utility libs). Several MB of install payload per `npx` invocation.
+- Bad: Ties the TUI to React's LTS cadence.
+
+**If B (neo-blessed) is chosen:**
+- Good: Smaller install payload, no React.
+- Good: Battle-tested widget set.
+- Bad: API is old-style (event-emitter + imperative layout). Not as ergonomic as ink's React model.
+- Bad: Maintenance is best-effort; the upstream `blessed` was abandoned and `neo-blessed` is a small-volunteer fork.
+
+**If C (home-grown) is chosen:**
+- Good: Zero dependencies. ADR-0002 stays unbent.
+- Good: Full control of rendering semantics.
+- Bad: Weeks of work that duplicate what libraries already do well.
+- Bad: Every new TUI feature is a manual re-implementation of patterns libraries give for free.
+
+**If D (no interactive) is chosen:**
+- Good: Status quo preserved; A+B ship as-is.
+- Good: One less future-breakage risk.
+- Bad: Users who wanted keyboard-driven drill-down get a CLI-composition answer instead.
+
+## Consequences
+
+**Good, because:**
+- ADR-0002's `dependencies: []` invariant (as amended by ADR-0006 for `yaml`) stays intact. Install-anywhere story is unchanged.
+- No new supply-chain surface. No CVE triage, no maintainer hand-off risk.
+- One less future-breakage risk.
+
+**Bad, because:**
+- Users who want keyboard-driven drill-down get a CLI-composition answer instead. `handoff-list --for X --status open | jq …`, then `handoff-read $(…)`, then `render-todo M001-S001`.
+- If a concrete workflow gap emerges later, we pay the full ADR-cycle cost to revisit.
+
+## More Information
+
+* Dashboard A+B already ships: `lib/dashboard.cjs`, `bin/np-tools/dashboard.cjs`, with `--json`, `--no-color`, `--watch [sec]` flags.
+* Interactive drill-down composes existing commands — `handoff-list --for X --status open | jq …`, `handoff-read $(…)`, `render-todo M001-S001`.
+* If this ADR is ever superseded to adopt a framework, `lib/dashboard.cjs` (snapshot collector) is already framework-agnostic and can be reused as-is.

package/lib/config-defaults.cjs

@@ -8,6 +8,7 @@ const DEFAULT_RESEARCH_TOOLS = Object.freeze({
 const DEFAULT_WORKFLOW = Object.freeze({
   commit_docs: true,
   commit_artifacts: true,
+  worktree_isolation: false,
   research_tools: DEFAULT_RESEARCH_TOOLS,
 });
 

package/lib/dashboard.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { listMilestones, listSlices, listTasks, mId } = require('./layout.cjs');
+
+const ANSI = Object.freeze({
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue:   '\x1b[34m',
+  cyan:   '\x1b[36m',
+  gray:   '\x1b[90m',
+});
+
+const STATUS_GLYPHS = Object.freeze({
+  'pending':     { glyph: '[ ]', color: ANSI.gray },
+  'in-progress': { glyph: '[~]', color: ANSI.yellow },
+  'done':        { glyph: '[x]', color: ANSI.green },
+  'skipped':     { glyph: '[-]', color: ANSI.dim },
+  'parked':      { glyph: '[!]', color: ANSI.red },
+});
+
+function _safeReadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); }
+  catch { return null; }
+}
+
+function _safeReadFile(p) {
+  try { return fs.readFileSync(p, 'utf-8'); }
+  catch { return null; }
+}
+
+function _taskStatus(planPath) {
+  const raw = _safeReadFile(planPath);
+  if (!raw) return 'pending';
+  try {
+    const { frontmatter } = extractFrontmatter(raw);
+    return typeof frontmatter.status === 'string' ? frontmatter.status : 'pending';
+  } catch { return 'pending'; }
+}
+
+function _collectMilestones(projectRoot) {
+  const out = [];
+  for (const m of listMilestones(projectRoot)) {
+    const meta = _safeReadJson(path.join(m.path, mId(m.number) + '-META.json')) || {};
+    const slices = [];
+    for (const s of listSlices(m.number, projectRoot)) {
+      const tasks = listTasks(m.number, s.number, projectRoot);
+      const counts = { total: 0, pending: 0, 'in-progress': 0, done: 0, skipped: 0, parked: 0 };
+      const statuses = [];
+      for (const t of tasks) {
+        const status = _taskStatus(t.plan_path);
+        statuses.push(status);
+        counts.total += 1;
+        if (Object.prototype.hasOwnProperty.call(counts, status)) counts[status] += 1;
+      }
+      slices.push({
+        id: s.id,
+        full_id: s.full_id,
+        counts,
+        task_statuses: statuses,
+      });
+    }
+    out.push({
+      id: m.id,
+      number: m.number,
+      name: typeof meta.name === 'string' ? meta.name : null,
+      status: typeof meta.status === 'string' ? meta.status : null,
+      slices,
+    });
+  }
+  return out;
+}
+
+function collectSnapshot(projectRoot) {
+  const cwd = projectRoot || process.cwd();
+  return { milestones: _collectMilestones(cwd) };
+}
+
+function _summarizeCounts(c, useColor) {
+  const paint = (code, text) => useColor ? code + text + ANSI.reset : text;
+  const bits = [];
+  if (c.done)           bits.push(paint(ANSI.green,  c.done           + ' done'));
+  if (c['in-progress']) bits.push(paint(ANSI.yellow, c['in-progress'] + ' in-progress'));
+  if (c.pending)        bits.push(paint(ANSI.gray,   c.pending        + ' pending'));
+  if (c.skipped)        bits.push(paint(ANSI.dim,    c.skipped        + ' skipped'));
+  if (c.parked)         bits.push(paint(ANSI.red,    c.parked         + ' parked'));
+  return bits.join(' · ') || paint(ANSI.dim, 'no tasks');
+}
+
+function _checkboxRow(statuses, useColor) {
+  const parts = [];
+  for (const s of statuses) {
+    const g = STATUS_GLYPHS[s] || STATUS_GLYPHS.pending;
+    parts.push(useColor ? g.color + g.glyph + ANSI.reset : g.glyph);
+  }
+  return parts.join(' ');
+}
+
+function renderSnapshot(snap, opts) {
+  const o = opts || {};
+  const useColor = o.color !== false;
+  const c = (code, text) => useColor ? code + text + ANSI.reset : text;
+  const lines = [];
+
+  lines.push(c(ANSI.bold + ANSI.blue, 'nubos-pilot'));
+  lines.push('');
+
+  if (!snap.milestones || snap.milestones.length === 0) {
+    lines.push(c(ANSI.dim, 'No milestones yet. Run /np:new-project or /np:new-milestone.'));
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  for (const m of snap.milestones) {
+    const name = m.name ? ' — ' + m.name : '';
+    const status = m.status ? '  ' + c(ANSI.dim, '[' + m.status + ']') : '';
+    lines.push(c(ANSI.bold, m.id) + name + status);
+    if (m.slices.length === 0) {
+      lines.push('  ' + c(ANSI.dim, 'no slices planned'));
+    }
+    for (const s of m.slices) {
+      lines.push('  ' + c(ANSI.bold, s.full_id) + '  ' + _summarizeCounts(s.counts, useColor));
+      if (s.task_statuses.length > 0) {
+        lines.push('  ' + _checkboxRow(s.task_statuses, useColor));
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  collectSnapshot,
+  renderSnapshot,
+  ANSI,
+  STATUS_GLYPHS,
+};

package/lib/dashboard.test.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const dashboard = require('./dashboard.cjs');
+
+function _sandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-dashboard-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  return root;
+}
+
+function _writeTask(root, mNum, sNum, tNum, status, name) {
+  const mIdStr = 'M' + String(mNum).padStart(3, '0');
+  const sIdStr = 'S' + String(sNum).padStart(3, '0');
+  const tIdStr = 'T' + String(tNum).padStart(4, '0');
+  const fullId = mIdStr + '-' + sIdStr + '-' + tIdStr;
+  const dir = path.join(root, '.nubos-pilot', 'milestones', mIdStr, 'slices', sIdStr, 'tasks', tIdStr);
+  fs.mkdirSync(dir, { recursive: true });
+  const fm = [
+    '---',
+    'id: "' + fullId + '"',
+    'slice: "' + mIdStr + '-' + sIdStr + '"',
+    'milestone: "' + mIdStr + '"',
+    'type: execute',
+    'status: ' + status,
+    'tier: sonnet',
+    'owner: np-executor',
+    'wave: 1',
+    'depends_on: []',
+    'files_modified: []',
+    'autonomous: true',
+    'must_haves: {}',
+    '---',
+    '',
+    '# ' + fullId + ' — ' + name,
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(dir, tIdStr + '-PLAN.md'), fm, 'utf-8');
+}
+
+function _writeMeta(root, mNum, meta) {
+  const mIdStr = 'M' + String(mNum).padStart(3, '0');
+  const dir = path.join(root, '.nubos-pilot', 'milestones', mIdStr);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, mIdStr + '-META.json'), JSON.stringify(meta), 'utf-8');
+}
+
+test('DB-1: collectSnapshot returns only { milestones } shape', () => {
+  const root = _sandbox();
+  try {
+    const snap = dashboard.collectSnapshot(root);
+    assert.deepEqual(Object.keys(snap), ['milestones']);
+    assert.equal(Array.isArray(snap.milestones), true);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-2: collectSnapshot counts task statuses per slice', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 1, { name: 'Auth', status: 'active' });
+    _writeTask(root, 1, 1, 1, 'done', 'A');
+    _writeTask(root, 1, 1, 2, 'done', 'B');
+    _writeTask(root, 1, 1, 3, 'in-progress', 'C');
+    _writeTask(root, 1, 1, 4, 'pending', 'D');
+    _writeTask(root, 1, 1, 5, 'skipped', 'E');
+    const snap = dashboard.collectSnapshot(root);
+    assert.equal(snap.milestones.length, 1);
+    const m = snap.milestones[0];
+    assert.equal(m.id, 'M001');
+    assert.equal(m.name, 'Auth');
+    assert.equal(m.slices.length, 1);
+    assert.deepEqual(m.slices[0].counts, {
+      total: 5, pending: 1, 'in-progress': 1, done: 2, skipped: 1, parked: 0,
+    });
+    assert.deepEqual(m.slices[0].task_statuses, ['done', 'done', 'in-progress', 'pending', 'skipped']);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-3: renderSnapshot prints milestone, slice, checkbox row', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 1, { name: 'Auth', status: 'active' });
+    _writeTask(root, 1, 1, 1, 'done', 'Login');
+    _writeTask(root, 1, 1, 2, 'pending', 'Logout');
+    const snap = dashboard.collectSnapshot(root);
+    const out = dashboard.renderSnapshot(snap, { color: false });
+    assert.match(out, /^nubos-pilot/);
+    assert.match(out, /M001 — Auth/);
+    assert.match(out, /\[active\]/);
+    assert.match(out, /M001-S001/);
+    assert.match(out, /1 done/);
+    assert.match(out, /1 pending/);
+    assert.match(out, /\[x\] \[ \]/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-4: renderSnapshot shows "No milestones yet" when none exist', () => {
+  const root = _sandbox();
+  try {
+    const snap = dashboard.collectSnapshot(root);
+    const out = dashboard.renderSnapshot(snap, { color: false });
+    assert.match(out, /No milestones yet/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-5: renderSnapshot with color=false emits no ANSI codes', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 1, { name: 'Auth' });
+    _writeTask(root, 1, 1, 1, 'done', 'X');
+    const snap = dashboard.collectSnapshot(root);
+    const out = dashboard.renderSnapshot(snap, { color: false });
+    assert.equal(/\x1b\[/.test(out), false, 'render with color=false must not emit ANSI');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-6: renderSnapshot with default color includes ANSI codes', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 1, { name: 'Auth' });
+    _writeTask(root, 1, 1, 1, 'done', 'X');
+    const snap = dashboard.collectSnapshot(root);
+    const out = dashboard.renderSnapshot(snap);
+    assert.match(out, /\x1b\[/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-7: STATUS_GLYPHS covers all task-status enum values', () => {
+  for (const s of ['pending', 'in-progress', 'done', 'skipped', 'parked']) {
+    assert.ok(dashboard.STATUS_GLYPHS[s], 'missing glyph for ' + s);
+  }
+});
+
+test('DB-8: empty slice (no tasks) renders "no tasks" indicator', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 1, { name: 'Empty' });
+    fs.mkdirSync(path.join(root, '.nubos-pilot', 'milestones', 'M001', 'slices', 'S001', 'tasks'), { recursive: true });
+    const snap = dashboard.collectSnapshot(root);
+    const out = dashboard.renderSnapshot(snap, { color: false });
+    assert.match(out, /M001-S001/);
+    assert.match(out, /no tasks/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('DB-9: multiple milestones render in numeric order', () => {
+  const root = _sandbox();
+  try {
+    _writeMeta(root, 2, { name: 'Second' });
+    _writeMeta(root, 1, { name: 'First' });
+    _writeTask(root, 1, 1, 1, 'done', 'X');
+    _writeTask(root, 2, 1, 1, 'pending', 'Y');
+    const snap = dashboard.collectSnapshot(root);
+    assert.equal(snap.milestones.length, 2);
+    assert.equal(snap.milestones[0].id, 'M001');
+    assert.equal(snap.milestones[1].id, 'M002');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/lib/git.cjs

@@ -234,6 +234,26 @@ function workspaceGitInfo(cwd) {
   return { is_repo: true, current_branch, remote, branches, commits };
 }
 
+function runGit(args, opts) {
+  const o = opts || {};
+  const spawnOpts = { stdio: o.stdio || ['ignore', 'pipe', 'pipe'] };
+  if (o.cwd) spawnOpts.cwd = o.cwd;
+  try {
+    const stdout = execFileSync('git', args, spawnOpts);
+    return { stdout: stdout ? stdout.toString('utf-8') : '', ok: true };
+  } catch (err) {
+    const stderr = (err && err.stderr) ? err.stderr.toString('utf-8') : '';
+    const stdout = (err && err.stdout) ? err.stdout.toString('utf-8') : '';
+    return {
+      stdout,
+      stderr,
+      status: err && typeof err.status === 'number' ? err.status : null,
+      ok: false,
+      error: err,
+    };
+  }
+}
+
 module.exports = {
   commitTask,
   assertCommittablePaths,
@@ -246,4 +266,5 @@ module.exports = {
   gitShowSafe,
   gitDiffNoColor,
   workspaceGitInfo,
+  runGit,
 };