nubos-pilot 0.1.0

package/workflows/add-backlog.md

@@ -0,0 +1,212 @@
+---
+command: np:add-backlog
+description: Add a 999.x backlog item to ROADMAP.md. Uses lib/roadmap.cjs.addBacklogEntry (file-locked) to append to the synthetic "backlog" milestone. Creates .nubos-pilot/phases/999.X-<slug>/.gitkeep. One atomic docs commit.
+---
+
+# np:add-backlog
+
+Implements UTIL-05c. Mints a new entry in the synthetic `backlog`
+milestone (id: `backlog`) using 999.x numbering. Unlike normal phases,
+backlog items live outside the active milestone sequence — they are
+the parking lot for "not-ready-to-plan" ideas that still deserve a
+home in the roadmap.
+
+The authoritative numbering and ROADMAP/roadmap.yaml update are
+performed inside `lib/roadmap.cjs.addBacklogEntry` (landed in
+Plan 10-01-T05). That helper is file-locked via `_mutate()` so two
+parallel invocations serialise on the same 999.x counter (T-10-05-04
+is accepted because the lock resolves the race inside the mutator).
+The preview number shown to the user is computed OUTSIDE the lock and
+is advisory only — the authoritative number comes back in the
+helper's return value.
+
+This is a pure-CRUD workflow — no agent spawn, no resolve-model, no
+metrics record. The `workflow-missing-metrics` lint in
+`bin/check-workflows.cjs` only fires on `Task(` / `Spawn agent=` sites,
+so CRUD-only workflows are exempt (Pitfall 9 resolution from
+Plan 10-05). Interactive prompts route through
+`node np-tools.cjs askuser --json` per INST-03.
+
+## Initialize
+
+```bash
+TITLE="$*"
+if [[ -z "$TITLE" ]]; then
+  echo "Usage: /np:add-backlog <title>" >&2
+  exit 2
+fi
+```
+
+## Compute Preview
+
+Info-only preview — the preview number is NOT used as the commit
+subject. The authoritative 999.X is assigned inside the lock and
+returned in `RESULT` below.
+
+```bash
+NEXT_NUMBER=$(node np-tools.cjs phase next-decimal 999 --raw)
+SLUG=$(node np-tools.cjs generate-slug "$TITLE" --raw)
+if [[ -z "$SLUG" ]]; then
+  echo "Error: title produced no slug-safe characters." >&2
+  exit 1
+fi
+echo "Will add backlog item: ${NEXT_NUMBER} — ${TITLE}"
+```
+
+## Confirm
+
+```bash
+CHOICE=$(node np-tools.cjs askuser --json '{
+  "type": "select",
+  "header": "Backlog Item Preview",
+  "question": "Add backlog item '"${NEXT_NUMBER}"' — '"${TITLE}"'?",
+  "options": [
+    {"label": "Yes — append to ROADMAP + create phase dir", "description": "One atomic docs commit (ROADMAP.md + roadmap.yaml + .gitkeep)."},
+    {"label": "Cancel", "description": "Exit without changes."}
+  ]
+}')
+case "$CHOICE" in
+  "Cancel"*) exit 0 ;;
+esac
+```
+
+## Append to ROADMAP
+
+The real append happens through `lib/roadmap.cjs.addBacklogEntry`
+which owns (1) input validation (500-char cap, YAML-separator reject),
+(2) the file lock, and (3) the 999.X numbering computed inside the
+mutator. The helper returns `{backlog_number, backlog_slug}`; we use
+those values — NOT the preview values — for the phase directory and
+commit subject.
+
+```bash
+RESULT=$(node -e "const r=require('./lib/roadmap.cjs').addBacklogEntry(process.argv[1]); process.stdout.write(JSON.stringify(r));" "$TITLE")
+BACKLOG_NUMBER=$(echo "$RESULT" | jq -r '.backlog_number')
+BACKLOG_SLUG=$(echo "$RESULT" | jq -r '.backlog_slug')
+```
+
+T-10-05-03 (description-breaks-YAML) is mitigated inside
+`addBacklogEntry`: it rejects descriptions containing the YAML
+separator pattern and caps length at 500 chars, then re-parses
+roadmap.yaml inside the lock to validate the post-mutation document.
+
+## Create Phase Dir Stub
+
+The backlog phase gets an empty `.gitkeep` directory so
+`/np:discuss-phase 999.X` and `/np:plan-phase 999.X` have a place to
+write CONTEXT/RESEARCH/PLAN artefacts when the idea graduates from
+parking lot to active planning.
+
+```bash
+STATE_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()))")
+PHASE_DIR="${STATE_DIR}/phases/${BACKLOG_NUMBER}-${BACKLOG_SLUG}"
+mkdir -p "$PHASE_DIR"
+touch "${PHASE_DIR}/.gitkeep"
+```
+
+## Commit
+
+Route through `node np-tools.cjs commit` so
+`lib/git.cjs.assertCommittablePaths()` validates each path before
+`git add`. ROADMAP.md (rendered), roadmap.yaml (canonical source), and
+the phase-dir `.gitkeep` land together as a single atomic unit per
+ADR-0004.
+
+```bash
+node np-tools.cjs commit "docs(10): add backlog item ${BACKLOG_NUMBER} — ${TITLE}" \
+  --files "${STATE_DIR}/ROADMAP.md" "${STATE_DIR}/roadmap.yaml" "${PHASE_DIR}/.gitkeep"
+```
+
+## Report
+
+```
+Backlog item added: ${BACKLOG_NUMBER} — ${TITLE}
+  Directory: ${PHASE_DIR}/
+
+This item lives in the backlog parking lot.
+Use /np:discuss-phase ${BACKLOG_NUMBER} to explore it further.
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Use `lib/roadmap.cjs.addBacklogEntry` (file-locked + atomic
+  YAML+MD write) — it is the single sanctioned mutator for the
+  synthetic `backlog` milestone.
+- Use `node np-tools.cjs phase next-decimal 999 --raw` for the
+  preview number ONLY. The authoritative number comes from
+  `addBacklogEntry`'s return value (re-computed inside the lock).
+- Commit ROADMAP.md + roadmap.yaml + phase-dir `.gitkeep` together
+  as a single atomic unit per ADR-0004.
+- Route the commit through `node np-tools.cjs commit` for
+  `lib/git.cjs.assertCommittablePaths()` validation.
+- Confirm via `askuser` Pattern S-3 before the mutation — the
+  roadmap.yaml write is visible in git history forever.
+
+**Don't:**
+- Hand-edit ROADMAP.md. The synthetic backlog milestone renders via
+  `lib/roadmap-render.cjs` (Plan 10-01-T05); direct edits will be
+  overwritten on the next render pass.
+- Use the preview number as the final commit subject. A concurrent
+  `/np:add-backlog` may race and claim the same number; only the
+  lock-returned `BACKLOG_NUMBER` is authoritative.
+- Invoke host-specific prompt tools directly (the BARE_ASKUSER lint
+  in `bin/check-workflows.cjs` blocks them) — always route through
+  `node np-tools.cjs askuser --json '…'`.
+- Add a `metrics record` block. There is no Task/Spawn site here;
+  Pitfall 9 / `workflow-missing-metrics` is exempt.
+</scope_guardrail>
+
+## Output
+
+- `.nubos-pilot/ROADMAP.md` — updated via
+  `lib/roadmap-render.cjs` to include the new 999.X entry under
+  the synthetic `## Backlog` H2 section (Plan 10-01-T05).
+- `.nubos-pilot/roadmap.yaml` — canonical source-of-truth with the
+  new phase appended to the `backlog` milestone's `phases:` array.
+- `.nubos-pilot/phases/999.X-<slug>/.gitkeep` — empty stub so
+  subsequent `/np:discuss-phase 999.X` invocations have a working
+  directory.
+- One atomic git commit
+  `docs(10): add backlog item 999.X — <title>` containing the three
+  files above (ADR-0004).
+
+## Success Criteria
+
+- [ ] Title validated (non-empty) before any roadmap read.
+- [ ] Preview number generated via
+      `node np-tools.cjs phase next-decimal 999 --raw` — info only.
+- [ ] Confirmation via `askuser` Pattern S-3 before mutation.
+- [ ] Authoritative 999.X comes from
+      `lib/roadmap.cjs.addBacklogEntry` return value (NOT the
+      preview number).
+- [ ] Phase directory created at
+      `${STATE_DIR}/phases/${BACKLOG_NUMBER}-${BACKLOG_SLUG}/` with
+      `.gitkeep` stub.
+- [ ] Single atomic commit via `np-tools.cjs commit` containing
+      ROADMAP.md + roadmap.yaml + `.gitkeep`.
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations and no DIRECT_READ pattern matches for the project
+      state directory.
+
+## Related Workflows
+
+- **`/np:add-todo <title>`** — smaller-scope pending todo capture
+  with STATE.md counter increment. Use when the idea is actionable
+  within a current plan.
+- **`/np:note [--global] <text>`** — zero-friction free-form capture
+  with no ROADMAP mutation. Use when the idea isn't yet scoped.
+- **`/np:discuss-phase 999.X`** — explore a backlog item
+  interactively to graduate it from parking-lot to active planning.
+- **`/np:plan-phase 999.X`** — produce a CONTEXT/RESEARCH/PLAN stack
+  for a backlog item once it is ready for implementation.
+
+## Design Notes
+
+Numbering + roadmap mutation run through
+`lib/roadmap.cjs.addBacklogEntry` (Plan 10-01-T05). The lib-level
+helper is file-locked and touches both the canonical `roadmap.yaml`
+AND the rendered ROADMAP.md atomically — ROADMAP.md is rendered
+output, not source-of-truth. The `.gitkeep` phase-dir stub keeps the
+working directory legible before planning lands.

