nubos-pilot 0.1.0

package/workflows/thread.md

@@ -0,0 +1,214 @@
+---
+command: np:thread
+description: Create or resume a cross-session thread at .nubos-pilot/threads/<slug>.md. Lifecycle status OPEN → IN_PROGRESS (auto on resume) → RESOLVED (user edits manually, no close command per D-19 Claude's Discretion). No agent spawn. Project-scope only.
+---
+
+# np:thread
+
+Implements UTIL-06. Threads are lightweight cross-session context
+stores for work spanning multiple sessions but not belonging to a
+specific phase. They live under `.nubos-pilot/threads/<slug>.md` with
+lifecycle `OPEN → IN_PROGRESS → RESOLVED` in their frontmatter.
+
+Two modes, selected by presence of the target file:
+
+- **create** — writes a fresh file with `status: OPEN`; one atomic
+  docs commit (ADR-0004).
+- **resume** — reads the file, bumps `status: OPEN → IN_PROGRESS`
+  (never downgraded), updates `last_resumed`, displays content.
+  Resume does **not** commit — `last_resumed` churn is too noisy.
+
+No close command (D-19). User manually sets `status: RESOLVED`.
+Pure-CRUD — no agent spawn, no metrics record (Pitfall 9 exempt).
+
+## Initialize
+
+```bash
+SLUG_ARG="$*"
+if [[ -z "$SLUG_ARG" ]]; then
+  echo "Usage: /np:thread <slug-or-title>" >&2
+  exit 2
+fi
+SLUG=$(node np-tools.cjs generate-slug "$SLUG_ARG" --raw)
+if [[ -z "$SLUG" ]]; then
+  echo "Error: argument produced no slug-safe characters." >&2
+  exit 1
+fi
+STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+THREADS_DIR="${STATE_DIR}/threads"
+THREAD_PATH="${THREADS_DIR}/${SLUG}.md"
+TODAY=$(date +%Y-%m-%d)
+mkdir -p "$THREADS_DIR"
+```
+
+Slug via `generate-slug` (wraps `lib/phase.cjs.phaseSlug`) — only
+`[a-z0-9-]` enters the filename; closes T-10-06-01 (path traversal).
+
+## Create vs Resume Branch
+
+```bash
+if [[ -f "$THREAD_PATH" ]]; then
+  MODE="resume"
+else
+  MODE="create"
+fi
+```
+
+## Create Branch (MODE = create)
+
+Use the `Write` tool to create `$THREAD_PATH` with the frontmatter +
+body template below (not a bash heredoc). `${SLUG}` / `${SLUG_ARG}` /
+`${TODAY}` are substituted from the variables above.
+
+```markdown
+---
+slug: <SLUG>
+status: OPEN
+created: <TODAY>
+last_resumed: <TODAY>
+---
+
+# Thread: <SLUG_ARG>
+
+## Status: OPEN
+
+## Goal
+
+<TBD — user fills in>
+
+## Context
+
+*Created from conversation on <TODAY>.*
+
+## References
+
+- *(add links, file paths, or issue numbers)*
+
+## Next Steps
+
+- *(what the next session should do first)*
+```
+
+Route the commit through `node np-tools.cjs commit` so
+`lib/git.cjs.assertCommittablePaths()` validates the path before
+`git add` (path-traversal guard from Plan 10-01-T04).
+
+```bash
+if [[ "$MODE" == "create" ]]; then
+  node np-tools.cjs commit "docs(10): create thread — ${SLUG}" --files "$THREAD_PATH"
+  echo "Thread created: $THREAD_PATH"
+  echo ""
+  echo "Resume anytime with: /np:thread ${SLUG}"
+fi
+```
+
+## Resume Branch (MODE = resume)
+
+Two in-place updates via `lib/core.cjs.atomicWriteFileSync`
+(ADR-0004 crash-safety):
+
+1. If current `status === "OPEN"`, bump to `IN_PROGRESS`. Status is
+   **never downgraded**: `IN_PROGRESS` / `RESOLVED` remain as-is.
+2. `last_resumed: <TODAY>` — always refreshed.
+
+Frontmatter parsed via `lib/frontmatter.cjs.extractFrontmatter` (read)
+and re-serialised via a hand-rolled minimal FM writer (the lib ships
+a reader only) that emits one `key: value` per field in insertion
+order.
+
+```bash
+if [[ "$MODE" == "resume" ]]; then
+  node -e "
+    const fs = require('node:fs');
+    const { extractFrontmatter } = require('./lib/frontmatter.cjs');
+    const { atomicWriteFileSync } = require('./lib/core.cjs');
+    const p = process.argv[1];
+    const today = process.argv[2];
+    const raw = fs.readFileSync(p, 'utf-8');
+    const { frontmatter, body } = extractFrontmatter(raw);
+    const next = Object.assign({}, frontmatter);
+    const cur = String(next.status || 'OPEN');
+    if (cur === 'OPEN') next.status = 'IN_PROGRESS';
+    next.last_resumed = today;
+    const order = ['slug', 'status', 'created', 'last_resumed'];
+    const seen = new Set();
+    const lines = ['---'];
+    for (const k of order) {
+      if (k in next) { lines.push(k + ': ' + next[k]); seen.add(k); }
+    }
+    for (const k of Object.keys(next)) {
+      if (!seen.has(k)) lines.push(k + ': ' + next[k]);
+    }
+    lines.push('---');
+    const out = lines.join('\n') + '\n' + body;
+    atomicWriteFileSync(p, out);
+  " "$THREAD_PATH" "$TODAY"
+  echo "Thread resumed: $THREAD_PATH"
+  echo ""
+  echo "--- thread content ---"
+  node -e "process.stdout.write(require('node:fs').readFileSync(process.argv[1], 'utf-8'))" "$THREAD_PATH"
+fi
+```
+
+Resume never commits. `last_resumed` churn would flood the log.
+
+## Report
+
+Echo `Thread <MODE>d: <THREAD_PATH>` with slug/mode/today to stdout.
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Use `phaseSlug`-generated slug (T-10-06-01 mitigation).
+- Preserve status monotonicity on resume: `OPEN → IN_PROGRESS` only.
+- Let the user manually flip `status: RESOLVED` (D-19 — no close
+  command in this adapted port).
+- Use `lib/core.cjs.atomicWriteFileSync` for any in-place rewrite
+  (ADR-0004 crash-safety).
+- Route the create-branch commit through `node np-tools.cjs commit`.
+
+**Don't:**
+- Commit `last_resumed`-only updates. Resume is commit-free.
+- 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 '…'`.
+- Bypass `atomicWriteFileSync` — rename pair is the invariant.
+- Add a `metrics record` block. No Task/Spawn site here; Pitfall 9 /
+  `workflow-missing-metrics` is exempt.
+</scope_guardrail>
+
+## Output
+
+- `.nubos-pilot/threads/<slug>.md` — thread file. Create mode writes
+  a new file with four-field frontmatter (`slug / status:OPEN /
+  created / last_resumed`) and four-section body. Resume mode
+  updates in-place: `status: IN_PROGRESS` (if OPEN) + refreshed
+  `last_resumed`.
+- **Create mode only:** one atomic commit
+  `docs(10): create thread — <slug>` (ADR-0004).
+- **Resume mode:** no commit.
+
+## Success Criteria
+
+- [ ] Slug via `generate-slug` (T-10-06-01 mitigation).
+- [ ] Threads dir via `lib/core.cjs.projectStateDir`.
+- [ ] Mode selected by `[[ -f $THREAD_PATH ]]`.
+- [ ] Create: `Write` tool + `np-tools.cjs commit` atomic unit.
+- [ ] Resume: `extractFrontmatter` round-trip;
+      `OPEN → IN_PROGRESS` only; `last_resumed` refreshed.
+- [ ] Resume writes via `atomicWriteFileSync`; no commit.
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations, no DIRECT_READ matches.
+
+## Related Workflows
+
+- **`/np:add-todo <title>`** — smaller-scope pending todo capture.
+- **`/np:note [--global] <text>`** — zero-friction free-form capture.
+- **`/np:add-backlog <title>`** — promote a thread to a backlog entry.
+
+## Design Notes
+
+No list-all mode (no-arg invocation errors). Threads live under
+`.nubos-pilot/threads/` per D-14. Lifecycle frontmatter is the
+machine-readable source-of-truth (no free-text heading parsing).

package/workflows/triage.md

@@ -0,0 +1,9 @@
+# np:triage
+
+Interactive reviewer that walks the unified queue (see `np:queue`) item-by-item.
+For each item, prompts `promote-to-todo | promote-to-phase | keep | drop`.
+Non-TTY runs default to `keep` — safe in CI.
+
+```bash
+node np-tools.cjs triage "$@"
+```

package/workflows/ui-phase.md

@@ -0,0 +1,246 @@
+---
+command: np:ui-phase
+description: Generate UI-SPEC.md for frontend phases via 2-agent revision loop (np-ui-researcher → np-ui-checker) with max 2 iterations and a PASS/FLAG/BLOCK verdict gate.
+---
+
+# np:ui-phase
+
+Produces `{phase_dir}/{padded}-UI-SPEC.md` via a researcher → checker
+revision loop (max 2 iterations). Inserts between `/np:discuss-phase` and
+`/np:plan-phase` for UI-heavy phases. Locks the six visual pillars
+(spacing, typography, color, copywriting, design-system, components)
+BEFORE the planner creates tasks so execution stays on-brand.
+
+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:ui-phase <phase-number>" >&2
+  exit 2
+fi
+
+INIT=$(node np-tools.cjs init ui-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`, `ui_spec_path`,
+`has_ui_spec`, `template_path`, `max_iterations`,
+`agents.ui_researcher`, `agents.ui_checker`.
+
+```bash
+PADDED=$(echo "$INIT" | jq -r '.padded')
+PHASE_DIR=$(echo "$INIT" | jq -r '.phase_dir')
+UI_SPEC_PATH=$(echo "$INIT" | jq -r '.ui_spec_path')
+HAS_UI_SPEC=$(echo "$INIT" | jq -r '.has_ui_spec')
+TEMPLATE_PATH=$(echo "$INIT" | jq -r '.template_path')
+MAX_ITER=$(echo "$INIT" | jq -r '.max_iterations')
+PLAN_ID="${PADDED}-ui"
+TASK_ID="${PADDED}-ui"
+```
+
+## Pre-Flight Gates
+
+<pre_flight>
+
+### Gate 1 — UI-SPEC.md already exists
+
+If `has_ui_spec == true`:
+
+```bash
+if [[ "$HAS_UI_SPEC" == "true" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Existing UI-SPEC",
+    "question": "UI-SPEC.md already exists for Phase '"$PHASE"'. What would you like to do?",
+    "options": [
+      {"label": "Update — re-run researcher with existing as baseline", "description": "Re-runs the researcher→checker loop against the current spec."},
+      {"label": "View — display current UI-SPEC and exit",             "description": "Reads the file and exits without changes."},
+      {"label": "Skip — keep current UI-SPEC and exit",                "description": "Leaves the file untouched."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*) cat "$UI_SPEC_PATH"; exit 0 ;;
+    "Skip"*) exit 0 ;;
+  esac
+fi
+```
+
+</pre_flight>
+
+## Philosophy
+
+<philosophy>
+UI-SPEC.md locks the six pillars most often under-specified in frontend
+work: spacing scale (non-multiple-of-4 breaks grids), typography
+(too many sizes or weights create visual noise), color (accent reserved
+for "all interactive elements" defeats the 60/30/10 split), copywriting
+(generic CTAs like "Submit" / "OK" ship as design debt), design-system
+inventory (pull-once, re-use everywhere), and per-component contracts
+(prop shape + a11y + state machine). Running this loop BEFORE
+`/np:plan-phase` surfaces these decisions as an explicit artifact the
+planner, executor, and ui-auditor can enforce.
+</philosophy>
+
+## Main Flow
+
+The researcher and checker alternate for up to `$MAX_ITER` iterations.
+Each iteration wraps both spawns in the Plan-09-05 metrics pattern.
+The checker emits a structured JSON verdict with `overall_status` set
+to `APPROVED` or `BLOCKED`; `BLOCKED` re-invokes the researcher with
+the checker's issue list as feedback.
+
+### Step 0 — Initialize UI-SPEC.md from template
+
+```bash
+if [[ "$HAS_UI_SPEC" != "true" ]]; then
+  cp "$TEMPLATE_PATH" "$UI_SPEC_PATH"
+fi
+ITER=0
+VERDICT_PATH="${PHASE_DIR}/${PADDED}-ui-checker-verdict.json"
+```
+
+### Revision Loop
+
+> NOTE: Serial per iteration. The researcher writes UI-SPEC.md; the
+> checker reads it and emits a verdict. On `BLOCKED`, loop with the
+> verdict as feedback. On `APPROVED` or `$ITER >= $MAX_ITER`, exit.
+
+```bash
+while [[ "$ITER" -lt "$MAX_ITER" ]]; do
+  ITER=$((ITER + 1))
+  ITER_TASK_ID="${TASK_ID}-iter-${ITER}"
+```
+
+#### Step 1 — UI researcher (np-ui-researcher, sonnet)
+
+```bash
+  START=$(node np-tools.cjs metrics start-timestamp)
+  MODEL=$(node np-tools.cjs resolve-model np-ui-researcher --profile balanced)
+  > NOTE: Spawn agent=np-ui-researcher model=$MODEL
+  > NOTE:   input: phase_number=$PHASE, ui_spec_path=$UI_SPEC_PATH, iteration=$ITER
+  > NOTE:   on iter >= 2, also pass prior_verdict=$VERDICT_PATH as revision feedback
+  > NOTE:   output: fully-populated UI-SPEC.md at $UI_SPEC_PATH
+  END=$(node np-tools.cjs metrics end-timestamp)
+  node np-tools.cjs metrics record \
+    --agent np-ui-researcher --tier sonnet --resolved-model "$MODEL" \
+    --phase "$PHASE" --plan "$PLAN_ID" --task "$ITER_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 — UI checker (np-ui-checker, haiku)
+
+```bash
+  START=$(node np-tools.cjs metrics start-timestamp)
+  MODEL=$(node np-tools.cjs resolve-model np-ui-checker --profile balanced)
+  > NOTE: Spawn agent=np-ui-checker model=$MODEL
+  > NOTE:   input: ui_spec_path=$UI_SPEC_PATH
+  > NOTE:   output: structured JSON verdict written to $VERDICT_PATH
+  END=$(node np-tools.cjs metrics end-timestamp)
+  node np-tools.cjs metrics record \
+    --agent np-ui-checker --tier haiku --resolved-model "$MODEL" \
+    --phase "$PHASE" --plan "$PLAN_ID" --task "$ITER_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 — Evaluate verdict
+
+```bash
+  OVERALL=$(jq -r '.overall_status' "$VERDICT_PATH" 2>/dev/null || echo "BLOCKED")
+  VERDICT=$(jq -r '.verdict' "$VERDICT_PATH" 2>/dev/null || echo "BLOCK")
+  if [[ "$OVERALL" == "APPROVED" ]]; then
+    break
+  fi
+done
+```
+
+## Validation Gate
+
+After the loop, inspect the final verdict. If still `BLOCKED` after
+`$MAX_ITER` iterations, ask the user to accept with warnings, revise
+manually, or abort. If `APPROVED`, update UI-SPEC.md frontmatter to
+`status: approved` with a review timestamp.
+
+```bash
+OVERALL=$(jq -r '.overall_status' "$VERDICT_PATH" 2>/dev/null || echo "BLOCKED")
+
+if [[ "$OVERALL" == "BLOCKED" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "UI-SPEC still BLOCKED after max iterations",
+    "question": "The checker still returns BLOCKED. What would you like to do?",
+    "options": [
+      {"label": "Accept with warnings", "description": "Proceed; unresolved issues are noted in the commit message."},
+      {"label": "Revise manually",      "description": "Exit so you can edit UI-SPEC.md by hand."},
+      {"label": "Abort",                "description": "Exit without committing."}
+    ]
+  }')
+  case "$CHOICE" in
+    "Abort")           exit 1 ;;
+    "Revise manually") exit 0 ;;
+  esac
+else
+  REVIEWED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  node np-tools.cjs frontmatter-set "$UI_SPEC_PATH" status approved
+  node np-tools.cjs frontmatter-set "$UI_SPEC_PATH" reviewed_at "$REVIEWED_AT"
+fi
+```
+
+> NOTE: `frontmatter-set` is the standard nubos-pilot frontmatter editor;
+> if unavailable, use an equivalent in-place sed/Write pattern per the
+> adapted-port invariant (no direct host-tool edits).
+
+## Commit
+
+```bash
+git add "$UI_SPEC_PATH"
+git commit -m "docs(${PADDED}): generate UI-SPEC.md via 2-agent revision loop"
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Run researcher and checker serially per iteration (max 2 iterations).
+- 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 UI-SPEC.md when the checker returns APPROVED or the
+  user accepts with warnings.
+
+**Don't:**
+- Invoke the host-specific prompt tool directly — always route through
+  `np-tools.cjs askuser`.
+- Parallelize researcher + checker — the checker reads what the
+  researcher just wrote.
+- Exceed `$MAX_ITER` iterations — the revision loop is bounded to
+  prevent runaway costs on stubborn BLOCKs.
+- 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.
+- Modify UI-SPEC.md from the checker agent — the checker is read-only
+  and the researcher owns writes.
+- Skip any metrics record block — the Phase-10 np:stats consumer
+  expects one record per Task spawn.
+</scope_guardrail>
+
+## Output
+
+- `{phase_dir}/{padded}-UI-SPEC.md` — filled-in UI design contract with
+  `status: approved` frontmatter when the checker passes.
+- `{phase_dir}/{padded}-ui-checker-verdict.json` — last checker verdict
+  (JSON); retained for the planner and ui-auditor to consume.
+- Up to 2 × 2 = 4 metrics records in
+  `.nubos-pilot/metrics/phase-${PHASE}.jsonl` (one per Task spawn per
+  iteration).
+- One git commit (when APPROVED or user accepts with warnings).

package/workflows/ui-review.md

@@ -0,0 +1,222 @@
+---
+command: np:ui-review
+description: Retroactive 6-pillar visual audit of a completed phase. Spawns np-ui-auditor to score copywriting, visuals, color, typography, spacing, and experience design against UI-SPEC.md (if present) or abstract best-practice standards. Produces UI-REVIEW.md.
+---
+
+# np:ui-review
+
+Produces `{phase_dir}/{padded}-UI-REVIEW.md` via a single `np-ui-auditor` spawn
+that audits the phase's implemented frontend code. Runs AFTER
+`/np:execute-phase` has landed code — the audit needs a SUMMARY.md to
+know what was built.
+
+Two modes:
+
+- **Spec-conformance audit** — when `{padded}-UI-SPEC.md` exists (phase
+  went through `/np:ui-phase`). Pillars are scored against the declared
+  contract.
+- **Retroactive general audit** — when no UI-SPEC is present. Pillars
+  are scored against abstract 6-pillar best-practice standards. The
+  output file header labels the mode explicitly (Pitfall 10 — avoids
+  silent drift between spec-backed and spec-less reviews).
+
+The single 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 the `metrics record` call.
+
+## Initialize
+
+```bash
+PHASE="$1"
+if [[ -z "$PHASE" ]]; then
+  echo "Usage: /np:ui-review <phase-number>" >&2
+  exit 2
+fi
+
+INIT=$(node np-tools.cjs init ui-review "$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`, `ui_review_path`,
+`summary_present`, `summary_path`, `ui_spec_path`, `has_ui_spec`,
+`agents.ui_auditor`.
+
+```bash
+PADDED=$(echo "$INIT" | jq -r '.padded')
+PHASE_DIR=$(echo "$INIT" | jq -r '.phase_dir')
+UI_REVIEW_PATH=$(echo "$INIT" | jq -r '.ui_review_path')
+SUMMARY_PRESENT=$(echo "$INIT" | jq -r '.summary_present')
+SUMMARY_PATH=$(echo "$INIT" | jq -r '.summary_path')
+UI_SPEC_PATH=$(echo "$INIT" | jq -r '.ui_spec_path')
+HAS_UI_SPEC=$(echo "$INIT" | jq -r '.has_ui_spec')
+PLAN_ID="${PADDED}-ui-review"
+TASK_ID="${PADDED}-ui-review"
+```
+
+## Pre-Flight Gates
+
+<pre_flight>
+
+### Gate 1 — SUMMARY.md must exist
+
+A retroactive audit requires a completed phase. If no SUMMARY.md is
+present, the phase hasn't been executed yet and there is nothing to
+audit.
+
+```bash
+if [[ "$SUMMARY_PRESENT" != "true" ]]; then
+  echo "Error: Phase $PHASE has no SUMMARY.md at $SUMMARY_PATH." >&2
+  echo "The phase must be executed (/np:execute-phase) before it can be audited." >&2
+  exit 1
+fi
+```
+
+### Gate 2 — UI-REVIEW.md already exists
+
+If a prior review is present, let the user choose between re-running,
+viewing the current review, or skipping.
+
+```bash
+if [[ -f "$UI_REVIEW_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Existing UI-REVIEW",
+    "question": "UI-REVIEW.md already exists for Phase '"$PHASE"'. What would you like to do?",
+    "options": [
+      {"label": "Re-run — replace the current review", "description": "Re-runs np-ui-auditor and overwrites the existing file."},
+      {"label": "View — display current review and exit", "description": "Reads the file and exits without changes."},
+      {"label": "Skip — keep current review and exit", "description": "Leaves the file untouched."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*) cat "$UI_REVIEW_PATH"; exit 0 ;;
+    "Skip"*) exit 0 ;;
+  esac
+fi
+```
+
+### Gate 3 — Determine audit mode
+
+```bash
+if [[ "$HAS_UI_SPEC" == "true" ]]; then
+  AUDIT_MODE="spec-conformance"
+else
+  AUDIT_MODE="retroactive-general"
+fi
+```
+
+</pre_flight>
+
+## Philosophy
+
+<philosophy>
+UI drift is invisible until you measure it. Copy regresses to "Submit"
+and "OK", accent colors multiply past the 60/30/10 split, spacing
+scales fragment into pixel-perfect one-offs, and empty/error/loading
+states go missing. A retroactive 6-pillar audit catches all of that in
+one pass and produces a ranked list of fixes. When a UI-SPEC.md exists,
+the audit is a conformance check. When it doesn't, the audit is a
+best-practice sweep — and the mode label on UI-REVIEW.md makes that
+difference explicit so reviewers don't treat a general audit as if it
+had SPEC backing.
+</philosophy>
+
+## Main Flow
+
+Single serial spawn — the auditor is self-contained (screenshots,
+pillar scoring, registry safety, report writing all happen inside
+`np-ui-auditor`).
+
+### Step 1 — UI auditor (np-ui-auditor, haiku)
+
+```bash
+START=$(node np-tools.cjs metrics start-timestamp)
+MODEL=$(node np-tools.cjs resolve-model np-ui-auditor --profile balanced)
+> NOTE: Spawn agent=np-ui-auditor model=$MODEL
+> NOTE:   input: phase_number=$PHASE, phase_dir=$PHASE_DIR,
+> NOTE:          summary_path=$SUMMARY_PATH, ui_spec_path=$UI_SPEC_PATH,
+> NOTE:          has_ui_spec=$HAS_UI_SPEC, audit_mode=$AUDIT_MODE,
+> NOTE:          ui_review_path=$UI_REVIEW_PATH
+> NOTE:   output: $UI_REVIEW_PATH with pillar scores, top-3 fixes,
+> NOTE:           and a mode label ("spec-conformance" or
+> NOTE:           "retroactive-general") in the header frontmatter.
+END=$(node np-tools.cjs metrics end-timestamp)
+node np-tools.cjs metrics record \
+  --agent np-ui-auditor --tier haiku --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 the auditor finishes, verify UI-REVIEW.md was written and carries
+the expected mode label. If the file is missing, the spawn failed
+silently and the user is prompted to re-run or abort.
+
+```bash
+if [[ ! -f "$UI_REVIEW_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "UI-REVIEW.md missing",
+    "question": "np-ui-auditor did not write UI-REVIEW.md. What would you like to do?",
+    "options": [
+      {"label": "Re-run np-ui-auditor", "description": "Spawn the auditor once more."},
+      {"label": "Abort",                "description": "Exit without committing."}
+    ]
+  }')
+  case "$CHOICE" in
+    "Abort") exit 1 ;;
+  esac
+fi
+```
+
+## Commit
+
+```bash
+git add "$UI_REVIEW_PATH"
+git commit -m "docs(${PADDED}): generate UI-REVIEW.md (${AUDIT_MODE})"
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Run `np-ui-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` — no hardcoded IDs.
+- Use `np-tools.cjs askuser` for every prompt (INST-03 invariant).
+- Label the audit mode explicitly in UI-REVIEW.md
+  (`spec-conformance` when UI-SPEC.md exists, `retroactive-general`
+  otherwise) — Pitfall 10 enforcement.
+- Abort early when SUMMARY.md is missing; retroactive audits are only
+  meaningful against executed phases.
+
+**Don't:**
+- Run this workflow on a phase that has not been executed — there is
+  nothing to audit until SUMMARY.md lands.
+- Invoke host-specific prompt tools directly — always route through
+  `np-tools.cjs askuser`.
+- Silently treat a spec-less audit as if it had SPEC backing — the
+  mode label in the output header is mandatory.
+- Spawn any additional agent beyond `np-ui-auditor`; if a follow-up
+  remediation pass is needed, that is the planner's job, not this
+  workflow's.
+- 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 the metrics record block — the Phase-10 np:stats consumer
+  expects one record per Task spawn.
+</scope_guardrail>
+
+## Output
+
+- `{phase_dir}/{padded}-UI-REVIEW.md` — pillar scores, top-3 priority
+  fixes, detailed findings, and mode label
+  (`spec-conformance` or `retroactive-general`).
+- 1 metrics record in `.nubos-pilot/metrics/phase-${PHASE}.jsonl`
+  for the single `np-ui-auditor` Task spawn.
+- One git commit when UI-REVIEW.md is produced successfully.