nubos-pilot 1.3.2 → 1.3.4

package/workflows/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 command: np:plan-phase
 description: Plans a milestone (M<NNN>) — breaks it into slices (waves) and tasks. Spawns np-planner (opus) + np-plan-checker (opus), 2-iteration verification, then scaffolds every task file.
-argument-hint: <milestone-number> [--research] [--repromote]
+argument-hint: <milestone-number> [--research] [--architect] [--repromote]
 ---
 
 # np:plan-phase
@@ -41,17 +41,19 @@ Output layout:
 ```bash
 PHASE=""
 RESEARCH_FLAG=0
+ARCHITECT_FLAG=0
 REPROMOTE_FLAG=0
 for arg in "$@"; do
   case "$arg" in
     --research)  RESEARCH_FLAG=1 ;;
+    --architect) ARCHITECT_FLAG=1 ;;
     --repromote) REPROMOTE_FLAG=1 ;;
     --*)         echo "Unknown flag: $arg" >&2; exit 2 ;;
     *)           [[ -z "$PHASE" ]] && PHASE="$arg" ;;
   esac
 done
 if [[ -z "$PHASE" ]]; then
-  echo "Usage: /np:plan-phase <milestone-number> [--research] [--repromote]" >&2
+  echo "Usage: /np:plan-phase <milestone-number> [--research] [--architect] [--repromote]" >&2
   exit 2
 fi
 ```
@@ -154,6 +156,19 @@ fi
 
 **Exit code 42 contract:** orchestrator sees exit 42 → runs `/np:research-phase $PHASE` → re-enters `/np:plan-phase $PHASE` without the `--research` flag.
 
+### Gate 2b — Optional architecture pass (`--architect`)
+
+The `--architect` flag auto-dispatches `/np:architect-phase` before planning, so a structural ADR pass (`M<NNN>-ARCHITECTURE.md`) is decided up front and the planner consumes it like an extension of CONTEXT.md. Dispatched AFTER research (the established flow is research → architect → plan): when both flags are set, the research re-entry strips `--research`, leaving `--architect` to dispatch on the next pass.
+
+```bash
+if [[ "$ARCHITECT_FLAG" == "1" ]]; then
+  echo "architect-auto: dispatching /np:architect-phase $PHASE before planning" >&2
+  exit 43
+fi
+```
+
+**Exit code 43 contract:** orchestrator sees exit 43 → runs `/np:architect-phase $PHASE` → re-enters `/np:plan-phase $PHASE` without the `--architect` flag. The milestone `np-architect` stays intent-level (ADR-0019): its decisions inform the plan; they do not bake schema/filenames/code-style into `PLAN.md`.
+
 **Researcher-Schwarm semantics (ADR-0011).** The dispatched `/np:research-phase` runs in Schwarm mode by default (`swarm.research.k=3`). The cache-bypass at Pre-flight short-circuits the swarm whenever the milestone goal + requirements match a stored learning at similarity ≥ `swarm.research.threshold` and `occurrence ≥ swarm.research.minOccurrence`. The merged consensus carries a `<consensus_meta>` block (`k`, `agreement_score`, `flagged_decisions`) which `np-plan-checker` reads to weight downstream verdicts. No additional flags needed at this site — the swarm runs automatically when `--research` is set.
 
 ### Gate 3 — Milestone already planned

package/workflows/simplify-debt.md

