nubos-pilot 0.1.0

package/workflows/note.md

@@ -0,0 +1,244 @@
+---
+command: np:note
+description: Capture a free-form note to markdown. Defaults to project scope (.nubos-pilot/notes/YYYY-MM-DD-<slug>.md, committed). Use --global for sensitive/cross-project notes (~/.nubos-pilot/notes/YYYY-MM-DD-<slug>.md, NOT committed). No agent spawn, no STATE mutation.
+---
+
+# np:note
+
+Implements UTIL-05b. Zero-friction idea capture that writes the note
+text verbatim to a timestamped markdown file.
+Unlike `/np:add-todo`, `/np:note` does NOT touch STATE.md and has no
+pending-todo semantics — it is the fastest-possible surface for
+"capture now, triage later".
+
+This workflow ships with a project-default + global-fallback scope
+model. Project scope (`.nubos-pilot/notes/YYYY-MM-DD-<slug>.md`,
+committed per ADR-0004) is the happy path. The `--global` flag routes
+to `~/.nubos-pilot/notes/` and intentionally does **not** commit —
+global notes live outside any repository (Pitfall 10: the global
+branch bypasses `lib/core.cjs.findProjectRoot` entirely so the tool
+works from any cwd, including directories that have no project at
+all).
+
+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
+SCOPE="project"
+TEXT_ARGS=()
+for arg in "$@"; do
+  case "$arg" in
+    --global) SCOPE="global" ;;
+    *)        TEXT_ARGS+=("$arg") ;;
+  esac
+done
+TEXT="${TEXT_ARGS[*]}"
+if [[ -z "$TEXT" ]]; then
+  echo "Usage: /np:note [--global] <text>" >&2
+  exit 2
+fi
+```
+
+The `--global` flag is stripped from anywhere in `$@` (beginning,
+middle, or end of the argv list) before the remaining args are joined
+into `$TEXT`. Empty text after stripping is an error — there is no
+`list` or `promote` subcommand here (deferred to a future
+capture-management plan).
+
+## Compute Paths
+
+Scope branching is explicit (T-10-05-02 mitigation + Pitfall 10
+guidance). The project branch walks the `lib/core.cjs.projectStateDir`
+resolver which asserts the cwd is inside a project. The global branch
+sidesteps that resolver and hardcodes `HOME + /.nubos-pilot/notes`.
+
+```bash
+if [[ "$SCOPE" == "global" ]]; then
+  NOTES_DIR="$HOME/.nubos-pilot/notes"
+else
+  NOTES_DIR=$(node -e "console.log(require('./lib/core.cjs').projectStateDir(process.cwd()) + '/notes')")
+fi
+mkdir -p "$NOTES_DIR"
+DATE=$(date +%Y-%m-%d)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SLUG=$(node np-tools.cjs generate-slug "$TEXT" --raw)
+if [[ -z "$SLUG" ]]; then
+  echo "Error: note text produced no slug-safe characters." >&2
+  exit 1
+fi
+NOTE_PATH="${NOTES_DIR}/${DATE}-${SLUG}.md"
+```
+
+Slug generation is delegated to `node np-tools.cjs generate-slug`
+(which wraps `lib/phase.cjs.phaseSlug`) — the same filename-safety
+rails used by every capture workflow (T-10-05-01 & T-10-05-02
+mitigation; only `[a-z0-9-]` enter the filename).
+
+## Duplicate Check
+
+Same `date + slug` collisions are resolved via `askuser` Pattern S-3.
+The fourth option, "append-timestamp", adds the current `HHMM` to the
+filename so rapid-fire notes on the same topic each get their own
+file.
+
+```bash
+if [[ -f "$NOTE_PATH" ]]; then
+  CHOICE=$(node np-tools.cjs askuser --json '{
+    "type": "select",
+    "header": "Duplicate note",
+    "question": "A note already exists at '"${NOTE_PATH}"'. What would you like to do?",
+    "options": [
+      {"label": "Re-run — overwrite existing note",      "description": "Replaces the body with the new text."},
+      {"label": "View — display existing note and exit",  "description": "No changes."},
+      {"label": "Skip — keep existing and exit",          "description": "Leaves the file untouched."},
+      {"label": "Append-timestamp — add HHMM suffix",     "description": "Writes a new file with a time-suffixed name."}
+    ]
+  }')
+  case "$CHOICE" in
+    "View"*) cat "$NOTE_PATH"; exit 0 ;;
+    "Skip"*) exit 0 ;;
+    "Append-timestamp"*)
+      HHMM=$(date +%H%M)
+      NOTE_PATH="${NOTES_DIR}/${DATE}-${SLUG}-${HHMM}.md"
+      ;;
+  esac
+fi
+```
+
+## Write Note File
+
+Use the `Write` tool to create `$NOTE_PATH` with the following
+frontmatter + body. The first 100 characters of `$TEXT` flow into a
+short `text:` field for quick scanning; the full verbatim text lives
+in the body so notes containing `:` characters or multi-line content
+cannot break the YAML frontmatter (T-10-05-03 defence-in-depth
+variant — the full text is never interpolated into frontmatter).
+
+```markdown
+---
+text: <first line of TEXT, truncated to 100 chars>
+created: <TIMESTAMP>
+scope: project | global
+promoted: false
+---
+
+<TEXT>
+```
+
+The note text is captured verbatim — typos, emoji, capitalisation are
+all preserved. The `promoted` flag starts as `false`; a future
+capture-management workflow will flip it when a note is promoted to a
+todo.
+
+## Commit (project scope only)
+
+Project-scope notes commit to git per ADR-0004 so the capture shows
+up in the repo history. Global-scope notes do **not** commit — they
+live under `$HOME/.nubos-pilot/notes/` which is outside any repo, and
+committing would require running `git` against an unknown repo (or
+none). The scope-branching commit step is the single-source-of-truth
+for that distinction.
+
+```bash
+if [[ "$SCOPE" == "project" ]]; then
+  node np-tools.cjs commit "docs(10): add note — ${SLUG}" --files "$NOTE_PATH"
+else
+  echo "Global note written to $NOTE_PATH (not committed — lives outside any project)." >&2
+fi
+```
+
+## Report
+
+```
+Note saved ($SCOPE): $NOTE_PATH
+
+  Text:    $TEXT
+  Created: $TIMESTAMP
+  Scope:   $SCOPE
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Use `--global` for sensitive data that must not enter git history
+  (API keys, personal context, cross-project thoughts). Project scope
+  writes are committed; treat them as public.
+- Let `lib/core.cjs.projectStateDir` throw on a non-project cwd for
+  project scope — the error message is clearer than a silent write
+  to a resolved-to-unexpected-root.
+- For global scope, bypass `lib/core.cjs.findProjectRoot` completely
+  (Pitfall 10) so the workflow works from any cwd, including non-repo
+  directories.
+- Derive the slug via `node np-tools.cjs generate-slug` so only
+  `[a-z0-9-]` enter the filename.
+- Route the project-scope commit through `node np-tools.cjs commit`
+  for `lib/git.cjs.assertCommittablePaths()` validation.
+
+**Don't:**
+- Commit global-scope notes. They live outside any repo; committing
+  them from this workflow would write into whatever git repo happens
+  to contain the current cwd.
+- Put the full note text in the frontmatter `text:` field —
+  multi-line content or `:` characters would break YAML parsing
+  (T-10-05-03 defence-in-depth).
+- 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 '…'`.
+- Mutate STATE.md. Notes are lighter-weight than todos; there is no
+  pending-note counter. If you need STATE semantics, use
+  `/np:add-todo` instead.
+- Add a `metrics record` block. There is no Task/Spawn site here;
+  Pitfall 9 / `workflow-missing-metrics` is exempt.
+</scope_guardrail>
+
+## Output
+
+- `.nubos-pilot/notes/YYYY-MM-DD-<slug>.md` (project scope) OR
+  `~/.nubos-pilot/notes/YYYY-MM-DD-<slug>.md` (global scope) — note
+  file with `text / created / scope / promoted:false` frontmatter and
+  the verbatim capture as body text.
+- Project scope only: one atomic git commit
+  `docs(10): add note — <slug>` containing the new note file.
+- Global scope: no commit. The note lives outside the repo.
+
+## Success Criteria
+
+- [ ] `--global` stripped from `$@` at any position.
+- [ ] Scope defaults to `project`; `--global` switches to HOME-based
+      path (Pitfall 10 mitigation — bypasses findProjectRoot).
+- [ ] Project-scope directory resolved via
+      `lib/core.cjs.projectStateDir`.
+- [ ] Slug produced via `node np-tools.cjs generate-slug` (only
+      `[a-z0-9-]` enter filename).
+- [ ] Duplicate collisions resolved via `askuser` Pattern S-3
+      (Re-run / View / Skip / Append-timestamp).
+- [ ] Note text captured verbatim in body (never in frontmatter).
+- [ ] Project-scope notes committed via `np-tools.cjs commit`;
+      global-scope notes not committed (stderr confirmation only).
+- [ ] STATE.md is NOT touched by this workflow (notes have no
+      pending-counter semantics).
+- [ ] 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>`** — pending todo capture with STATE.md
+  counter increment. Use when the idea is actionable.
+- **`/np:add-backlog <title>`** — larger-scope capture for a full
+  backlog phase (`999.x`) entry in ROADMAP.md.
+
+## Design Notes
+
+`list` and `promote` subcommands are out of scope (they belong to a
+future capture-management workflow). Global notes live under
+`~/.nubos-pilot/notes/` per D-14. Empty text after flags errors out
+rather than falling through to a list dump — the explicit failure
+mode is easier to debug than an accidental list surface.