package/workflows/add-tests.md

@@ -0,0 +1,69 @@
+---
+command: np:add-tests
+description: Persist Pass-SCs from VERIFICATION.md as node:test UAT blocks in test/uat/phase-<padded>-<slug>.test.cjs. Sentinel-preserving (D-20, Pitfall 8).
+---
+
+# /np:add-tests
+
+<objective>
+After `/np:verify-work` emits VERIFICATION.md with SC classifications,
+convert each Pass-SC into a runnable `node:test` case as a UAT regression
+suite. User-authored tests outside the `>>> np:add-tests begin … <<< end`
+sentinels survive regeneration.
+</objective>
+
+## Initialize
+
+```bash
+PHASE="$1"
+INIT=$(node np-tools.cjs init add-tests "$PHASE")
+```
+
+Parse: `phase`, `target_path`, `verification_path`, `pass_cases[]`,
+`skip_cases[]`. Target path is
+`<pkgRoot>/test/uat/phase-<padded>-<slug>.test.cjs`.
+
+## Execution
+
+Emit/merge the Sentinel block:
+
+```bash
+node np-tools.cjs init add-tests emit "$PHASE"
+```
+
+Smoke-run the generated file to catch syntax errors early:
+
+```bash
+node --test "$(echo "$INIT" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).target_path))")"
+```
+
+## Meta-commit
+
+UAT tests are a PHASE artifact, not a TASK artifact, so ADR-0004
+atomic-per-task does not apply — per D-19 this is a phase-level meta
+commit. Scope it tightly to the UAT file only (never `git add .`):
+
+```bash
+TARGET=$(echo "$INIT" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).target_path))")
+git add "$TARGET"
+git commit -m "docs(${PHASE}): persist UAT from verification"
+```
+
+## Scope Guardrail
+
+**Do:**
+- Render only the sentinel-bounded block; preserve everything outside.
+- Use `test.skip(..., { todo: ... })` for Fail/Defer cases so the suite
+  tracks them without failing CI.
+- `git add <target>` — single explicit path.
+
+**Don't:**
+- Overwrite user-authored tests outside the sentinels.
+- Commit the VERIFICATION.md and the UAT file together (separate commits;
+  VERIFICATION.md is committed by `/np:verify-work`).
+
+## Output
+
+- `test/uat/phase-<padded>-<slug>.test.cjs` with the sentinel-bounded
+  block updated.
+- Meta-commit `docs(<padded>): persist UAT from verification`.