@@ -0,0 +1,93 @@
+---
+command: np:simplify-debt
+description: Economy-debt ledger — record, list, and resolve simplifications you deferred rather than fixed now, so "later" doesn't become "never". CRUD-only (no agent spawn unless you harvest from a review). Manual twin of the in-loop Economy critic (agents.economy full/ultra).
+argument-hint: "[list [--status open|resolved|all]] | [add --file <f> --line <n> --category <c> --note <text>] | [resolve <id>] | [harvest [<git-range>]]"
+---
+
+# /np:simplify-debt
+
+<objective>
+Keep a durable ledger of over-engineering you chose NOT to fix this round. `/np:simplify-review` finds what could be deleted, reused, or condensed; whatever you defer goes here as a tracked entry, so the shortcut is harvested rather than lost. Each entry carries a `file`, optional `line`, one of the four Economy categories (`over-engineering` / `stdlib-reinvention` / `native-duplication` / `shrinkable`), and a one-line note. This command is CRUD over `.nubos-pilot/economy-debt/` — it does not edit source and does not commit code. It is the deferred-work counterpart of the in-loop Economy critic (`/np:execute-phase` with `agents.economy` set to `full` or `ultra`).
+</objective>
+
+## Initialize
+
+```bash
+LANG_DIRECTIVE=$(node .nubos-pilot/bin/np-tools.cjs lang-directive)
+VERB="${1:-list}"
+```
+
+`$LANG_DIRECTIVE` governs the prose you wrap around the CLI output; the ledger lines (id, category, `file:line`, note) stay canonical. Supersedes CLAUDE.md.
+
+## Route by verb
+
+This is a pure-CRUD workflow — the ledger lives behind `node .nubos-pilot/bin/np-tools.cjs simplify-debt`; never read or write `.nubos-pilot/economy-debt/` directly.
+
+### `list` (default)
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs simplify-debt list --status "${2:-open}"
+```
+
+Prints the open ledger (oldest debt first — longest-deferred is most urgent). `--status resolved` or `--status all` widen the view; append `--json` for the machine shape. Print the output verbatim.
+
+### `add`
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs simplify-debt add \
+  --file "$FILE" --line "$LINE" --category "$CATEGORY" --note "$NOTE"
+```
+
+`--category` MUST be one of `over-engineering`, `stdlib-reinvention`, `native-duplication`, `shrinkable` (the CLI rejects anything else). `--line` is optional (omit for a file-level note). Adds are idempotent: re-adding an identical finding is a no-op (`was_new=false`), so re-harvesting the same review never duplicates.
+
+### `resolve`
+
+```bash
+node .nubos-pilot/bin/np-tools.cjs simplify-debt resolve "$ID"
+```
+
+Moves the entry from `open/` to `resolved/` and stamps the resolution time. Use it once the simplification has actually landed (by hand or via a later `/np:execute-phase` round).
+
+### `harvest [<git-range>]`
+
+Spawn ONE read-only reviewer — `Agent(subagent_type="np-simplifier", prompt=<…>)` — over the diff (default: working tree + staged vs `HEAD`; or the passed git range). Its prompt MUST carry `agents/np-critic-economy.md` as the rubric (the canonical ladder + safety boundaries) and the captured `git diff --no-color`. For each finding the reviewer returns that you are NOT fixing now, record it with one `simplify-debt add` call (mapping the report tag to the matching `--category`). Findings you fix immediately are not harvested. Print the resulting open ledger when done.
+
+## No Source Mutation
+
+CRUD over the ledger only. This workflow NEVER edits source, NEVER stages, NEVER commits code. The ledger files under `.nubos-pilot/economy-debt/` are the only writes; commit them with your normal docs/artifact flow if `workflow.commit_docs` is set.
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Route every ledger read/write through `node .nubos-pilot/bin/np-tools.cjs simplify-debt <verb>` — never touch `.nubos-pilot/economy-debt/` directly.
+- Use one of the four Economy categories on `add`; the CLI is the source of truth and rejects others.
+- On `harvest`, pass `agents/np-critic-economy.md` to the reviewer so the ledger and the in-loop critic apply the identical bar.
+
+**Don't:**
+- Edit, stage, or commit source — this command only records deferred work. No `Write`/`Edit` of source, no `git add` of code.
+- Log a test, input-validation, error-handling, security, or required-edge-case removal as debt — those are completeness, never economy (the rubric's safety boundaries; completeness wins).
+- Record low-confidence "could be cleaner" noise — every entry needs a concrete file + replacement, same bar as `/np:simplify-review`.
+</scope_guardrail>
+
+## Output
+
+- The ledger view (open / resolved / all) or the result of an `add` / `resolve`, printed verbatim.
+- On `harvest`: one ledger entry per deferred finding, then the refreshed open ledger.
+- No source changes, no code commits.
+
+## Definition of Done
+
+Ledger CRUD. Definition of Done, per [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md):
+
+- Rule 3 (Do it with tests) — the ledger NEVER records deleting or weakening test code; coverage is completeness, not debt.
+- Rule 8 (Never present a workaround when the real fix exists) — entries point at the root-cause-simple form, not an obscure golfed one-liner.
+- Rule 11 (Ship the complete thing) — deferred simplifications are tracked, not silently dropped; "later" stays visible until `resolve`.
+
+Any violation = the operation is incomplete; surface it and exit non-zero. The orchestrator does not relax these.
+
+## Related Workflows
+
+- **`/np:simplify-review <git-range>`** — read-only economy audit of a diff (the finder; this command is the ledger that outlives a single review).
+- **`/np:execute-phase`** — runs the Economy critic in-loop when `agents.economy` is `full` or `ultra`, enforcing the same rubric during execution.
+- **`/np:add-todo`** — general pending-todo capture (this command is the economy-specific deferred-work ledger).

package/workflows/simplify-review.md

@@ -0,0 +1,103 @@
+---
+command: np:simplify-review
+description: Read-only economy audit of a git diff, the working tree, or the whole repo (--repo) — flags over-engineering, stdlib-reinvention, native-duplication, and shrinkable logic via the np-simplifier agent. Never edits or commits; emits a deletion-oriented report. Manual twin of the Economy critic axis (agents.economy full/ultra).
+argument-hint: "[<git-range> | --repo]  (default: working tree + staged vs HEAD)"
+---
+
+# /np:simplify-review
+
+<objective>
+Catalogue what could be deleted, reused, or condensed in a change set — the "wrote-too-much" review. A read-only `np-simplifier` agent scans the diff against the Economy rubric (`agents/np-critic-economy.md`) and emits one finding per removable construct plus a `net: -<N> lines possible.` summary. This command NEVER edits source and NEVER commits; it hands a report to the user. It is the manual counterpart of the in-loop Economy critic (`/np:execute-phase` with `agents.economy` set to `full` or `ultra`), and both apply the identical rubric and safety boundaries.
+</objective>
+
+## Initialize
+
+```bash
+LANG_DIRECTIVE=$(node .nubos-pilot/bin/np-tools.cjs lang-directive)
+RANGE="$*"
+if [[ "$RANGE" == "--repo" || "$RANGE" == "--all" ]]; then
+  SCOPE_MODE="repo"
+  FILES=$(git ls-files)
+  SCOPE_DESC="whole repository (tracked files)"
+  if [[ -z "$FILES" ]]; then
+    echo "No tracked files in scope ($SCOPE_DESC). Nothing to review."
+    exit 0
+  fi
+elif [[ -n "$RANGE" ]]; then
+  SCOPE_MODE="diff"
+  DIFF=$(git diff --no-color "$RANGE")
+  SCOPE_DESC="$RANGE"
+else
+  SCOPE_MODE="diff"
+  DIFF=$(git diff --no-color HEAD)
+  SCOPE_DESC="working tree + staged vs HEAD"
+fi
+if [[ "$SCOPE_MODE" == "diff" && -z "$DIFF" ]]; then
+  echo "No changes in scope ($SCOPE_DESC). Nothing to review."
+  exit 0
+fi
+```
+
+Capture is read-only — neither `git diff` nor `git ls-files` stages, edits, or commits anything. There are two scope modes:
+
+- **diff** (default) — a range (`HEAD~5..HEAD`, a branch name, `--staged`, …) is passed through verbatim; with no argument the scope is uncommitted + staged work against `HEAD`. This is the "review what just changed" mode.
+- **repo** (`--repo` / `--all`) — audits the whole tracked tree, not just a diff. `git ls-files` hands the agent the file roster; the agent walks the existing source for standing over-engineering (single-use abstractions, hand-rolled stdlib, duplicated native features, condensable logic) that predates any one change. Slower and noisier than diff mode — use it for a periodic cleanup pass, not every review.
+
+**Language (SSOT = `.nubos-pilot/config.json` → `response_language`).** `$LANG_DIRECTIVE` is authoritative for the report's prose and the final summary line. Finding lines (`<file>:L<line>: <tag> …`), file paths, and code snippets stay canonical. Supersedes CLAUDE.md.
+
+## Review
+
+Spawn ONE read-only reviewer — `Agent(subagent_type="np-simplifier", prompt=<…>)`, sonnet by default. The prompt MUST carry:
+
+- `<files_to_read>` listing `agents/np-critic-economy.md` (the canonical rubric — ladder, categories, severity bar, safety boundaries), plus `.nubos-pilot/codebase/INDEX.md` and `.nubos-pilot/RULES.md` when present (stdlib / native-feature / existing-helper context).
+- The review scope, by mode:
+  - **diff mode** — pass the captured `$DIFF` as the scope; the agent reviews only the changed hunks.
+  - **repo mode** — pass `$SCOPE_DESC` plus the `$FILES` roster from `git ls-files`, and instruct the agent to walk the tracked source itself (`Read`/`Grep`/`Glob`) under the same rubric. The agent should skip vendored, generated, and lock files and prioritise the largest hand-written modules. Because there is no diff, findings cite the source line as `<file>:L<line>` from the file it read.
+- `$SCOPE_MODE` and `$SCOPE_DESC` so the agent knows whether it is auditing a change set or the standing codebase.
+- `$LANG_DIRECTIVE` so the prose follows the project language.
+
+The agent is READ-ONLY (`tools: Read, Bash, Grep, Glob` — no Write/Edit). It returns a plain-text report: one line per finding in the shape `<file>:L<line>: <tag> <what>. <replacement>.` (tags `delete:` / `stdlib:` / `native:` / `shrink:`), ending with `net: -<N> lines possible.` or `Lean already. Ship.`
+
+## Report
+
+Print the agent's report verbatim to the user. Do not edit files, do not stage, do not commit — this command only catalogues. Close with the next-step hint:
+
+```
+Reductions are suggestions, not applied. To act on them: edit by hand, or run
+/np:execute-phase with agents.economy set to full (or ultra) so the Economy critic
+enforces the same bar inside the adversarial loop.
+```
+
+## Scope Guardrail
+
+<scope_guardrail>
+**Do:**
+- Capture the scope read-only — `git diff` in diff mode, `git ls-files` in `--repo` mode (no staging, no `-w` rewrites, no commit).
+- Spawn exactly one `np-simplifier` agent; pass it `agents/np-critic-economy.md` as the rubric so the manual command and the in-loop critic never diverge.
+- Print the report verbatim; respect `$LANG_DIRECTIVE` for prose only.
+
+**Don't:**
+- Edit, stage, or commit anything — this is a read-only audit. No `git add`, no `commit`, no `Write`/`Edit` of source.
+- Flag tests, input validation, error handling, security/access-control, or required edge cases as removable (the rubric's safety boundaries; completeness wins over economy).
+- Emit low-confidence "could be cleaner" noise — high-confidence, concrete replacements only.
+</scope_guardrail>
+
+## Output
+
+- A plain-text economy report to the user (findings + `net: -<N> lines possible.` or `Lean already. Ship.`).
+- No filesystem changes, no commits, no state mutation — read-only by contract.
+
+## Definition of Done
+
+This workflow audits a diff for economy and reports. The Definition of Done, per [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md):
+
+- Rule 3 (Do it with tests) — the report NEVER proposes deleting or weakening test code; coverage is completeness, not bloat.
+- Rule 5 (Aim to genuinely impress) — every finding cites file, line, the exact construct, and a concrete replacement; no vague "could be simpler" entries.
+- Rule 8 (Never present a workaround when the real fix exists) — reductions favour the root-cause-simple form over obscure golfed one-liners.
+
+Any violation = the review is incomplete; surface it and exit non-zero. The orchestrator does not relax these.
+
+## Related Workflows
+
+- **`/np:verify-work <N>`** — correctness/acceptance verification (the orthogonal axis; economy never judges correctness).
+- **`/np:execute-phase`** — runs the Economy critic in-loop when `agents.economy` is `full` or `ultra`, enforcing this exact rubric during execution.