package/workflows/park.md

@@ -0,0 +1,29 @@
+---
+command: np:park
+description: Mark a task as parked (lifecycle CRUD). Use when a task needs to be deferred without being marked skipped.
+---
+
+# /np:park
+
+<objective>
+Flip the task's frontmatter `status` field to `parked`. Like `skipped`,
+parked tasks are excluded from wave-selection — but the semantic intent
+is "come back to this", so `/np:unpark` returns it to `pending` rather
+than implying the task was permanently dropped.
+</objective>
+
+## Execution
+
+```bash
+TASK_ID="$1"
+if [ -z "$TASK_ID" ]; then
+  echo "Usage: /np:park <task-id>" >&2
+  exit 1
+fi
+node np-tools.cjs park "$TASK_ID"
+```
+
+## Scope Guardrail
+
+**Do:** flip task status to `parked` via `lib/tasks.setTaskStatus`.
+**Don't:** revert commits; modify other frontmatter fields.

package/workflows/pause-work.md

@@ -0,0 +1,34 @@
+---
+command: np:pause-work
+description: Stamp STATE.session.stopped_at and resume_file for explicit session handoff. No git stash (D-08 semantic).
+---
+
+# /np:pause-work
+
+<objective>
+Record the session boundary in STATE.md so the next session (or a
+different operator) can re-enter via `/np:resume-work`. The in-flight
+checkpoint, if any, is untouched — it continues to capture the executor's
+progress.
+</objective>
+
+## Execution
+
+```bash
+node np-tools.cjs init pause-work
+```
+
+Output is a small JSON payload `{ ok, stopped_at, resume_file }`. The
+workflow simply displays it.
+
+## Scope Guardrail
+
+**Do:** stamp STATE.session; print the resume hint.
+**Don't:** stash, discard, or modify the working tree; delete checkpoints
+(resume-work needs them).
+
+## Output
+
+- STATE.md updated with `session.stopped_at = <ISO>` and
+  `session.resume_file = .nubos-pilot/checkpoints/<task-id>.json` (or null
+  if no active task).