package/workflows/add-todo.md

@@ -0,0 +1,222 @@
+---
+command: np:add-todo
+description: Capture a pending todo to .nubos-pilot/todos/pending/YYYY-MM-DD-<slug>.md; increments STATE.md pending_todos count via lib/state.cjs.mutateState single-writer lock. One atomic docs commit. No agent spawn.
+---
+
+# np:add-todo
+
+Implements UTIL-05a. Captures a free-form idea, task, or issue that
+surfaces mid-session as a structured
+pending todo so the originating workflow can continue without losing
+context. The todo lives under `.nubos-pilot/todos/pending/` and the
+pending-todo counter in STATE.md is bumped via the single-writer lock
+in `lib/state.cjs.mutateState` (D-20 invariant).
+
+This is a pure-CRUD workflow — no agent spawn, no resolve-model, no
+metrics record. The `workflow-missing-metrics` lint in
+`bin/check-workflows.cjs` only fires on `Task(` / `Spawn agent=` sites,
+so CRUD-only workflows are exempt (Pitfall 9 resolution from
+Plan 10-05). All interactive prompts route through
+`node np-tools.cjs askuser --json` per INST-03.
+
+## Initialize
+
+```bash
+DESCRIPTION="$*"
+if [[ -z "$DESCRIPTION" ]]; then
+  echo "Usage: /np:add-todo <description>" >&2
+  exit 2
+fi
+
+INIT=$(node np-tools.cjs init add-todo "$DESCRIPTION")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+
+SLUG=$(echo "$INIT" | jq -r '.slug')
+DATE=$(echo "$INIT" | jq -r '.date')
+TIMESTAMP=$(echo "$INIT" | jq -r '.timestamp')
+PENDING_DIR=$(echo "$INIT" | jq -r '.pending_dir')
+STATE_PATH=$(echo "$INIT" | jq -r '.state_path')
+TODO_PATH="${PENDING_DIR}/${DATE}-${SLUG}.md"
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `slug`,
+`todo_count`, `todos_dir_exists`, `pending_dir`, `state_path`. The
+init handler sanitises the slug through `lib/phase.cjs.phaseSlug`
+(strips to `[a-z0-9-]` only; T-10-05-01 filename-injection
+mitigation) and validates the description length (<= 500 chars) before
+any filesystem write occurs.
+
+## Create Pending Dir
+
+```bash
+mkdir -p "$PENDING_DIR"
+```
+
+The directory is created idempotently; no-op if it already exists.
+
+## Duplicate Check
+
+If a todo with this `DATE-SLUG` already exists in `pending/`,
+let the user resolve the collision via `askuser` Pattern S-3. The
+prompt surfaces four options: re-run (overwrite), view existing,
+skip (keep both), or rename-with-counter (append `-2`, `-3`, etc.).
+
+```bash
+if [[ -f "$TODO_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Duplicate todo",
+    "question": "A todo already exists at '"${TODO_PATH}"'. What would you like to do?",
+    "options": [
+      {"label": "Re-run — overwrite existing todo", "description": "Replaces the current todo body."},
+      {"label": "View — display the existing todo and exit", "description": "No changes."},
+      {"label": "Skip — keep existing and exit", "description": "Leaves the file untouched."},
+      {"label": "Rename — append -2/-3 counter to filename", "description": "Writes a new file beside the existing one."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*) cat "$TODO_PATH"; exit 0 ;;
+    "Skip"*) exit 0 ;;
+    "Rename"*)
+      i=2
+      while [[ -f "${PENDING_DIR}/${DATE}-${SLUG}-${i}.md" ]]; do i=$((i + 1)); done
+      TODO_PATH="${PENDING_DIR}/${DATE}-${SLUG}-${i}.md"
+      ;;
+  esac
+fi
+```
+
+## Write Todo File
+
+Use the `Write` tool (not a bash heredoc) to create `$TODO_PATH` with
+the following frontmatter + body. The agent invokes the `Write` tool
+directly — this is documented here as the contract, not executed as a
+shell step.
+
+```markdown
+---
+title_short: <first 100 chars of DESCRIPTION, single line>
+created: <TIMESTAMP>
+status: pending
+---
+
+<DESCRIPTION>
+```
+
+Specifically: `title_short` = the first 100 chars of `$DESCRIPTION`
+flattened to a single line (newlines replaced with spaces) so the
+frontmatter stays parseable even when the raw description contains
+YAML metacharacters or multiple lines, `created` = `$TIMESTAMP`
+(init-supplied ISO-8601), `status` always `pending`. The body carries
+the full raw description verbatim so the file is self-contained when
+read weeks later. This mirrors the `note.md` pattern (truncated
+frontmatter field + full body) and pairs with the
+`add-todo-invalid-description` YAML-separator guard in
+`bin/np-tools/add-todo.cjs._buildPayload`. Do **not** include
+`status: completed` or any other status here — the completion flow
+lives in a separate workflow.
+
+## Update STATE.md
+
+STATE.md is mutated through `lib/state.cjs.mutateState` which wraps
+`withFileLock` (D-20 single-writer invariant, T-10-05-06 mitigation).
+The node one-liner is the sanctioned surface; direct filesystem
+reads of the project state directory from this workflow would bypass
+the lock and are explicitly forbidden by the check-workflows lint.
+
+```bash
+node -e "require('./lib/state.cjs').mutateState(function (doc) { doc.frontmatter.pending_todos = (doc.frontmatter.pending_todos || 0) + 1; return doc; });"
+```
+
+The mutator increments the `pending_todos` counter on the STATE.md
+frontmatter. The lock serialises concurrent writers (two parallel
+`/np:add-todo` invocations converge on the correct count).
+
+## Commit
+
+Route through `node np-tools.cjs commit` so
+`lib/git.cjs.assertCommittablePaths()` validates the paths before
+`git add` (path-traversal guard from Plan 10-01-T04).
+
+```bash
+node np-tools.cjs commit "docs(10): add todo — ${SLUG}" --files "$TODO_PATH" "$STATE_PATH"
+```
+
+Both the new todo file and STATE.md land in a single atomic commit per
+ADR-0004 (one commit per unit).
+
+## Report
+
+```
+Todo saved: $TODO_PATH
+
+  Title:  $DESCRIPTION
+  Status: pending
+  Created: $TIMESTAMP
+
+Pending todo count bumped via lib/state.cjs.mutateState.
+Use /np:next to surface this todo in the next-step picker.
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Always go through `lib/state.cjs.mutateState` for STATE.md updates
+  (D-20 single-writer lock; T-10-05-06 mitigation).
+- Use the `Write` tool for the new markdown file — never a bash
+  heredoc or `echo >`.
+- Route the final commit through `node np-tools.cjs commit` so
+  `lib/git.cjs.assertCommittablePaths()` runs the gitignore-guard.
+- Derive the slug via `node np-tools.cjs init add-todo` (filename
+  sanitisation, T-10-05-01 mitigation) — not via ad-hoc `sed`.
+- Commit todo file + STATE.md together as a single atomic unit.
+
+**Don't:**
+- Invoke host-specific prompt tools directly (the BARE_ASKUSER lint in
+  `bin/check-workflows.cjs` blocks them) — always route through
+  `node np-tools.cjs askuser --json '…'`.
+- Read STATE.md via raw filesystem calls (DIRECT_READ lint blocks
+  those patterns) — let `mutateState` handle the lock.
+- Add a `metrics record` block. There is no Task/Spawn site in this
+  workflow, so Pitfall 9 / the `workflow-missing-metrics` lint is
+  exempt.
+- Touch the completed-todos subtree — completion is a separate
+  workflow concern.
+</scope_guardrail>
+
+## Output
+
+- `.nubos-pilot/todos/pending/YYYY-MM-DD-<slug>.md` — new todo file
+  with `title / created / status: pending` frontmatter and the
+  description as body text.
+- `.nubos-pilot/STATE.md` — `pending_todos` frontmatter counter
+  incremented via `mutateState`.
+- One atomic git commit `docs(10): add todo — <slug>` containing
+  both files (ADR-0004).
+
+## Success Criteria
+
+- [ ] Description validated (non-empty, <= 500 chars) via the init
+      handler before any filesystem write.
+- [ ] Slug derived via `phaseSlug` so only `[a-z0-9-]` enter the
+      filename (T-10-05-01 mitigation).
+- [ ] Pending todo directory created idempotently.
+- [ ] Duplicate collisions resolved via `askuser` Pattern S-3
+      (Re-run / View / Skip / Rename-with-counter).
+- [ ] Todo file written via the `Write` tool with valid frontmatter.
+- [ ] STATE.md `pending_todos` counter incremented via
+      `lib/state.cjs.mutateState` (D-20 single-writer lock).
+- [ ] Both files committed atomically via `np-tools.cjs commit`.
+- [ ] Lint clean under `bin/check-workflows.cjs` — no BARE_ASKUSER
+      violations and no DIRECT_READ pattern matches for the project
+      state directory.
+
+## Related Workflows
+
+- **`/np:note <text>`** — zero-friction free-form capture (no STATE
+  mutation, no todo semantics). Use when the idea isn't yet actionable.
+- **`/np:add-backlog <title>`** — larger-scope capture for ideas that
+  deserve a full backlog phase (`999.x` in ROADMAP.md).
+- **`/np:next`** — surfaces the next actionable item; a pending todo
+  can be the pointer when no active plan has a runnable task.