nubos-pilot 0.1.0

package/workflows/secure-phase.md

@@ -0,0 +1,209 @@
+---
+command: np:secure-phase
+description: Threat-mitigation audit on a completed phase. Reads PLAN.md threat_model + implementation, spawns np-security-auditor (opus) to score each threat as MITIGATED/PARTIAL/UNMITIGATED/N/A, writes SECURITY.md sidecar from templates/SECURITY.md skeleton. One atomic docs commit.
+---
+
+# np:secure-phase
+
+Produces `{phase_dir}/{padded}-SECURITY.md` via a single `np-security-auditor`
+(opus) spawn. Runs AFTER `/np:execute-phase` has landed code — the audit
+needs SUMMARY.md and a `<threat_model>` block in PLAN.md.
+
+The workflow `cp`s `templates/SECURITY.md` into the sidecar BEFORE
+spawning the agent; the auditor substitutes placeholders (`{N}`,
+`{phase-slug}`, `{date}`) and appends per-threat scoring. The Task
+spawn is wrapped in the Plan 09-05 metrics + resolve-model pattern
+(D-06, D-01); `RUNTIME` is detected once and re-used by `metrics
+record`. Prompts route through `np-tools.cjs askuser` (INST-03).
+
+Pre-Phase-9 phases without `<threat_model>` degrade gracefully: the
+auditor produces a best-effort audit inferred from ADRs + code patterns
+(T-10-04-04 accept).
+
+## Initialize
+
+```bash
+PHASE="$1"
+if [[ -z "$PHASE" ]]; then
+  echo "Usage: /np:secure-phase <phase-number>" >&2
+  exit 2
+fi
+
+INIT=$(node np-tools.cjs init secure-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: `padded_phase`, `phase_dir`, `phase_found`.
+
+```bash
+PADDED=$(echo "$INIT" | jq -r '.padded_phase // .padded')
+PHASE_DIR=$(echo "$INIT" | jq -r '.phase_dir')
+PHASE_FOUND=$(echo "$INIT" | jq -r '.phase_found')
+SECURITY_PATH="${PHASE_DIR}/${PADDED}-SECURITY.md"
+SUMMARY_PATH="${PHASE_DIR}/${PADDED}-SUMMARY.md"
+PLAN_PATH_GLOB="${PHASE_DIR}/${PADDED}-*-PLAN.md"
+TEMPLATE_PATH="templates/SECURITY.md"
+PLAN_ID="${PADDED}-secure-phase"
+TASK_ID="${PADDED}-secure-phase"
+```
+
+## Pre-Flight Gates
+
+<pre_flight>
+
+### Gate 1 — Phase found + SUMMARY.md present
+
+```bash
+if [[ "$PHASE_FOUND" != "true" ]]; then
+  echo "Error: Phase $PHASE not found in roadmap or on disk." >&2
+  exit 1
+fi
+if [[ ! -f "$SUMMARY_PATH" ]]; then
+  echo "Error: Phase $PHASE has no SUMMARY.md at $SUMMARY_PATH." >&2
+  echo "Run /np:execute-phase $PHASE before auditing." >&2
+  exit 1
+fi
+```
+
+### Gate 2 — SECURITY.md already exists
+
+If a prior audit is present, let the user choose Re-run / View / Skip.
+The `cp` step only runs in the Re-run branch — View or Skip never
+overwrites a user-edited sidecar (T-10-04-01 mitigation).
+
+```bash
+RERUN="false"
+if [[ -f "$SECURITY_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Existing SECURITY.md",
+    "question": "SECURITY.md already exists for Phase '"$PHASE"'. What would you like to do?",
+    "options": [
+      {"label": "Re-run — replace the current audit", "description": "Re-runs np-security-auditor and overwrites the existing file."},
+      {"label": "View — display current audit and exit", "description": "Reads the file and exits without changes."},
+      {"label": "Skip — keep current audit and exit", "description": "Leaves the file untouched."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*)   cat "$SECURITY_PATH"; exit 0 ;;
+    "Skip"*)   exit 0 ;;
+    "Re-run"*) RERUN="true" ;;
+  esac
+fi
+```
+
+### Gate 3 — Template present
+
+```bash
+if [[ ! -f "$TEMPLATE_PATH" ]]; then
+  echo "Error: $TEMPLATE_PATH missing; Plan 10-01-T03 should have ported it." >&2
+  echo "Re-run 'npx nubos-pilot install' or restore templates/SECURITY.md from source." >&2
+  exit 1
+fi
+```
+
+</pre_flight>
+
+## Load Template
+
+Copy `templates/SECURITY.md` into the sidecar ONLY when absent OR user
+chose Re-run. The agent substitutes `{N}` / `{phase-slug}` / `{date}`
+at write time — the workflow never pre-substitutes.
+
+```bash
+if [[ ! -f "$SECURITY_PATH" || "$RERUN" == "true" ]]; then
+  cp "$TEMPLATE_PATH" "$SECURITY_PATH"
+fi
+```
+
+## Extract Threat Model
+
+The `np-security-auditor` agent reads every
+`${PHASE_DIR}/${PADDED}-*-PLAN.md`, extracts the `<threat_model>`
+block, and consolidates into a unified audit. The workflow passes only
+the glob + phase dir — the agent parses via `Read` / `Grep`.
+
+## Spawn np-security-auditor (opus)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-security-auditor --profile balanced)
+# Spawn agent=np-security-auditor model=$MODEL
+#   input: plan_path_glob=$PLAN_PATH_GLOB, summary_path=$SUMMARY_PATH,
+#          security_path=$SECURITY_PATH, template_path=$TEMPLATE_PATH,
+#          phase_dir=$PHASE_DIR, phase=$PHASE, padded=$PADDED
+#   output: $SECURITY_PATH with scored threats (MITIGATED / PARTIAL /
+#           UNMITIGATED / N/A), using templates/SECURITY.md as skeleton.
+Task(
+  subagent_type="np-security-auditor",
+  model="$MODEL",
+  prompt="<files_to_read>${PLAN_PATH_GLOB} ${SUMMARY_PATH} ${TEMPLATE_PATH} CLAUDE.md PROJECT.md</files_to_read><config>plan_path_glob=$PLAN_PATH_GLOB,summary_path=$SUMMARY_PATH,security_path=$SECURITY_PATH,template_path=$TEMPLATE_PATH,phase_dir=$PHASE_DIR,phase=$PHASE,padded=$PADDED</config>"
+)
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-security-auditor --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
+
+```bash
+if [[ ! -f "$SECURITY_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "SECURITY.md missing",
+    "question": "np-security-auditor did not write SECURITY.md. What would you like to do?",
+    "options": [
+      {"label": "Re-run np-security-auditor", "description": "Spawn the auditor once more."},
+      {"label": "Abort",                      "description": "Exit without committing."}
+    ]
+  }')
+  case "$CHOICE" in "Abort") exit 1 ;; esac
+fi
+```
+
+## Commit
+
+```bash
+node np-tools.cjs commit "docs(${PADDED}): add security audit report" --files "$SECURITY_PATH"
+```
+
+One atomic docs commit per ADR-0004. The commit helper routes through
+`lib/git.cjs.assertCommittablePaths` (gitignore-guard) before staging.
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Run `np-security-auditor` exactly once per invocation (single-pass audit).
+- Emit a metrics record AFTER the Task spawn (D-06).
+- Resolve MODEL via `np-tools.cjs resolve-model np-security-auditor --profile balanced` — no hardcoded IDs.
+- Use `np-tools.cjs askuser` for every prompt (INST-03 invariant).
+- `cp templates/SECURITY.md` into the sidecar BEFORE spawning the agent.
+- Only overwrite existing SECURITY.md on Re-run choice (T-10-04-01).
+- Abort early when phase_dir or SUMMARY.md is absent.
+- Treat implementation files as READ-ONLY (D-20 SC-5).
+
+**Don't:**
+- Run this workflow on a phase without SUMMARY.md.
+- Invoke host-specific prompt tools directly — route through `np-tools.cjs askuser`.
+- Overwrite a user-edited SECURITY.md without the Re-run gate (T-10-04-01).
+- Construct phase paths from raw `$1` — consume `padded_phase` / `phase_dir`
+  from `np-tools.cjs init` (SAFE_PHASE_RE enforced upstream, T-10-04-03).
+- Skip the metrics record block (D-06).
+- Inject raw secret values into the agent prompt (T-10-04-02 defence-in-depth).
+- Spawn any additional agent beyond `np-security-auditor`.
+</scope_guardrail>
+
+## Output
+
+- `{phase_dir}/{padded}-SECURITY.md` — threat register with
+  MITIGATED / PARTIAL / UNMITIGATED / N/A scoring, Trust Boundaries,
+  Accepted Risks log, Security Audit Trail. Frontmatter carries
+  `threats_total`, `mitigated`, `partial`, `unmitigated`, `threats_open`.
+- 1 metrics record in `.nubos-pilot/metrics/phase-${PHASE}.jsonl`.
+- One atomic `docs(${PADDED}): add security audit report` git commit.

package/workflows/session-report.md

@@ -0,0 +1,243 @@
+---
+command: np:session-report
+description: Generate session report from metrics since .nubos-pilot/reports/.last-session pointer. Pointer update is file-lock-guarded (Pitfall 8). Output filename is ISO-8601-prefixed (YYYY-MM-DDTHHMM-session-report.md) for deterministic sort and no overwrite (D-17). Uses lib/metrics-aggregate.cjs.aggregateSession (D-18). One atomic docs commit.
+---
+
+# np:session-report
+
+Implements UTIL-07a. Produces a post-session markdown report
+summarising metrics, commits, and progress since the last report.
+Three deliberate design choices:
+
+- **D-16 pointer file** — persists
+  `.nubos-pilot/reports/.last-session` (ISO-8601 timestamp) so each
+  report covers exactly "since last report" regardless of clock time
+  (rather than a rolling 24h window that would double-count overlaps).
+- **D-17 ISO-prefixed filename** — emits
+  `YYYY-MM-DDTHHMM-session-report.md` so reports never overwrite and
+  sort deterministically.
+- **D-18 aggregation helper** — metrics come from
+  `lib/metrics-aggregate.cjs.aggregateSession` (Plan 10-01-T02);
+  workflow does not parse JSONL itself.
+
+Pointer read + aggregation + write are wrapped in
+`lib/core.cjs.withFileLock` (10s timeout per Pitfall 8, T-10-06-02
+mitigation). Two concurrent `/np:session-report` invocations
+serialise on the pointer so neither produces an overlapping report.
+
+Pure-CRUD workflow — no agent spawn, no resolve-model, no metrics
+record. Pitfall 9 / `workflow-missing-metrics` is exempt.
+
+## Initialize
+
+```bash
+SINCE_OVERRIDE=""
+for arg in "$@"; do
+  case "$arg" in
+    --since=*) SINCE_OVERRIDE="${arg#--since=}" ;;
+  esac
+done
+
+STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+REPORTS_DIR="${STATE_DIR}/reports"
+POINTER="${REPORTS_DIR}/.last-session"
+mkdir -p "$REPORTS_DIR"
+
+NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+LOCAL_FILENAME_TS=$(date +"%Y-%m-%dT%H%M")
+REPORT_PATH="${REPORTS_DIR}/${LOCAL_FILENAME_TS}-session-report.md"
+```
+
+The filename format is `YYYY-MM-DDTHHMM-session-report.md` (D-17 —
+4-char HHMM, no seconds, local time) so reports sort
+lexicographically by invocation order.
+
+## Pointer Read + Aggregation
+
+Pointer read and metrics aggregation run inside a single
+`withFileLock` call so a concurrent invocation cannot interleave
+between "read pointer" and "write new pointer" (T-10-06-02 / Pitfall
+8 mitigation). The lock times out at 10 000 ms; callers that wait
+longer hit `lock-timeout` from `lib/core.cjs.NubosPilotError`.
+
+```bash
+REPORT_JSON=$(node -e '
+  const fs = require("node:fs");
+  const { withFileLock } = require("./lib/core.cjs");
+  const { aggregateSession } = require("./lib/metrics-aggregate.cjs");
+  const pointer = process.argv[1];
+  const override = process.argv[2] || "";
+  const done = withFileLock(pointer, async () => {
+    let since = override || "";
+    if (!override && fs.existsSync(pointer)) {
+      since = fs.readFileSync(pointer, "utf-8").trim();
+    }
+    return aggregateSession(since || null, { cwd: process.cwd() });
+  }, { timeoutMs: 10000 });
+  Promise.resolve(done).then((r) => process.stdout.write(JSON.stringify(r)));
+' "$POINTER" "$SINCE_OVERRIDE")
+```
+
+The `aggregateSession` helper returns
+`{since_iso, record_count, by_phase, total_tokens_in, total_tokens_out,
+partial_tokens, total_duration_ms, error_count, phases_touched}`.
+Null token values (non-claude runtimes per Phase 9 D-09) pass through
+and are rendered as `—` in the output table.
+
+## Render Report Body
+
+Use the `Write` tool to create `$REPORT_PATH` with the body below
+(not a bash heredoc per CLAUDE.md). Render values from
+`$REPORT_JSON` using Node to produce the table rows (null-safe with
+`—` for any null token fields, per D-09 / D-15).
+
+```markdown
+# Session Report — <NOW_ISO>
+
+**Since:** <since_iso or "project inception">
+**Records:** <record_count>
+**Phases touched:** <phases_touched joined with comma>
+**Total duration:** <total_duration_ms> ms
+**Errors:** <error_count>
+
+## By Phase
+
+| Phase | Records | Tokens In | Tokens Out | Errors | Retry Sum |
+|-------|---------|-----------|------------|--------|-----------|
+| <phase> | <record_count> | <tokens_in or "—"> | <tokens_out or "—"> | <error_count> | <retry_count_sum> |
+```
+
+To produce the rendered body deterministically, the agent invokes a
+short Node snippet that consumes `$REPORT_JSON` on stdin and emits
+the markdown table rows — then feeds the full text to the `Write`
+tool. The snippet shape:
+
+```bash
+BODY=$(node -e '
+  const j = JSON.parse(process.argv[1]);
+  const fmt = (v) => v === null || v === undefined ? "—" : String(v);
+  const rows = Object.entries(j.by_phase || {}).sort()
+    .map(([k, p]) => `| ${k} | ${p.record_count} | ${fmt(p.total_tokens_in)} | ${fmt(p.total_tokens_out)} | ${p.error_count} | ${p.retry_count_sum} |`)
+    .join("\n");
+  process.stdout.write(rows);
+' "$REPORT_JSON")
+```
+
+## Update Pointer
+
+AFTER the report file is written via `Write`, update the pointer
+inside a second `withFileLock` call so a crash between "write report"
+and "update pointer" leaves the pointer STALE — the next run
+re-covers the missing period (safe-by-default).
+
+```bash
+node -e '
+  const { withFileLock, atomicWriteFileSync } = require("./lib/core.cjs");
+  withFileLock(
+    process.argv[1],
+    () => atomicWriteFileSync(process.argv[1], process.argv[2]),
+    { timeoutMs: 10000 }
+  );
+' "$POINTER" "$NOW_ISO"
+```
+
+Using `atomicWriteFileSync` ensures the pointer update is crash-safe
+(ADR-0004) — a mid-write crash leaves the OLD pointer intact, not a
+truncated file.
+
+## Commit
+
+Both the new report and the updated pointer land in a single atomic
+docs commit per ADR-0004. Route through `node np-tools.cjs commit`
+so `lib/git.cjs.assertCommittablePaths()` validates the paths.
+
+```bash
+node np-tools.cjs commit "docs(10): add session report — ${LOCAL_FILENAME_TS}" \
+  --files "$REPORT_PATH" "$POINTER"
+```
+
+## Report
+
+```
+Session report: $REPORT_PATH
+  Since:   <since_iso from JSON>
+  Records: <record_count>
+  Pointer: $POINTER (updated to $NOW_ISO)
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Wrap pointer reads AND pointer writes in `withFileLock` (10s
+  timeout per Pitfall 8, T-10-06-02 mitigation).
+- Use local time `YYYY-MM-DDTHHMM` for the filename prefix (D-17 —
+  no seconds; deterministic sort; no overwrite).
+- Render `—` for null token fields (Phase 9 D-09 non-claude runtimes).
+- Commit BOTH the report file AND the updated pointer in a single
+  atomic commit (ADR-0004).
+- Delegate all JSONL parsing to `lib/metrics-aggregate.cjs` (D-18
+  schema single-source-of-truth).
+
+**Don't:**
+- Use a 24h rolling window (rejected per D-16 — two invocations in 12
+  hours would double-count the overlap).
+- Overwrite `SESSION_REPORT.md` (rejected per D-17 — previous reports
+  would be lost on every run).
+- Bypass `aggregateSession` for raw JSONL reads — schema guarantees
+  come from the aggregator.
+- Update the pointer BEFORE the report file write succeeds — a crash
+  between the two would skip a session.
+- 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/reports/YYYY-MM-DDTHHMM-session-report.md` — rendered
+  markdown with session summary, per-phase table (null tokens as
+  `—`), and metadata header.
+- `.nubos-pilot/reports/.last-session` — pointer file updated to the
+  current ISO-8601 UTC timestamp (atomic write; file-locked).
+- One atomic git commit
+  `docs(10): add session report — <local-ts>` containing both files
+  (ADR-0004).
+
+## Success Criteria
+
+- [ ] `--since=<ISO>` argv override honoured when present.
+- [ ] Reports directory created via `projectStateDir` +
+      `mkdir -p` (no direct project-state reads).
+- [ ] Pointer read AND pointer write both wrapped in `withFileLock`
+      with `timeoutMs: 10000` (Pitfall 8 / T-10-06-02).
+- [ ] Metrics aggregation via `lib/metrics-aggregate.cjs.aggregateSession`
+      (D-18 — workflow never parses JSONL directly).
+- [ ] Filename format `YYYY-MM-DDTHHMM-session-report.md` (D-17 —
+      no overwrite, deterministic sort).
+- [ ] Null token fields rendered as `—` in the Phase table (D-09 /
+      D-15).
+- [ ] Pointer update happens AFTER report write succeeds (stale
+      pointer on crash is safer than skipped session).
+- [ ] Pointer written via `atomicWriteFileSync` (ADR-0004 crash-safety).
+- [ ] Single atomic commit via `np-tools.cjs commit` containing both
+      report file and pointer.
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations, no DIRECT_READ matches.
+
+## Related Workflows
+
+- **`/np:stats`** — stats snapshot (read-only, no pointer, no commit).
+- **`/np:cleanup`** — archive completed milestones (distinct
+  milestone-level aggregation).
+
+## Design Notes
+
+D-16 pointer file replaces any rolling-window approach with
+deterministic "since last report" semantics. D-17 ISO-prefixed
+filename makes reports append-only and deterministically sortable.
+D-18 delegates metrics aggregation to `lib/metrics-aggregate.cjs`
+(landed Plan 10-01-T02). Pitfall 8 mitigation wraps pointer access
+in `withFileLock`.

package/workflows/skip.md

@@ -0,0 +1,29 @@
+---
+command: np:skip
+description: Mark a task as skipped (lifecycle CRUD). The task is excluded from wave-selection until it is unparked or its status is set back to pending.
+---
+
+# /np:skip
+
+<objective>
+Flip the task's frontmatter `status` field to `skipped`. The wave-selector
+treats `skipped` like `done` for advancement purposes, so the next wave
+can proceed without this task. No commit is made; the task file is rewritten
+in place.
+</objective>
+
+## Execution
+
+```bash
+TASK_ID="$1"
+if [ -z "$TASK_ID" ]; then
+  echo "Usage: /np:skip <task-id>" >&2
+  exit 1
+fi
+node np-tools.cjs skip "$TASK_ID"
+```
+
+## Scope Guardrail
+
+**Do:** flip task status to `skipped` via `lib/tasks.setTaskStatus`.
+**Don't:** revert commits; modify other frontmatter fields.

package/workflows/state.md

@@ -0,0 +1,7 @@
+# np:state
+
+Print a JSON snapshot of the current STATE.md frontmatter.
+
+```bash
+node np-tools.cjs state
+```

package/workflows/stats.md

@@ -0,0 +1,170 @@
+---
+command: np:stats
+description: Stats output — phases-table (name/plans/completed/status/%) + metrics aggregation (tokens-in/out per phase, avg duration by tier, retry_count_sum, error_rate). Consumes node np-tools.cjs stats json. Null-token runtimes render as `—` (Phase 9 D-09). Read-only — no commits, no STATE mutation.
+---
+
+# np:stats
+
+Implements UTIL-07b. Renders an on-demand snapshot combining a
+phases-table (phase / plans total / complete / status / percent)
+with metrics aggregation (tokens-in / tokens-out per phase, avg
+duration by tier, retry_count_sum, error_rate). Read-only surface
+per D-20 SC-5 — no files written, no state mutated, no git commit.
+
+The workflow delegates ALL data collection to
+`bin/np-tools/stats.cjs` (landed Plan 10-01-T04), which emits a
+`schema_version:1` JSON envelope on stdout. This workflow consumes
+that JSON and renders markdown. No JSONL parsing inline.
+
+Pure read-only workflow — no agent spawn, no resolve-model, no
+metrics record. Pitfall 9 / `workflow-missing-metrics` is exempt.
+
+## Initialize
+
+```bash
+STATS_JSON=$(node np-tools.cjs stats json)
+if [[ -z "$STATS_JSON" ]]; then
+  echo "No stats available (empty project?)" >&2
+  exit 0
+fi
+```
+
+The stats CLI produces the full payload — `{schema_version, milestone,
+phases, plans_total, plans_complete, percent, git, last_activity,
+metrics_by_phase}`. An empty project yields an empty JSON; the
+workflow short-circuits gracefully rather than producing an empty
+table.
+
+## Render
+
+Render the JSON as markdown via a `node -e` one-liner. Null token
+cells render as `—` (Phase 9 D-09) so non-claude runtimes don't show
+misleading zeros. Progress bar is a 20-char block-string
+`[████░░░░░░…]` (ADR-0002 — no cli-progress dep).
+
+Progress bar helper:
+
+```javascript
+const filled = Math.round(percent / 5);
+const bar = "█".repeat(filled) + "░".repeat(20 - filled);
+```
+
+Null-safe token rendering:
+
+```javascript
+const fmt = (v) => v === null || v === undefined ? "—" : v.toLocaleString();
+```
+
+Rendered output sections: Project Stats header (milestone / progress
+bar / last activity / commits / start date), Phases table (phase /
+name / plans / complete / status / percent), Metrics by Phase table
+(records / tokens / tier-avg durations / errors). Example row for a
+phase with no metrics: `| 10 | — | — | — | — | — | — | — |`.
+
+The full render is a single `node -e` call consuming `$STATS_JSON`:
+
+```bash
+node -e '
+  const j = JSON.parse(process.argv[1]);
+  const fmt = (v) => v === null || v === undefined ? "—" : (typeof v === "number" ? v.toLocaleString() : String(v));
+  const filled = Math.round((j.percent || 0) / 5);
+  const bar = "█".repeat(filled) + "░".repeat(20 - filled);
+  const lines = [];
+  lines.push("## Project Stats");
+  lines.push("");
+  lines.push(`**Milestone:** ${fmt(j.milestone && j.milestone.version)} — ${fmt(j.milestone && j.milestone.name)}`);
+  lines.push(`**Progress:** [${bar}] ${j.percent || 0}% (${j.plans_complete}/${j.plans_total} plans)`);
+  lines.push(`**Last activity:** ${fmt(j.last_activity)}`);
+  lines.push(`**Commits:** ${fmt(j.git && j.git.commits)}`);
+  lines.push(`**Project started:** ${fmt(j.git && j.git.first_commit_at)}`);
+  lines.push("");
+  lines.push("### Phases");
+  lines.push("");
+  lines.push("| Phase | Name | Plans | Completed | Status | % |");
+  lines.push("|-------|------|-------|-----------|--------|---|");
+  for (const ph of (j.phases || [])) {
+    const pct = ph.plans_total > 0 ? Math.round(ph.plans_complete / ph.plans_total * 100) : 0;
+    lines.push(`| ${ph.number} | ${ph.name} | ${ph.plans_total} | ${ph.plans_complete} | ${ph.status} | ${pct}% |`);
+  }
+  lines.push("");
+  lines.push("### Metrics by Phase");
+  lines.push("");
+  lines.push("| Phase | Records | Tokens In | Tokens Out | Avg Opus ms | Avg Sonnet ms | Avg Haiku ms | Errors |");
+  lines.push("|-------|---------|-----------|------------|-------------|---------------|--------------|--------|");
+  for (const ph of (j.phases || [])) {
+    const m = (j.metrics_by_phase || {})[ph.number];
+    if (!m || m.record_count === 0) {
+      lines.push(`| ${ph.number} | — | — | — | — | — | — | — |`);
+      continue;
+    }
+    const t = m.avg_duration_ms_by_tier || {};
+    lines.push(`| ${ph.number} | ${m.record_count} | ${fmt(m.total_tokens_in)} | ${fmt(m.total_tokens_out)} | ${fmt(t.opus)} | ${fmt(t.sonnet)} | ${fmt(t.haiku)} | ${m.error_count} |`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+' "$STATS_JSON"
+```
+
+## No Commit
+
+Stats is read-only (D-20 SC-5). No files are written, no state is
+mutated, no git commit is made. The markdown goes directly to stdout
+and is rendered by the agent CLI.
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Consume `node np-tools.cjs stats json` — trust its
+  `schema_version: 1` output shape (Plan 10-01-T04 contract).
+- Render `tokens_in` / `tokens_out` as `—` when null (Phase 9 D-09
+  non-claude runtimes; D-15 hybrid-output decision).
+- Render the progress bar as a 20-char `[████░░…]` string (ADR-0002
+  — no cli-progress dep).
+- Keep the workflow read-only — no files written, no STATE mutated,
+  no git commit (D-20 SC-5).
+
+**Don't:**
+- Re-implement JSONL aggregation inline — `lib/metrics-aggregate.cjs`
+  owns the schema (D-18).
+- Write any files — this workflow is a render, not a producer.
+- Add a git commit — there is nothing to commit.
+- 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 '…'` if prompts are ever added.
+- Add a `metrics record` block. No Task/Spawn site; Pitfall 9 /
+  `workflow-missing-metrics` is exempt.
+</scope_guardrail>
+
+## Output
+
+- Markdown snapshot on stdout with Project Stats header, Phases
+  table, and Metrics by Phase table.
+- No files created. No state mutated. No git commit.
+
+## Success Criteria
+
+- [ ] Data sourced exclusively from `node np-tools.cjs stats json`
+      (Plan 10-01-T04) — no inline JSONL parsing.
+- [ ] Null `tokens_in` / `tokens_out` render as `—` (D-09 / D-15).
+- [ ] Progress bar is a 20-char block-string (ADR-0002).
+- [ ] Phases table contains phase / name / plans_total / completed
+      / status / percent.
+- [ ] Metrics-by-phase table shows records / tokens / tier-avg
+      durations / errors per phase.
+- [ ] Zero file writes, zero state mutations, zero commits (D-20
+      SC-5).
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations, no DIRECT_READ matches.
+
+## Related Workflows
+
+- **`/np:progress`** — base-workflow percent snapshot (subset).
+- **`/np:session-report`** — commits a rendered report with
+  since-last-session metrics (the producer pair for `/np:stats`).
+
+## Design Notes
+
+Phases-table + metrics aggregation combined per D-15. Stats CLI
+(`bin/np-tools/stats.cjs`) is the single data source (D-20 SC-5).
+Null-token semantics from Phase 9 D-09. Progress bar uses block
+characters (ADR-0002) instead of a cli-progress dep.