nubos-pilot 0.1.0

package/docs/adr/0005-three-orthogonal-file-trees.md

@@ -0,0 +1,98 @@
+# ADR-0005: Three Orthogonal File-Trees
+
+* Status: Accepted
+* Date: 2026-04-14
+* Supersedes: None
+
+## Context and Problem Statement
+
+Three distinct concerns have historically been conflated in similar tools:
+
+1. **What we (nubos-pilot contributors) author and commit** — the source repository.
+2. **What we ship to end users via `npx nubos-pilot init`** — the install payload landing at the user's `.claude/nubos-pilot/`.
+3. **What an end user's project accumulates** as they plan and execute with nubos-pilot — STATE.md, ROADMAP.md, phase directories, todos, checkpoints, metrics.
+
+Mixing these three concerns produces two well-known failure modes:
+
+* **Install bit-rot** — the "copy-paste N blocks to remove stale X" problem. When installer files and state files live in the same tree, "clean install" and "clean state" cannot be distinguished.
+* **Contributor confusion** — authors cannot tell, for a given file, whether they are editing something that ships to users, something that only contributors see, or something users will mutate at runtime.
+
+The question: how are these three concerns physically separated?
+
+## Decision Drivers
+
+* **Install correctness** — Phase 7's manifest-based installer (INST-01) needs a distinct payload subtree to manifest against. Mixing it with source code or project state makes the manifest incoherent.
+* **Contributor clarity** — every file answers unambiguously: "do I edit this, does it ship, or does a user's project produce it?"
+* **Removability** — end-user uninstall (INST-08, stale-install cleanup) must be able to operate on one well-defined tree without sweeping scattered files.
+* **Avoiding bit-rot** — stale-install cleanup only works deterministically if payload boundaries are defined precisely enough to diff-check on reinstall.
+
+## Considered Options
+
+* **Three orthogonal file-trees** — Source tree / Install-Payload tree / Project-State tree, defined below. (CHOSEN)
+* **Single tree with everything intermixed** — installer files, source files, and state files cohabiting in one location.
+* **Two trees** — either merge Install-Payload into Source (ship the source tree directly), or merge Project-State into Install-Payload (state alongside installed tooling).
+
+## Decision Outcome
+
+Chosen: **"Three orthogonal file-trees"**. The three trees are enumerated in prose below; each tree has a distinct owner, lifecycle, and runtime location. This ADR asserts the boundary as a TEXT INVARIANT only — it does NOT create any of the trees beyond what Phase 1 authors (i.e. only the Source tree's `docs/adr/` subdirectory is materialized by this phase; see the scope disclaimer).
+
+### The Three Trees
+
+1. **Source tree** — what lives inside the nubos-pilot git repository (this monorepo subdirectory at `tools/nubos-pilot/`). **Owned by** contributors. **Lifecycle:** normal git. **Contains** (over time, as phases complete): a `bin/` subdir for the installer and the CLI helper, a `docs/` subdir (including `docs/adr/` authored now), a staging subdirectory whose contents become the install-payload after `npx nubos-pilot init` runs, a `.planning/` subdir with authoring-time planning artifacts (nubos-pilot's own ROADMAP / STATE / PLAN files), `CLAUDE.md`, `package.json`, and related author-facing artifacts. Committed.
+
+2. **Install-Payload tree** — the subset of the Source tree that is copied onto an end user's machine when they run `npx nubos-pilot init`. **Owned by** the end user after install, but **managed** by the installer via a manifest. **Lifecycle:** overwritten on `npx nubos-pilot` reinstall; cleaned up via `np:doctor --fix` against the manifest (Phase 7, INST-01 / INST-05 / INST-08). **Runtime location** on the end user's machine: `.claude/nubos-pilot/` for Claude Code (primary), or `.agents/nubos-pilot/` for other runtimes (Codex/Gemini/OpenCode — forward-reference Phase 8). **Not materialized in this phase** — scaffolded in Phase 7 (INST-01 manifest install).
+
+3. **Project-State tree** — state that end users' projects accumulate as they plan and execute: `STATE.md`, `ROADMAP.md`, `phases/<NN>-<slug>/` directories, `todos/pending/`, `backlog/`, `checkpoints/`, `metrics/`. **Owned by** the end user's project. **Lifecycle:** mutated only through nubos-pilot workflows under a single-writer lock (Phase 2, LIB-02). **Runtime location** on the end user's machine: `.nubos-pilot/`. **Not materialized in this phase** — scaffolded starting Phase 4 (base workflows + state schemas).
+
+### Orthogonality Rule
+
+**No file lives in two trees simultaneously at runtime.** A file is either source (in the contributor's repo), or payload (at the end user's install location), or state (in the end user's project) — **never two at once**. Workflow commands operate on exactly one tree per invocation; a single commit touches files in one tree at a time (see [ADR-0004](0004-atomic-commit-per-unit.md)).
+
+### Source-vs-Install-Payload Overlap Nuance
+
+The install-payload content ORIGINATES in the Source tree — it is authored by contributors in a staging subdirectory of the repo (e.g. `tools/nubos-pilot/nubos-pilot/…` as a suggested staging layout, finalized in Phase 7). **At install time**, the installer copies those files into a distinct tree at the end user's `.claude/nubos-pilot/` — a different filesystem location entirely. "Orthogonality" applies to **runtime locations** (what exists where when things are running), not to pre-install staging. Authoring in the Source tree is how Install-Payload files come to exist; they become the Install-Payload tree only after `npx nubos-pilot init` has run on the end user's machine. On the contributor's machine, only the Source tree is populated; on the end user's machine, only the Install-Payload and Project-State trees are populated (plus a snapshot of the payload staging subtree if the user also clones the repo, which is an unusual contributor-mode case).
+
+### Scope Disclaimer for Phase 1
+
+**Phase 1 materializes ONLY the Source tree** — specifically, `docs/adr/` and this ADR itself. Install-Payload and Project-State directories are **deferred**: the Install-Payload tree is scaffolded in Phase 7 (INST-01 manifest install), and the Project-State tree is scaffolded starting Phase 4 (base workflows + state schemas). **No `.gitkeep`, no empty staging directories, no skeleton subtrees are created in Phase 1.** This disclaimer is mandatory per CONTEXT.md D-09 and RESEARCH.md Pitfall 3.
+
+### Consequences
+
+* Good, because Phase 7 installer (INST-01) has a well-defined source-of-truth for manifest generation — the payload staging subtree inside the repo maps 1:1 to the installed content.
+* Good, because uninstall and stale-cleanup (INST-05, INST-08) are mechanical — operate on the Install-Payload tree only; Project-State is never touched.
+* Good, because `git log` on the nubos-pilot repo contains contributor work only — never end-user state churn (which lives on the user's machine, not in our repo).
+* Good, because users can delete `.nubos-pilot/` to reset their state without disturbing the installed tool, or delete `.claude/nubos-pilot/` to uninstall without losing their plans.
+* Bad, because contributors must remember the staging-subtree-vs-installed-payload distinction — mitigated by this ADR being linked from `bin/install.js` and CLAUDE.md once those artifacts exist in later phases.
+* Neutral, because project-state schema evolves across Phases 2–4 — ADR-0005 is agnostic to the schema, only asserts the tree boundary.
+
+## Pros and Cons of the Options
+
+### Three orthogonal file-trees — chosen
+
+* Good, because it maps cleanly to the three distinct owners (contributor / installed-tool / user-project) without overlap.
+* Good, because each tree has a single, well-defined lifecycle operation (git-commit / npx-reinstall / workflow-mutate).
+* Good, because it makes Phase 7's manifest-based installer (INST-01) implementable without heuristic boundaries.
+* Bad, because contributors must mentally track the staging-vs-installed distinction — the ONE piece of nuance this model requires.
+
+### Single tree with everything intermixed — rejected
+
+* Good, because it is "simpler" in the sense of having fewer rules.
+* Bad, because it reproduces the "copy-paste N blocks to remove stale X" bit-rot pattern — stale install files cannot be distinguished from stale state files when they cohabit.
+* Bad, because a user who wants to reset state deletes things that look like state but may be installed-tooling, or vice versa.
+* Bad, because manifest-based install becomes undecidable — the installer cannot tell a file it shipped from a file the user created.
+
+### Two trees (merge source+payload, or payload+state) — rejected
+
+* Good, because it reduces the tree count, superficially simpler.
+* Bad — **merge source+payload:** ships contributor-only artifacts (planning docs, ADRs, internal notes) to end users, bloating installs and leaking internal state.
+* Bad — **merge payload+state:** reintroduces the bit-rot failure mode exactly. A user's state lives alongside installed tooling; reinstall must then distinguish "state I should keep" from "tooling I should overwrite" — the very problem we're avoiding.
+* Bad, because every 2-tree variant reintroduces one of the two failure modes the 3-tree split is designed to eliminate.
+
+## More Information
+
+* **Related ADR:** [ADR-0002](0002-zero-runtime-dependencies.md) — the Install-Payload tree contains only `.cjs` + markdown; no `node_modules/` subtree ever lives inside it.
+* **Related ADR:** [ADR-0004](0004-atomic-commit-per-unit.md) — commits touch files in a single tree at a time (almost always the Source tree; end-user commits on their own repos are their business and out of nubos-pilot's scope).
+* **REQUIREMENTS.md:** §"Install" → INST-01 (manifest-based install — Install-Payload tree is the consumer), INST-05 (`np:doctor` — Install-Payload tree), INST-08 (stale-install auto-cleanup — Install-Payload tree).
+* **CLAUDE.md:** §"Technology Stack" → "Installation" — confirms the end-user install path `.claude/nubos-pilot/`.
+* **CONTEXT.md:** D-09 — only `docs/adr/` is materialized in Phase 1; other trees are text invariant only.
+* **RESEARCH.md:** Pitfall 3 — do NOT create Install-Payload or Project-State directories in this phase.

package/docs/adr/0006-yaml-dependency-amendment.md

@@ -0,0 +1,60 @@
+# ADR-0006: Accept yaml@^2.8 as First Runtime Dependency (Amendment to ADR-0002)
+
+* Status: Accepted
+* Date: 2026-04-15
+* Supersedes: None
+* Amends: [ADR-0002](0002-zero-runtime-dependencies.md)
+
+## Context and Problem Statement
+
+Phase 4 introduces `.nubos-pilot/roadmap.yaml` as the canonical source-of-truth for roadmap data (Phase-4 D-16..D-20). The schema contains nested sequences, mixed scalar types, and per-phase `plans` sub-objects that go well beyond what a hand-rolled regex parser can robustly handle. `lib/frontmatter.cjs` (the hand-rolled parser) already hits its design ceiling on Task-Frontmatter multiline sequences — extending it further to parse the full roadmap YAML would reimplement a real YAML 1.2 parser in-repo, which is strictly worse than vendoring a 50KB battle-tested library.
+
+ADR-0002 §"Escape hatch for future exceptions" explicitly foresees this: "if a concrete future feature genuinely requires a runtime dep that builtins cannot satisfy, the exception is introduced by a new ADR […] that either supersedes ADR-0002 wholesale or amends it narrowly with a name-scoped exemption." This ADR is the first exercise of that escape hatch.
+
+## Scope
+
+* This amendment permits **EXACTLY ONE** additional runtime dependency: `yaml@^2.8`.
+* `package.json.dependencies` is limited to `{"yaml": "^2.8.0"}` — no other key permitted.
+* **No further runtime deps** may be added without a new ADR amendment that either supersedes ADR-0002 again, or amends it with a second narrowly-scoped exemption. The bureaucratic step is deliberate — the escape hatch is load-bearing on the "just add a dep" reflex never becoming the default answer.
+* `devDependencies` remain unconstrained by this amendment (same as ADR-0002 §Scope).
+
+## Decision Drivers
+
+* **Concrete need** — Phase-4 D-16..D-20 ship `roadmap.yaml` with nested sequences (milestones → phases → plans) that the hand-rolled regex parser cannot express.
+* **Pre-sanctioned by CLAUDE.md** — the project's tech-stack document explicitly identifies `yaml@^2.8` as the acceptable escape-hatch dependency under "Supporting Libraries" / "When to Use Alternative".
+* **Install-footprint minimal** — `yaml@^2.8` has zero transitive dependencies and ships ~50KB of JS. This does not re-open the dep-tree floodgate ADR-0002 guards against.
+* **Type safety** — `YAML.parse` yields typed scalars (number, string, boolean, null, arrays of same) — no ad-hoc type coercion needed in callers.
+* **Round-trip support** — `yaml@^2.8` supports CST-preserving `YAML.parseDocument` for future phases that need to edit YAML while preserving comments.
+
+## Considered Options
+
+* **Option A — Keep regex parser, extend it to handle nested sequences.** Reject: every step along this road lands in a hand-rolled YAML 1.2 implementation. `lib/frontmatter.cjs` already has edge-cases around stack-demotion and inline vs block arrays; adding plans-objects-inside-phases-inside-milestones is not tenable.
+* **Option B — Write a minimal purpose-built YAML subset parser.** Reject: the effort to correctly support nested sequences + mixed-scalar-types exceeds the install-surface cost of vendoring `yaml@^2.8`. Writing a new parser is also a test-surface multiplier (we'd need the fuzz-corpus `yaml@^2.8` already passes).
+* **Option C — Accept `yaml@^2.8` as the first and only additional runtime dependency.** Chosen: demonstrable concrete need, pre-sanctioned, zero transitive deps, narrow scope preserves ADR-0002's spirit.
+* **Option D — Move the roadmap source-of-truth back to Markdown.** Reject: Phase-4 D-16..D-20 lock roadmap.yaml as source-of-truth specifically because Markdown cannot express the structured plan-object data the downstream renderer/workflows need.
+
+## Decision Outcome
+
+Chosen: **Option C — accept `yaml@^2.8` as the first runtime dependency**, because the concrete need is documented in Phase-4 decisions D-16..D-20, CLAUDE.md pre-sanctions this specific dep, and the narrow name-scoped amendment preserves ADR-0002's forcing function against "just add a dep" drift.
+
+**Audit rule:** Any PR that adds a key to `package.json.dependencies` beyond `yaml` MUST be blocked unless it ships with a new ADR amendment that supersedes this one or adds a second narrowly-scoped exemption. Phase 1's CI-gate enforcement note (ADR-0002 closing paragraph) applies here verbatim — human PR review is the current enforcement, CI-gate is deferred to a later phase.
+
+### Consequences
+
+* Good, because roadmap.yaml parsing is now robust across nested sequences and YAML 1.2's full scalar type system.
+* Good, because future phases that need structured YAML (e.g. Phase 5 plan-diff, Phase 9 model-profile config) can reuse `yaml@^2.8` without another amendment.
+* Good, because the install-footprint remains effectively flat — `yaml@^2.8` has zero transitive dependencies (confirm with `npm ls --all`).
+* Bad, because `npx nubos-pilot` now performs one actual download at install time on a fresh machine. ADR-0002's "zero-deps ≈ zero failure modes" property is slightly weakened — but only by the thinnest possible amount.
+* Bad, because the escape-hatch is no longer purely theoretical — future PR authors have a concrete precedent to cite. Mitigation: the Scope clause pins this to EXACTLY ONE dep, and the audit rule makes a second exemption equally bureaucratic.
+* Neutral, because Pattern S-1 (atomic write + file lock), S-2 (NubosPilotError envelope), S-5 (sandboxed tests), and S-6 (CJS module footer) remain unchanged — no workflow pattern changes with this amendment.
+
+## More Information
+
+* **Amended ADR:** [ADR-0002](0002-zero-runtime-dependencies.md) — this amendment exercises the escape hatch documented in §"Escape hatch for future exceptions" (line 37 of ADR-0002).
+* **CLAUDE.md:** §"Supporting Libraries" → row "yaml `^2.8.0`" pre-sanctions this dependency with the condition "Only adopt if a concrete workflow produces frontmatter that the hand-rolled regex parser can't handle (multiline arrays, anchors). Default answer is still 'no'." The Phase-4 roadmap.yaml schema satisfies that concrete-workflow condition.
+* **Phase-4 Context:** `.planning/phases/04-base-workflows-state-schemas/04-CONTEXT.md` D-16..D-20 (roadmap.yaml source-of-truth decisions).
+* **Upstream:** [`yaml` npm package](https://www.npmjs.com/package/yaml) — maintained by Eemeli Aro, version 2.x is YAML 1.2 compliant, zero transitive deps.
+
+---
+
+*This ADR does not describe CI enforcement. The dep-growth block (PR blocker on any new `dependencies` key beyond `yaml`) is deferred to a later deploy/CI phase per ROADMAP.md, identical to ADR-0002's deferral. Enforcement in the source-only phases is human PR review with this ADR as the authoritative reference.*

package/docs/adr/README.md

@@ -0,0 +1,27 @@
+# Architectural Decision Records
+
+This directory contains MADR-full ADRs that codify scope invariants of nubos-pilot. Each ADR is authoritative for the constraint it documents. Per CONTEXT.md D-07, decisions are superseded by new ADRs, never rewritten.
+
+## Index
+
+- [`0001-no-daemon-invariant.md`](0001-no-daemon-invariant.md) — No runtime daemon, no background process, no RPC multi-agents (FND-01)
+- [`0002-zero-runtime-dependencies.md`](0002-zero-runtime-dependencies.md) — `package.json` dependencies block stays empty (FND-02)
+- [`0003-max-six-unit-types.md`](0003-max-six-unit-types.md) — Milestone, Phase, Plan, Task, Todo, Backlog — no more (FND-03)
+- [`0004-atomic-commit-per-unit.md`](0004-atomic-commit-per-unit.md) — Every unit-completion = exactly one git commit (FND-04)
+- [`0005-three-orthogonal-file-trees.md`](0005-three-orthogonal-file-trees.md) — Source / Install-Payload / Project-State stay disjoint (FND-05)
+
+## Status Lifecycle
+
+Each ADR moves through three states:
+
+1. **Proposed** — authored but not yet accepted; subject to revision during review.
+2. **Accepted** — decision is binding; downstream work consumes the invariant as-is.
+3. **Deprecated** — superseded by a later ADR (referenced via `Supersedes NNNN`); retained for history.
+
+An ADR MAY enter directly as **Accepted** when it is ratified at authoring time (e.g. the FND-01…FND-05 ADRs in Phase 1, which encode invariants already agreed in CONTEXT.md). The `Proposed` state is reserved for ADRs whose decision is still open at commit time.
+
+ADRs are append-only. A superseded ADR is never rewritten — instead, a new ADR with a higher number references it via its `Supersedes` line.
+
+## Numbering
+
+ADRs follow the pattern `NNNN-kebab-title.md` with a zero-padded four-digit sequence starting at `0001`. Numbers are monotonically incremented — no skips, no re-use — so that cross-references (e.g. `ADR-0003`) stay stable across the project's lifetime.

package/docs/agent-frontmatter-schema.md

@@ -0,0 +1,84 @@
+# Agent Frontmatter Schema
+
+Canonical schema for every `agents/*.md` file shipped by nubos-pilot. Enforced by `lib/agents.cjs` at load time. Introduced in Phase 5 (CONTEXT decisions D-09..D-14).
+
+## Canonical Schema (D-09)
+
+```yaml
+---
+name: <string>              # required; MUST equal the filename stem
+description: <string>       # required; single-line summary
+tier: haiku|sonnet|opus     # required; see Tier Enum (D-11)
+tools: <comma-list string>  # required; e.g. "Read, Write, Bash, Grep"
+color: <string>             # optional; UI hint only
+---
+```
+
+Agent body follows the closing `---`. Body content is free-form markdown, consumed verbatim by the runtime when the agent is spawned.
+
+## Required Fields
+
+Every required field must be present with a truthy value. Missing or empty fields throw `NubosPilotError('agent-invalid-frontmatter', …)` with `details.field` set to the offender.
+
+| Field | Type | Validator Rule | Example |
+|-------|------|----------------|---------|
+| `name` | string | Must equal the filename stem (e.g. `planner.md` → `planner`). | `name: planner` |
+| `description` | string | Non-empty single-line summary; shown in `listAgents` UIs. | `description: Creates executable phase plans …` |
+| `tier` | enum string | Must be one of `haiku`, `sonnet`, `opus`. | `tier: opus` |
+| `tools` | comma-list string | Flat comma-separated list; parsed later by the runtime adapter. | `tools: Read, Write, Bash, Glob, Grep` |
+
+Order of checks inside `validateAgentFrontmatter`: REQUIRED → FORBIDDEN → TIER_ENUM → name-match. First failure throws; the remaining checks are short-circuited.
+
+## Forbidden Fields (D-10)
+
+Presence of any of these fields — even with a falsy value — throws `NubosPilotError('agent-forbidden-field', …)` with `details.field` and `details.hint`.
+
+| Field | Why forbidden | Hint returned |
+|-------|---------------|---------------|
+| `model` | Model routing is tier-based in nubos-pilot (D-12..D-14). A concrete model id bypasses the tier abstraction and breaks multi-runtime adapters (Phase 7/8). | `Use "tier" instead.` |
+| `model_profile` | Same reason as `model`: profile-based selection is an out-of-band concern; `tier` is the single source of truth. | `Use "tier" instead.` |
+| `hooks` | Runtime-specific syntax (Claude Code ≠ Codex ≠ Gemini). Hooks live in the runtime-adapter layer introduced in Phase 7/8; they are NOT part of the portable agent contract. | `hooks are runtime-specific and deferred to Phase 7/8.` |
+
+Rationale: the FORBIDDEN list is what makes D-09/D-10 testable. Every agent file that slips a forbidden field in gets rejected at load time before the runtime adapter ever sees it.
+
+## Tier Enum (D-11)
+
+`TIER_ENUM = ['haiku', 'sonnet', 'opus']`. Any other value throws `NubosPilotError('agent-invalid-tier', …)` with `details.value` (the offending input) and `details.allowed` (the canonical enum).
+
+Pre-classified assignments (D-13, locked in ROADMAP SC-4):
+
+| Agent | Tier | Rationale |
+|-------|------|-----------|
+| `planner` | `opus` | Goal-backward decomposition, dependency-graph reasoning, decision-fidelity checks — deepest model. |
+| `plan-checker` | `opus` | Adversarial validator for planner output; equivalent reasoning depth required. |
+| `researcher` | `sonnet` | Web/MCP fetch + synthesis; wider context tolerance, lighter reasoning load. |
+
+No mid-run tier re-selection (D-14). `loadAgent()` re-reads the file on every call — never cached — so edits to the markdown are picked up immediately but cannot be tampered with at runtime.
+
+## Plan-Checker Finding Categories (starting set)
+
+Canonical identifiers for findings that `agents/np-plan-checker.md` emits. Starting set — extensible by the plan-checker agent as new failure modes are observed.
+
+- `missing-success-criterion` — a ROADMAP SC-X is not mapped to any task.
+- `non-atomic-task` — a task bundles multiple distinct deliverables that should be split.
+- `unbounded-scope` — `<action>` uses words like "etc.", "and related", "as needed" without concrete enumeration.
+- `broken-dependency` — `depends_on` references a plan or task that does not exist.
+- `cyclic-dependency` — the wave-graph computation detects a cycle.
+- `fake-promotion-trigger` — plan claims a `tasks/` promotion trigger (parallelism / mixed-tiers / non-linear-deps) that its own task list does not substantiate (D-18..D-20).
+- `missing-coverage-annotation` — a task modifies production code without a `tdd="true"` task or a `<verify><automated>` command (Nyquist rule).
+- `bare-askuser-call` — workflow MD emits `AskUserQuestion` directly instead of `node np-tools.cjs askuser --json '{…}'` (D-04).
+- `hook-field-present` — agent frontmatter contains `hooks:` (D-10).
+- `forbidden-agent-field` — agent frontmatter contains `model:` or `model_profile:` (D-10).
+
+Each finding returned by plan-checker carries one of these codes plus an anchor `{file, line}` pair so the planner's revise-mode can address them without re-deriving context.
+
+## Validation Flow
+
+`validateAgentFrontmatter(fm, agentName)` runs four gates in strict order, throwing the first violation and skipping the rest:
+
+1. **REQUIRED** — every field in `REQUIRED = ['name', 'description', 'tier', 'tools']` must be truthy; otherwise `agent-invalid-frontmatter` with `details.field`.
+2. **FORBIDDEN** — no field in `FORBIDDEN = ['model', 'model_profile', 'hooks']` may be defined; otherwise `agent-forbidden-field` with `details.field` and `details.hint`.
+3. **TIER_ENUM** — `fm.tier` must be in `TIER_ENUM = ['haiku', 'sonnet', 'opus']`; otherwise `agent-invalid-tier` with `details.value` and `details.allowed`.
+4. **Name match** — `fm.name` must equal the `agentName` passed in (which `loadAgent` derives from the filename stem); otherwise `agent-invalid-frontmatter` with `details.field === 'name'`, `details.expected`, `details.got`.
+
+All error codes are stable identifiers; callers (workflows, plan-checker, test suites) match on `err.code` verbatim rather than on message strings.

package/docs/phase-artifact-schemas.md

@@ -0,0 +1,292 @@
+# Phase Artifact Schemas
+
+Phase-5 defines the canonical on-disk format of the 5 planning artifacts.
+Downstream phases (Phase 6 executor, Phase 10 review commands) parse against
+these schemas. Breaking changes require a Phase-5 amendment or a new phase.
+
+All artifacts live under `.nubos-pilot/phases/<padded>-<slug>/` — e.g.
+`.nubos-pilot/phases/05-planning-workflows-agents/05-CONTEXT.md`.
+
+| Artifact           | Producer                     | Consumer(s)                              | Lifecycle       |
+| ------------------ | ---------------------------- | ---------------------------------------- | --------------- |
+| `CONTEXT.md`       | `/np:discuss-phase`          | researcher, planner, plan-checker        | rewrite on save |
+| `RESEARCH.md`      | `/np:research-phase`         | planner, plan-checker                    | rewrite on save |
+| `PLAN.md`          | `/np:plan-phase` planner     | plan-checker, executor, verifier         | rewrite on save |
+| `PLAN-REVIEW.md`   | `/np:plan-phase` loop        | user, np:undo, Phase 10 review           | append-only     |
+| `QUESTIONS.json`   | `/np:discuss-phase-power`    | power-mode UI, discuss-phase finalize    | rewrite on save |
+
+## CONTEXT.md
+
+Captures user decisions from the adaptive interview. Read by every downstream
+agent. Structure:
+
+```markdown
+---
+phase: "<phase-number>"
+padded: "<padded>"
+phase_name: "<human-readable>"
+mode: adaptive | assumptions | power
+finalized: <ISO-8601>
+---
+
+# <Phase Name> — Context
+
+<domain>
+One-paragraph framing: what user domain is this phase serving?
+</domain>
+
+<decisions>
+**D-01:** First locked decision (short imperative)
+- Rationale: …
+- Constraints: …
+
+**D-02:** Next decision …
+</decisions>
+
+<canonical_refs>
+- path/to/file.ts (why it matters)
+- https://… (spec or vendor doc)
+</canonical_refs>
+
+<code_context>
+- `lib/foo.cjs` — current behavior, what we keep, what we replace
+</code_context>
+
+<specifics>
+- Concrete inputs/outputs the user insisted on
+</specifics>
+
+<deferred>
+- Items explicitly parked for a later phase
+</deferred>
+```
+
+**Required tag blocks:** `<domain>`, `<decisions>`, `<canonical_refs>`,
+`<code_context>`, `<specifics>`, `<deferred>`. Tag blocks may be empty but
+must be present — downstream agents assume the structure.
+
+**Placeholders** in `templates/CONTEXT.md` (Plan 05-06) use `{{ snake_case }}`;
+`lib/template.cjs` fails loud on unknown keys.
+
+## RESEARCH.md
+
+Stack, patterns, pitfalls, security domain, open questions. Produced by
+`agents/np-researcher.md` (tier=sonnet). High-level H2 sections — in this order:
+
+```markdown
+## Summary
+## Standard Stack
+## Architecture Patterns
+## Don't Hand-Roll
+## Pitfalls
+## Security Domain
+## Validation Architecture
+## Assumptions Log
+## Open Questions
+## Environment Availability
+## Research Coverage
+## Sources
+```
+
+`## Research Coverage` is **mandatory in offline mode** (no WebFetch/MCP) — it
+lists which areas were covered from local knowledge only so the planner can
+flag gaps. In online mode the section may be empty but the header must be
+present.
+
+Each source line in `## Sources` uses:
+
+```
+- <absolute path or URL> — <one-line relevance note> — <HIGH|MEDIUM|LOW>
+```
+
+## PLAN.md
+
+The executor's prompt. YAML frontmatter + body. One PLAN.md per `NN-NN-PLAN.md`
+(phase-scoped — the plan number is the second NN). Produced by
+`agents/np-planner.md` (tier=opus), verified by `agents/np-plan-checker.md` (opus).
+
+### Required frontmatter keys
+
+```yaml
+---
+phase: "<phase-number>"            # string, e.g. "5"
+plan: "<phase>-<plan>"             # e.g. "05-01"
+plan_id: "<phase>-<plan>"          # stable ID — equal to `plan`
+wave: <integer>                    # 1..N — planner-assigned execution wave
+depends_on: [<plan_id>, …]         # inter-plan dependencies
+files_modified: [<relative-path>]  # every path this plan will touch
+autonomous: true | false           # true = no human gate needed mid-execution
+requirements: [<REQ-ID>]           # roadmap requirement IDs this plan covers
+must_haves:                        # goal-backward truths + artifacts + links
+  truths: [string, …]
+  artifacts: [{ path, provides }]
+  key_links: [{ from, to, via, pattern }]
+---
+```
+
+### Required body sections
+
+```markdown
+<objective>
+Single-paragraph statement of intent.
+</objective>
+
+<context>
+@<path>            # embed CONTEXT.md, RESEARCH.md, sibling plans, libs
+<interfaces>
+Shape descriptions of APIs this plan touches.
+</interfaces>
+</context>
+
+<tasks>
+<task type="auto" tdd="true|false">
+  <name>Task N: …</name>
+  <files>…</files>
+  <read_first>…</read_first>
+  <behavior>…</behavior>
+  <action>…</action>
+  <verify><automated>…</automated></verify>
+  <acceptance_criteria>…</acceptance_criteria>
+  <done>…</done>
+</task>
+</tasks>
+
+<threat_model>
+| Threat ID | Category | Component | Disposition | Mitigation |
+</threat_model>
+
+<verification>
+- Shell command(s) the executor runs after the plan completes.
+</verification>
+
+<success_criteria>
+- Boolean predicates that must hold after execution.
+</success_criteria>
+
+<output>
+Path of the SUMMARY.md that the executor writes.
+</output>
+```
+
+### Optional sections
+
+- `## Task Promotion` — emitted when Plan 05-04's `shouldPromoteToTasks`
+  returns `promote: true`. Lists the triggers (`parallelism`, `mixed-tiers`,
+  `non-linear-deps`) and the rationale. The presence of this section tells
+  the plan-phase workflow to scaffold `tasks/`. See D-18..D-20.
+
+## PLAN-REVIEW.md
+
+**Append-only** audit trail of the plan-checker verification loop. One file
+per phase (not per plan). Created by `plan-review-append` verb (Plan 05-10
+Task 1). Never truncated, even on abort (D-16, D-17).
+
+Format:
+
+```markdown
+# PLAN-REVIEW.md — Phase <N> (<Phase Name>)
+
+Append-only audit trail of plan-checker iterations. Never truncate.
+
+## Iteration 1 - 2026-04-15T14:22:13.412Z
+
+**Planner output:** PLAN.md committed at <sha or 'pending'>
+**Checker verdict:** issues_found
+**Findings:**
+
+```yaml
+status: issues_found
+findings:
+  - category: missing-success-criterion
+    severity: critical
+    target: "PLAN.md §SC-3"
+    message: "No task addresses SC-3."
+```
+
+**Planner response:** revision
+
+## Iteration 2 - 2026-04-15T14:24:41.988Z
+
+**Planner output:** PLAN.md committed at <sha>
+**Checker verdict:** passed
+**Findings:**
+
+```yaml
+status: passed
+findings: []
+```
+
+**Planner response:** done
+```
+
+Invariants:
+
+- Every iteration section begins with `## Iteration <N> - <ISO_TIMESTAMP>`.
+- The YAML verdict block is fenced with `yaml` language tag (Plan 05-10
+  Open Question 4 resolution).
+- Byte-level append-only — pre-existing bytes are a sha256-verified prefix
+  of post-append bytes.
+- Survives `plan-phase-abort` (Plan 05-10 Task 1) — abort deletes PLAN.md and
+  `tasks/` but never touches PLAN-REVIEW.md.
+
+## QUESTIONS.json
+
+Power-mode state file. Produced by `discuss-phase-power` (Plan 05-08).
+Single source of truth while power-mode is in progress; CONTEXT.md is a
+derived artifact written only on `finalize` (Pitfall 1 guard).
+
+```json
+{
+  "phase": "5",
+  "padded": "05",
+  "mode": "power",
+  "created": "2026-04-15T10:00:00.000Z",
+  "questions": [
+    {
+      "id": "Q-01",
+      "area": "decisions",
+      "question": "Should we gate the /np:plan-phase dispatcher …?",
+      "answer": "Yes, use the registry pattern.",
+      "explain": "Matches the registry invariant established in Phase 4 D-21."
+    }
+  ],
+  "answers_status": "pending"
+}
+```
+
+Schema:
+
+| Key               | Type      | Notes                                        |
+| ----------------- | --------- | -------------------------------------------- |
+| `phase`           | string    | Phase number (matches CONTEXT.md frontmatter) |
+| `padded`          | string    | Two-digit padded number                      |
+| `mode`            | string    | Always `"power"` here                        |
+| `created`         | string    | ISO-8601 creation timestamp                  |
+| `questions`       | array     | Ordered list of question objects             |
+| `answers_status`  | string    | `pending` \| `finalized`                     |
+
+Question object:
+
+| Key        | Type                   | Notes                                                  |
+| ---------- | ---------------------- | ------------------------------------------------------ |
+| `id`       | string                 | `Q-NN` — stable ID                                     |
+| `area`     | enum                   | `domain` \| `decisions` \| `canonical_refs` \| `code_context` \| `specifics` \| `deferred` |
+| `question` | string                 | Question text (German or English depending on user)    |
+| `answer`   | string \| null         | `null` until the user fills it                         |
+| `explain`  | string \| null         | Optional rationale the user adds inline                |
+
+Lifecycle:
+
+- `discuss-phase-power` writes the file on first run and on `refresh`.
+- User edits the JSON directly in their editor.
+- On `finalize`: workflow reads JSON, flips `answers_status` to `finalized`,
+  renders CONTEXT.md, and writes both files atomically.
+- CONTEXT.md is **derived** — regenerating QUESTIONS.json always wins.
+
+Downstream consumers:
+
+- `discuss-phase-power` finalize step — only entry point that touches
+  CONTEXT.md from power mode.
+- Phase 6 `np:undo` — reads QUESTIONS.json to detect mid-interview state
+  and warn the user before rolling back.
+- Phase 10 review commands — may parse for audit-trail completeness.

package/docs/phase-directory-layout.md

@@ -0,0 +1,82 @@
+# Phase Directory Layout
+
+**Status:** Canonical — Phase-4 D-24 / D-25
+**Last updated:** 2026-04-15
+
+This document is the authoritative spec for what a `.planning/phases/<NN>-<slug>/`
+directory may contain, which files are parser-mandatory, which are produced by
+which workflow, and which are consumed by which agent.
+
+## Mandatory files
+
+These are the only files that `lib/phase.cjs` / `lib/plan.cjs` / `lib/tasks.cjs`
+read by contract. A phase directory is well-formed when each of its plans has a
+`PLAN.md` and (optionally) a `tasks/` subdirectory with one `.md` file per task.
+
+| File                   | Producer workflow           | Parser                  | Minimal required sections                                                             |
+| ---------------------- | --------------------------- | ----------------------- | ------------------------------------------------------------------------------------- |
+| `<NN>-<MM>-PLAN.md`    | `np:plan-phase`             | `lib/plan.cjs`          | Frontmatter: `phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves`; body: `<objective>`, `<tasks>` (may be empty if plan is single-task), `<success_criteria>` |
+| `tasks/<task-id>.md`   | `np:plan-phase`             | `lib/tasks.cjs`         | Frontmatter: full 12-field set per D-01 (`id, phase, plan, type, status, tier, owner, wave, depends_on, files_modified, autonomous, must_haves`); body: freeform task prose |
+
+Notes:
+- `tasks/` is **optional at the plan level**: a plan promotes to `tasks/*.md`
+  only when parallelism, mixed tiers, or non-linear dependencies demand it.
+  A single-task plan may keep its tasks inline inside `PLAN.md`.
+- Every other file in the phase directory is **workflow-produced / workflow-consumed only**.
+  Parsers never read them.
+
+## Optional files (workflow artifacts)
+
+The parser contract does not read these. Each is produced by a specific
+workflow and consumed by a specific downstream agent or workflow step. Missing
+files are never an error — they simply indicate that the corresponding workflow
+step did not run (or has not run yet).
+
+| File                              | Producer workflow            | Consumer agent(s) / workflow                        | Minimal required sections                                                                                                    |
+| --------------------------------- | ---------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `<NN>-CONTEXT.md`                 | `np:discuss-phase`           | planner, researcher, plan-checker                   | `<domain>`, `<decisions>`, `<constraints>`, `<dependencies>`, `<success_criteria>`                                           |
+| `<NN>-RESEARCH.md`                | `np:research-phase`          | planner, plan-checker                               | `<sources>` (at least one link with HIGH/MEDIUM/LOW credibility), `<findings>`, `<open_questions>`, `<flags>`                |
+| `<NN>-PATTERNS.md`                | `np:plan-phase` (pre-plan)   | planner, executor                                   | `File Classification` table, per-file `Analog` block, `Shared Patterns` (S-1..S-N) section                                   |
+| `<NN>-VALIDATION.md`              | `np:plan-phase` (pre-plan)   | planner, executor, verifier                         | `Validation Strategy`, `Must-Have Truths`, `Artifact Checks`, `Traceability Matrix`                                          |
+| `<NN>-<MM>-SUMMARY.md`            | `np:execute-plan`            | verifier, `np:progress`, `np:next`                  | Frontmatter: `phase, plan, subsystem, key-files, decisions, metrics`; body: `Objective`, `What Was Built`, `Key Decisions`, `Deviations`, `Self-Check` |
+| `<NN>-VERIFICATION.md`            | `np:verify-work`             | `np:next` (rule 4 gate), human reviewer             | `Scope`, `Evidence`, `Result` (pass/fail), `Follow-ups`. Presence flips `np:next` from rule-4 to rule-5 for the phase.       |
+| `<NN>-DISCUSSION-LOG.md`          | `np:discuss-phase`           | planner (carry-over), human reviewer                | Freeform Q&A transcript — no parser contract                                                                                 |
+| `<NN>-UI-SPEC.md`                 | `np:ui-phase`                | UI executor, reviewer                               | `Screens`, `Components`, `Interactions`, `Accessibility`, `Design-system references`                                         |
+| `<NN>-AI-SPEC.md`                 | `np:ai-integration-phase`    | AI executor, eval-reviewer                          | `Framework selector`, `Model profile`, `Prompt contracts`, `Eval strategy`, `Metrics`                                        |
+| `<NN>-REVIEW.md` / `REVIEW-FIX.md`| `np:review` / `np:code-review` | executor (follow-up), verifier                    | `Findings` table, `Severity`, `Remediation plan`                                                                             |
+| `<NN>-verify.sh`                  | `np:plan-phase` (optional)   | executor, verifier, CI                              | POSIX-sh script; exit 0 = pass, non-zero = fail. Each assertion uses `[ -f ... ]` / `grep -q ...` / `node --test ...` style  |
+
+## Parser contract
+
+`lib/phase.cjs` (`findPhaseDir`, `paddedPhase`, `slug`) navigates the directory
+tree by filename convention only. `lib/plan.cjs` (`parsePlan`, `listPlans`)
+reads `PLAN.md` files. `lib/tasks.cjs` (`loadTaskGraph`,
+`validateTaskFrontmatter`) reads `tasks/*.md` if the subdirectory exists.
+
+None of these parsers read any of the optional files listed above. Workflows
+that consume optional files do so by explicit path (e.g.
+`fs.readFileSync(path.join(phaseDir, '04-CONTEXT.md'), 'utf-8')`) with
+ENOENT-tolerance — a missing file is a non-error state meaning "that step
+hasn't been run".
+
+## Producer-workflow vs. consumer-agent separation
+
+Workflow commands (`np:*`) produce files; subagents (planner, researcher,
+executor, verifier, plan-checker) consume them. A well-formed phase directory
+reflects exactly which workflow steps have been completed, which is what
+`np:next` uses to compute the next actionable step (Phase-4 D-12..D-15 gate
+rules).
+
+## Relation to D-24 / D-25
+
+- **D-24:** Only `PLAN.md` and `tasks/` are parser-mandatory. Every other file
+  is workflow-produced and may be absent.
+- **D-25:** This file is the authoritative spec for the optional-file list.
+  When a new workflow is added (e.g. Phase 5's `np:research-phase`), it must
+  either produce one of the files listed above or extend this table.
+
+## References
+
+- Phase-4 `04-CONTEXT.md` §decisions D-24, D-25
+- Phase-3 `03-CONTEXT.md` §D-12..D-17 (task-frontmatter baseline)
+- `lib/plan.cjs`, `lib/tasks.cjs`, `lib/phase.cjs` — the only parsers that read this tree