package/workflows/plan-milestone-gaps.md

@@ -0,0 +1,233 @@
+---
+command: np:plan-milestone-gaps
+description: Create corrective phases for audit gaps without touching completed phases.
+---
+
+# np:plan-milestone-gaps
+
+Create corrective phases for gaps surfaced by phase VERIFICATION.md files or
+an external audit markdown. New phases are appended to the current milestone
+(or decimal-inserted after a chosen base phase) and their `depends_on` is
+ALWAYS set to the *semantic* source phase — never the positional insertion
+point. Completed phases are NEVER rewritten.
+
+## Philosophy
+
+<philosophy>
+Gaps are the gap between plan and reality. When a plan's VERIFICATION.md
+flags unfinished checkboxes, explicit `## Gap:` sections, or `❌` / `FAIL`
+markers, the correct response is NOT to edit the originating phase — that
+phase shipped, its SUMMARY.md was written, its commit landed. Instead, we
+ADD a corrective phase whose `depends_on` cites the source phase, leaving the
+git history linear and the downstream roadmap unmutated.
+</philosophy>
+
+## Scope Guardrail
+
+<scope_guardrail>
+This workflow ONLY touches `.nubos-pilot/roadmap.yaml` (via the lib's write
+API) and `.nubos-pilot/ROADMAP.md` (regenerated atomically in the same lock).
+It NEVER:
+
+- rewrites completed phases' `depends_on` to route through the new phase
+- deletes or renumbers existing phases
+- reads files outside the project root (`parseAuditFile` rejects with
+  `gaps-invalid-audit-path`)
+- writes outside `.nubos-pilot/` or the workflow's own logs
+
+Any proposed deviation from these invariants MUST be raised with the user
+before proceeding.
+</scope_guardrail>
+
+## Downstream Awareness
+
+<downstream_awareness>
+A decimal-inserted phase (e.g. `7.1` after phase 7) is PHYSICALLY positioned
+between 7 and 8 in the yaml, but the `depends_on` edges of phases 8+ are NOT
+rewritten. This is load-bearing: other workflows (progress, next, the
+executor's wave planner) treat the numeric edges in `depends_on` as the
+authoritative dependency graph. If a user wants phase 8 to depend on `7.1`
+they must edit phase 8's `depends_on` explicitly — this workflow will not do
+it on their behalf, because doing so in bulk is how corrective phases
+silently invalidate in-flight SUMMARY.md claims. See Phase 5 RESEARCH §
+"Pitfall 5" for the full rationale.
+</downstream_awareness>
+
+## Single-Call Init
+
+All context is gathered in one call to `np-tools.cjs init
+plan-milestone-gaps`. The subcommand scans every phase's VERIFICATION.md (or
+parses `--from <audit.md>` when supplied), resolves the current milestone
+from STATE.md, and returns a JSON payload consumable by the rest of this
+workflow.
+
+```bash
+INIT=$(node np-tools.cjs init plan-milestone-gaps "$@")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+The payload shape:
+
+```json
+{
+  "_workflow": "plan-milestone-gaps",
+  "milestoneId": "v1.0",
+  "mode": "scan" | "from-file",
+  "gaps": [
+    {
+      "source_phase": 7,
+      "gap_type": "explicit" | "unchecked-box" | "fail-marker",
+      "description": "…",
+      "severity": "critical" | "major" | "minor"
+    }
+  ],
+  "insertAfter": null | <integer>,
+  "agent_skills": { "np-planner": <skills-payload | null> }
+}
+```
+
+Extract fields with standard shell JSON handling (e.g. `jq`). All further
+logic in this workflow MUST key off `INIT` — do NOT re-read files directly.
+
+## Answer Validation
+
+<answer_validation>
+Before mutating the roadmap, confirm with the user:
+
+1. How many gaps were found and which phases they originated from.
+2. Whether to append new phases at the milestone tail (default) or to use a
+   decimal insert via `--insert-after N`.
+3. Whether to proceed when the gap set is empty (usually: exit).
+
+All three confirmations use `np-tools.cjs askuser` (Pattern 2) — NEVER a
+bare `AskUserQuestion` invocation. The executor hosts will route the JSON
+question through whichever UI they support.
+</answer_validation>
+
+### Empty-gap short circuit
+
+```bash
+if [[ $(echo "$INIT" | jq '.gaps | length') -eq 0 ]]; then
+  node np-tools.cjs askuser --json '{
+    "type": "confirm",
+    "prompt": "No gaps found in VERIFICATION.md scan / audit. Exit without changes?",
+    "default": true
+  }'
+  exit 0
+fi
+```
+
+### Scan-mode confirmation
+
+```bash
+MODE=$(echo "$INIT" | jq -r '.mode')
+if [[ "$MODE" == "scan" ]]; then
+  node np-tools.cjs askuser --json '{
+    "type": "select",
+    "prompt": "Gaps found via VERIFICATION.md scan. Choose how to apply them:",
+    "options": [
+      "Proceed — append new phases to milestone tail",
+      "Abort — I want to re-run with --insert-after N",
+      "Cancel"
+    ]
+  }'
+fi
+```
+
+### From-file confirmation
+
+```bash
+if [[ "$MODE" == "from-file" ]]; then
+  node np-tools.cjs askuser --json '{
+    "type": "confirm",
+    "prompt": "Audit file parsed. Proceed to create corrective phases?",
+    "default": true
+  }'
+fi
+```
+
+## Apply Gap-to-Phase Conversion
+
+All file writes are delegated to `lib/gaps.cjs#gapsToPhases`. This keeps the
+workflow thin: no inline YAML mutation, no direct `atomicWriteFileSync` use,
+no hand-rolled slug generation. The lib function already:
+
+- groups gaps by `source_phase` (one new phase per unique source)
+- sets `depends_on: [source_phase]` (SEMANTIC — not positional)
+- calls `addPhase(milestoneId, …)` or `insertPhaseAfter(base, …)` based on
+  `insertAfter`
+- wraps the mutation in `withFileLock` and regenerates ROADMAP.md atomically
+
+```bash
+# Compose the apply payload and invoke the lib directly via node -e. Using
+# node -e keeps this file hermetic (no spawn of a separate CLI verb for
+# mutation) and delegates lock + render to lib/gaps.cjs.
+node -e '
+  const gaps = JSON.parse(process.env.GAPS);
+  const insertAfter = process.env.INSERT_AFTER === "null" ? null : Number(process.env.INSERT_AFTER);
+  const { gapsToPhases } = require("./lib/gaps.cjs");
+  const created = gapsToPhases(gaps, { insertAfter });
+  process.stdout.write(JSON.stringify({ created }, null, 2));
+' \
+  GAPS="$(echo "$INIT" | jq -c '.gaps')" \
+  INSERT_AFTER="$(echo "$INIT" | jq -r '.insertAfter // "null"')"
+```
+
+## Commit the Roadmap Change
+
+The roadmap mutation is already atomic. The workflow's final step is to
+commit the updated `roadmap.yaml` + regenerated `ROADMAP.md` so the change
+is preserved in git history — but ONLY when `.nubos-pilot/config.json`'s
+`commit_docs` flag is `true` (default).
+
+```bash
+COMMIT_DOCS=$(node -e 'try{
+  const c=require("./.nubos-pilot/config.json");
+  process.stdout.write(String(c.commit_docs !== false));
+}catch(e){process.stdout.write("true");}')
+
+if [[ "$COMMIT_DOCS" == "true" ]]; then
+  # Stage and commit via the git CLI (safe arg-array form; never string-concat
+  # the commit message through a shell). Empty diff is silently tolerated.
+  git add .nubos-pilot/roadmap.yaml .nubos-pilot/ROADMAP.md
+  if ! git diff --cached --quiet; then
+    # Choose the verb from mode: append vs insert.
+    VERB="append"
+    if [[ "$(echo "$INIT" | jq -r '.insertAfter')" != "null" ]]; then
+      VERB="insert"
+    fi
+    git commit --no-verify -m "docs(05-05): plan-milestone-gaps ${VERB} phase(s)"
+  fi
+else
+  echo "commit_docs=false — skipping roadmap commit (roadmap.yaml/ROADMAP.md remain staged-dirty)" >&2
+fi
+```
+
+## Naming Conventions (D-03)
+
+Canonical tokens this workflow uses:
+
+| Token                                 | Value                          |
+| ------------------------------------- | ------------------------------ |
+| Tools-binary                          | `np-tools.cjs`                 |
+| Slash-command                         | `/np:plan-milestone-gaps`      |
+| Roadmap file path                     | `.nubos-pilot/ROADMAP.md`      |
+
+Auto-advance state lives on `workflow.auto_advance` (boolean). Set
+from `/np:autonomous`; cleared when the loop exits or the user aborts.
+
+## Exit Codes
+
+- `0` — applied successfully, or user aborted with nothing to do.
+- non-zero — unrecoverable error (invalid audit path, YAML parse failure,
+  duplicate slug on re-run). Error code + message are emitted on stderr in
+  JSON `{error: {code, message, details}}` form by `np-tools.cjs`.
+
+## See Also
+
+- `lib/gaps.cjs` — scan, parse, group-to-phase logic (pure, unit-tested).
+- `lib/roadmap.cjs` — write API (`addMilestone`, `addPhase`,
+  `insertPhaseAfter`).
+- Phase 05 RESEARCH § "Pitfall 5" — why `depends_on` must be semantic.
+- `/np:next` — dispatches to this workflow when the project state flags
+  uncovered gaps.