docs: finalize ri-4-001 scratchpad with verification evidence (#1275 )

docs: ri-4-001 scratchpad for PRD authority card (#1275 )
test(mosaic): RI-N3 contract specs for prdy and mission --plan adapters (#1275 )
2026-08-17 16:48:39 -05:00 · 2026-08-17 16:46:17 -05:00 · 2026-08-17 16:46:14 -05:00 · 2026-08-17 16:46:06 -05:00 · 2026-08-17 16:46:00 -05:00
15 changed files with 1552 additions and 378 deletions
@@ -1368,38 +1368,3 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 10. ASSUMPTION: **Conversations and messages get their own PG tables** (not stored in brain's entity model). They follow a chat-specific schema with proper foreign keys to users and projects. Rationale: Chat has different access patterns (streaming, pagination, search) than brain entities.
 11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaicstack/agent — only configuration management.
 ---
 ## Release Integrity Workstream (RI, #1275)
 ### Problem and objective
 At `next` 476db12b (review of 2026-08-17), publication from `next` is not bound to the full verification pipeline for the same commit: the publish pipeline's publish steps depend on `build` only, while ordinary push CI excludes `next`. Public Forge/MACP paths contain false-success placeholders: a stub executor that reports `completed` with exit zero, planning/remediation gates that execute literal `true`, a review gate that echoes an approving verdict, and a gate runner that treats empty commands and unimplemented CI-provider gates as passing. Shipping UI surfaces can render a failed fetch as an empty, healthy collection.
 Objective: for alpha 0.0.50, the release cannot publish, report, or display work state that the repository has not actually verified. Decisions SDLC-D-033 through SDLC-D-038 (Jason, 2026-08-17) scope this floor; full decision text and required-behavior lists live in jarvis-brain `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` and `data/decisions/mosaic-stack-sdlc-protocol.json`. This section restates only the normative requirements.
 ### Normative requirements
 1. **RI-N1 Exact-commit publication verification (SDLC-D-034).** One canonical terminal verification command performs self-contained re-verification in the publish pipeline against the job's checked-out commit before any external publication effect. The command contains or invokes the complete mandatory verification set (semantic parity with the PR merge gate, including sanitization, upgrade-guard, typecheck, lint, format check, tests, and build); CI and publication do not maintain separate semantic checklists. Every publish step depends on the verification step in the executable pipeline DAG. Provider commit identity and `git rev-parse HEAD` must identify the same commit. Missing, skipped, cancelled, stale, or inconclusive checks fail closed. Documentation-only runs may skip publication but cannot bypass verification when a publication effect will occur. A negative control must prove that a broken check blocks every publish step.
 2. **RI-N2 Fail-closed Forge/MACP with explicit simulation (SDLC-D-035).** Simulation requires explicit caller intent (e.g. `--simulate`) and produces a distinct typed `simulated` state that can never satisfy dependencies, acceptance criteria, gates, merge, or release. Normal execution exits nonzero with a typed capability failure when a required executor, reviewer, command, or CI provider is absent — no stub completion, no literal-`true` gates, no synthetic approvals, no empty-command passes. A manual gate with no automation enters a waiting state; it does not pass. Positive tests prove explicit simulation still works; negative controls prove simulation and every missing-provider case cannot advance lifecycle state.
 3. **RI-N3 One transitional PRD authority (SDLC-D-036).** `@mosaicstack/prdy` structured storage under `docs/prdy/`, driven by `mosaic mission --plan`, is the authoritative PRD representation for the alpha. `mosaic prdy` either routes through the same application service or operates only as an explicit, named Markdown import/export adapter; `docs/PRD.md` is not a peer authority. `mission --plan` must persist the mission↔PRD linkage (mission id/version, PRD id/version, selected requirements). Markdown output is a generated view carrying source identity; editing it cannot mutate authority silently. Import is explicit, validated, and conflict-aware (proposed successor, never overwrite). Structural validity is separate from approval.
 4. **RI-N4 One quality-rails evaluator (SDLC-D-037).** The TypeScript quality-rails package is the sole authoritative evaluator. A complete probe inventory maps every current TypeScript and shell check to one canonical check with disposition (preserve/strengthen/retire, each named). Effective shell enforcement probes are absorbed before their independent paths retire; expected-file presence alone is not parity. The evaluator returns typed results (`passed`/`failed`/`blocked`/`error`/`not-applicable`) with check version, subject, and reason; missing implementation, missing input, unknown check, process error, timeout, or malformed output can never become `passed` or an unqualified skip. Check definitions and policy are versioned and digested. Shell commands become thin adapters with no separate verdict logic. The canonical terminal verification command (RI-N1) invokes this evaluator rather than duplicating its logic. Contract, parity, and negative-control tests are required, plus independent review of probe equivalence.
 5. **RI-N5 Consequence-aware stale UI (SDLC-D-038).** Mission Control distinguishes typed freshness states (`current`, `stale`, `partial`, `unknown`, `unavailable`) rather than inferring from empty arrays or null. A failed fetch never renders as an empty healthy collection. Last-known data may display for situational awareness only with source identity, version, and age visibly labeled; any derived completion/assurance/release verdict whose inputs are stale becomes `unknown`; all state-changing actions are disabled until fresh state loads and is revalidated. With no verified snapshot, surfaces show an explicit unavailable state. Cache corruption, cross-workspace data, schema mismatch, and version regression invalidate the snapshot. Tests cover the failure matrix (network, auth, malformed, partial, corruption, stale age, schema mismatch, recovery, stale-action rejection) with negative controls proving no case yields a current green verdict or enabled mutation.
 ### Acceptance criteria
 - AC-RI-1: A push to `next` that fails any mandatory verification step publishes nothing (no npm package, no image), demonstrated by a checked-in negative control and by pipeline evidence on a real `next` publish run where the verification step is green and every publish step depends on it.
 - AC-RI-2: With no executor/reviewer/CI provider wired, Forge and MACP normal runs exit nonzero with typed capability failures; with `--simulate`, runs complete but every result is typed `simulated` and cannot satisfy any gate, dependency, or completion state — proven by unit tests including negative controls.
 - AC-RI-3: A PRD created or revised through either `mosaic mission --plan` or `mosaic prdy` resolves to one authority under `docs/prdy/` with stable identities and versions; the mission↔PRD linkage survives restart; a Markdown export is labeled as generated and cannot silently become a second writer; divergent legacy content blocks baseline claims until explicitly resolved — proven by contract tests.
 - AC-RI-4: `quality-rails check` through any entry point (TS CLI, framework shell adapter) returns the same typed verdict for the same subject; the probe inventory names every legacy check's disposition; a deliberately broken probe fails closed — proven by contract/parity/negative-control tests and independent review of probe equivalence.
 - AC-RI-5: No shipping surface renders a failed fetch as an empty healthy state; stale/partial/unavailable states are typed, labeled, and mutation-disabled — proven by the failure-matrix tests.
 - AC-RI-6: All cards merged to `next` via squash PR with terminal-green CI; release evidence for 0.0.50 records commit, verification run, and published artifacts.
 ### Out of scope
 The canonical dispatcher/control-plane vertical slice (work graph, execution attempts, fenced leases, typed check-in, independent verifier dispatch) is decided post-alpha (SDLC-D-033, option B). Multi-pipeline verification certificates (SDLC-D-034 option B) are post-alpha. Full AF-1..AF-4 objective matrices and Mission Control portfolio surfaces are post-alpha.
@@ -1,42 +0,0 @@
 # Tasks — Release Integrity Workstream (RI-050, #1275)
 > Single-writer: the RI-050 orchestrator (jarvis, dragon-lin) only. Workers read but never modify.
 >
 > **Mission:** alpha 0.0.50 release-integrity floor (decisions SDLC-D-033..038).
 > **PRD:** [docs/PRD.md § Release Integrity Workstream](../PRD.md#release-integrity-workstream-ri-1275)
 > **Issue:** #1275 (remains open until RI-V-001 closes)
 > **Base branch:** `next` (all cards branch from `origin/next`, squash-merge via PR)
 >
 > **Execution note:** the `agent` column uses `pi-glm-5.3` — outside the pipeline-cron model
 > table on purpose. This workstream is executed by jarvis on dragon-lin with local pi workers
 > (`pi --model zai/glm-5.3:high`); pipeline crons must not auto-claim these rows.
 >
 > **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
 > `done` requires: repo quality gates green, independent review recorded, terminal-green CI on
 > the PR head, squash merge to `next`, and acceptance evidence in notes.
 | id       | status      | description                                                                                                                                                                                                                                                                      | issue | agent      | repo              | branch                            | depends_on                                                 | estimate | notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------- | ----------------- | --------------------------------- | ---------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | RI-0-001 | in-progress | Bootstrap: issue #1275, PRD section, this DAG, scratchpad (docs only)                                                                                                                                                                                                            | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-mission-bootstrap     | —                                                          | 6K       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-1-001 | in-progress | RI-N1: canonical terminal verification command + publish-pipeline exact-commit gate (every publish step depends on verify; commit identity check; fail closed)                                                                                                                   | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-publish-gate          | RI-0-001                                                   | 25K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-1-002 | not-started | RI-N1 negative control: checked-in tests proving a broken mandatory check blocks every publish step and that DAG edges cannot be bypassed                                                                                                                                        | #1275 | pi-glm-5.3 | mosaicstack/stack | test/ri-050-publish-gate-negative | RI-1-001                                                   | 12K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-2-001 | in-progress | RI-N2 (Forge): remove stub-executor false success; `--simulate` typed `simulated` results that satisfy nothing; literal-`true` gates and echo-review replaced with real gates or typed waiting-for-authority                                                                     | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-forge-fail-closed      | RI-0-001                                                   | 20K      | Independent review APPROVED 2026-08-17 (Gitea review 172 on PR #1278, head 99b8f6ea; reviewing seat fargo — recorded under shared host principal mos-dt-0, provenance correction posted by fred; wrapper gap filed by fred). Executed at head: forge tests 116/116, lint green, typecheck green after building macp dist (minimal-install artifact, not a defect), workspace typecheck 45/45, no external type consumers of the changed interfaces. CI red = known lane-wide fleet-test failure only, carries no information about this change (fred, log-content analysis, pipelines 2456-2458). Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare forge run/resume, which now fails closed — fast-follow docs touch. Merge queued behind #1270. |
 | RI-2-002 | in-progress | RI-N2 (MACP): gate runner fails closed on empty commands, stub executors, and unimplemented CI-provider gates unless explicit simulate; typed capability failures                                                                                                                | #1275 | pi-glm-5.3 | mosaicstack/stack | fix/ri-050-macp-fail-closed       | RI-0-001                                                   | 15K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-3-001 | not-started | RI-N4: complete probe inventory mapping every TS and shell quality-rail check to one canonical check with disposition (preserve/strengthen/retire, each named)                                                                                                                   | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-qr-probe-inventory    | RI-0-001                                                   | 12K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-3-002 | not-started | RI-N4: TS evaluator absorbs effective shell probes; typed results (passed/failed/blocked/error/not-applicable) with versioned digested check definitions; shell commands become thin adapters; contract/parity/negative-control tests                                            | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-qr-evaluator          | RI-3-001                                                   | 30K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-4-001 | in-progress | RI-N3: one PRD application service — `mission --plan` persists mission↔PRD linkage (ids/versions/selected requirements); `mosaic prdy` routes through the service or becomes a named import/export adapter; Markdown is a labeled generated view; explicit conflict-aware import | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-prd-authority         | RI-0-001                                                   | 35K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-5-001 | not-started | RI-N5: typed freshness states (current/stale/partial/unknown/unavailable); no failed-fetch-renders-empty; stale derived verdicts → unknown; mutations disabled when stale; failure-matrix tests                                                                                  | #1275 | pi-glm-5.3 | mosaicstack/stack | feat/ri-050-web-stale-safety      | RI-0-001                                                   | 25K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | RI-V-001 | not-started | Final verification + release evidence: all cards verified merged, negative controls demonstrated, real `next` publish run green on exact commit, evidence pack recorded                                                                                                          | #1275 | pi-glm-5.3 | mosaicstack/stack | docs/ri-050-release-evidence      | RI-1-002, RI-2-001, RI-2-002, RI-3-002, RI-4-001, RI-5-001 | 10K      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 ## Dispatch waves (max 2 parallel workers)
 1. RI-1-001 + RI-2-001
 2. RI-2-002 + RI-4-001
 3. RI-3-001 + RI-5-001
 4. RI-1-002 + RI-3-002
 5. RI-V-001
 ## Budget
 Derived soft cap: 250K tokens (no explicit cap given). Projected total: 190K.
 Conservative mode (1 worker) above 70% projected; freeze above 90%.
@@ -1,242 +0,0 @@
 # Scratchpad — RI-050 orchestrator (jarvis, dragon-lin)
 Mission: alpha 0.0.50 release-integrity floor. Issue #1275. Base `next` @ 476db12b.
 Design SSOT: jarvis-brain `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (SDLC-D-033..038).
 ## Mode (Jason's directives)
 - Orchestrator: jarvis (this session, dragon-lin). NOT mos-claude; work stays on this host.
 - Workers: local pi headless — `pi --model zai/glm-5.3:high -p` in the card's worktree, tools read,bash,edit,write.
 - Delegation override of stack AGENTS.md `agent` column: rows carry `pi-glm-5.3` (outside cron table so no auto-claim).
 - Target branch: `next`. Cards branch from `origin/next`, squash-merge via PR.
 ## Operational constraints (measured this session)
 - Main checkout at `/home/jwoltje/src/mosaic-stack` is a dirty diverged `main` (ahead 1139/behind 711) — NEVER touched. All work in `/home/jwoltje/src/mosaic-stack-worktrees/<branch>`.
 - Disk: /home 187G free. /tmp only 8.7G — keep pnpm stores/node_modules under /home.
 - `main` and `next` have DIVERGED; PRs target `next`.
 - Identity: pin `GITEA_LOGIN=mosaicstack-jarvis` for all wrapper ops. Issue #1275 verified authored by @jarvis.
 - `ci-queue-wait.sh` on this host is fail-open (board: fix #1032 not installed) — substitute SHA-status checks via `/commits/{sha}/status` and diff failing step names.
 - CI on PRs runs `pull_request` pipelines (any branch) incl. ci-postgres service. Push CI runs on main only; publish runs on push/tag to next + manual.
 - Wrapper gaps on this host per board (7 gaps; e.g. no pr-review-list, issue-assign broken, pr-merge makes no trailers): verify outcomes by reading back provider state, never trust rc alone.
 - Publish pipeline currently: install → build → publish-npm/publish-next-npm (+image). No verify. CI steps: install, sanitization, upgrade-guard, typecheck, lint, format, test, ci-postgres.
 ## Budget
 Soft cap 250K. Projected 190K across 10 cards. Track per-card used vs estimate in TASKS.md notes.
 ## Progress log
 - 2026-08-16 23:52 — Issue #1275 created (@jarvis verified).
 - 2026-08-16 23:5x — Bootstrap branch `docs/ri-050-mission-bootstrap` from origin/next@476db12b; PRD section + TASKS.md + this scratchpad written. RI-0-001 in-progress.
 ## Wave 1 dispatched (2026-08-17 00:35)
 - RI-1-001 worker: pi glm-5.3:high, pid 2322125, worktree ri-1-001, log /var/tmp/ri-050/ri-1-001-run.log
 - RI-2-001 worker: pi glm-5.3:high, pid 2322126, worktree ri-2-001, log /var/tmp/ri-050/ri-2-001-run.log
 - Gotcha recorded: pi has no -f flag (that's pi-do.sh); pass brief as positional message. First launch died "Unknown option: -f" — relaunched.
 - CI lane: PR #1276 (bootstrap) fails `test` at base like every next PR — fred's green #1270 unblocks (comms sent 2026-08-17T05:21Z, `comms/20260817T052148Z__from-jarvis__650fe8.md`). Merge gate for all RI PRs queues behind #1270.
 - Live RI-N1 evidence posted to #1275 (comment 22915): pipeline 2439 publish-next-npm SUCCESS beside build-gateway FAILURE.
 ---
 # HANDOFF — RI-050 continuation (written 2026-08-17 ~08:45 UTC, jarvis/dragon-lin)
 You are taking over the alpha 0.0.50 release-integrity workstream in place. Everything you
 need is on the remote. Read this whole file, then `docs/release-integrity/TASKS.md` (same
 branch), then the PRD section (`docs/PRD.md` § Release Integrity Workstream, same branch).
 ## Identity / mode
 - Orchestrator identity: `jarvis` (dragon-lin). You continue as the RI-050 orchestrator under
  whatever identity Jason gives you — if you are NOT jarvis, say so in comms and PR bodies.
 - Jason's standing directives for this mission: work happens on THIS repo (mosaicstack/stack),
  PRs target `next` (NOT main), workers are local pi headless sessions on
  `zai/glm-5.3:high`. Do not hand this to mos-claude. Do not borrow other seats' lanes.
 - All wrapper ops: pin `GITEA_LOGIN=mosaicstack-jarvis` (issue #1275 was verified authored by
  @jarvis; keep identity consistent or verify yours with issue-view and READ BACK user.login).
 - CI substitution rule (this host's ci-queue-wait.sh is fail-open; fix #1032 not installed):
  judge CI by SHA-status via `/api/v1/repos/mosaicstack/stack/commits/{sha}/status` or the
  woodpecker API (`pipeline-status.sh -r mosaicstack/stack -n N -f json`), and DIFF THE
  FAILING STEP NAMES rather than trusting rc.
 ## Mission state at handoff
 Mission: alpha 0.0.50 release-integrity floor. Issue #1275 (open, has live-evidence comment).
 Decisions SDLC-D-033..038 live in jarvis-brain
 `docs/plans/2026-08-16_mosaic-stack-sdlc-protocol.md` (normative text also mirrored in the
 PRD section on this branch, so this repo is self-sufficient).
 Base: `origin/next` @ 476db12b. NOTE: `main` and `next` have DIVERGED — never base on main.
 Branches (all pushed, all clean trees):
 - `docs/ri-050-mission-bootstrap` @ 5114faa2 → PR #1276 (open, mergeable) — bootstrap docs +
  this scratchpad + TASKS.md DAG. STATUS: CI red on `test` only, which is the known lane-wide
  failure (see blocker below); own prettier issue already fixed.
 - `feat/ri-050-publish-gate` @ 0aa5ed35 → PR #1277 (open, mergeable) — RI-1-001 COMPLETE
  (worker reported success, orchestrator review PASSED: verify step asserts CI_COMMIT_SHA ==
  git rev-parse HEAD then runs canonical `pnpm verify:release`; every publish/image step
  depends_on verify directly, confirmed by parsing the DAG: publish-npm, publish-next-npm,
  build-gateway/appservice/web all -> [build, verify]; invariant test
  scripts/verify-release.test.mjs passes 7/7 locally with negative fixtures). CI: same known
  lane-red `test` step only.
 - `fix/ri-050-forge-fail-closed` @ 99b8f6ea → PR #1278 (open, mergeable) — RI-2-001 worker
  reported success (typed `FORGE_*` capability errors, --simulate typed simulated everywhere,
  vacuous true/echo gates replaced, closed ForgeOutcome set, 116 tests green incl. 16 new).
  ORCHESTRATOR REVIEW NOT YET DONE — your first job. Review the diff
  (1391 insertions across forge src), check the fail-closed paths and that simulated
  results cannot satisfy any consumer, run `pnpm --filter @mosaicstack/forge test`.
 ## The one blocker
 Every `next` PR pipeline is red on ONE assertion:
 `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh:103` ("host provides 'pi'
 in the system path"). Pre-existing at base; affects PRs #1276/#1277/#1278 identically.
 fred's PR #1270 ("unblocks every PR on next") is green and open — it is HIS to merge; do not
 merge it yourself. jarvis sent comms (`comms/20260817T052148Z__from-jarvis__650fe8.md` in
 jarvis-brain) asking merge timing; no reply yet as of handoff. Merge gates for ALL RI PRs
 queue behind #1270 landing. Until then: review/develop freely, merge nothing that needs the
 green gate (docs-only #1276 arguably could merge red-lane with Jason's explicit call — ask,
 don't assume).
 ## Remaining DAG (docs/release-integrity/TASKS.md is canonical)
 Wave 2 (next): RI-2-002 MACP fail-closed (brief pattern: mirror RI-2-001 for
 packages/macp/src/gate-runner.ts — empty commands, stub executors, unimplemented CI-provider
 gates fail closed; explicit simulate) and RI-4-001 PRD authority (one PRD service;
@mosaicstack/prdy docs/prdy authoritative via `mosaic mission --plan`; `mosaic prdy` routes
 or becomes named Markdown adapter; mission<->PRD linkage persists — see PRD RI-N3).
 Wave 3: RI-3-001 probe inventory (docs), RI-5-001 web stale-safety.
 Wave 4: RI-1-002 negative-control tests, RI-3-002 TS evaluator absorbs shell probes.
 Final: RI-V-001 evidence pack (real green next publish run post-gate + all cards verified).
 ## Worker mechanics (measured, reuse)
 - Dispatch: create worktree `git -C /home/jwoltje/src/mosaic-stack worktree add
 /home/jwoltje/src/mosaic-stack-worktrees/<id> -b <branch> origin/next`, write a brief to
  /var/tmp/ri-050/, then run from INSIDE the worktree:
  `pi -p --no-session --model zai/glm-5.3:high --tools read,bash,edit,write "$(cat brief.md)"`
  (pi has NO -f flag — pass the brief as a positional message; first dispatch died on that).
 - Briefs for 1-001/2-001 are at /var/tmp/ri-050/ on dragon-lin (may not survive; the
  pattern is fully described above and in TASKS.md).
 - Briefs must carry: worktree path, branch, base, requirements, known base-red list (so the
  worker doesn't chase it), gates to run, PR creation command with GITEA_LOGIN pin, "do NOT
  merge, do NOT touch docs/TASKS.md", and the JSON report format.
 - Verify worker claims: read the PR, run their tests yourself, parse pipeline step names.
 ## Do-not-touch
 - Main checkout at /home/jwoltje/src/mosaic-stack (dirty diverged main) — never touch.
 - fred's open PRs (#1270 and others) — review evidence welcome, merging his is not yours.
 - Other RI PRs' authors' lanes: #1277/#1278 are yours to gate and merge ONCE lane is green
  and review is recorded.
 - Never `--no-verify`; never bypass the wrapper-fails-closed rule (wrapper failure ⇒
  `blocked + report exact command + stop`).
 ## Session-restore command sequence
 1. `git -C /home/jwoltje/src/mosaic-stack-worktrees/ri-050 fetch origin --prune`
 2. Read this file + `docs/release-integrity/TASKS.md` + PRD section.
 3. Check PR states (#1270, #1276, #1277, #1278) and lane CI (SHA-status per above).
 4. Review RI-2-001 (PR #1278) if not yet done; then dispatch wave 2.
 — jarvis, 2026-08-17
 ---
 # CONTINUATION — fargo (sb-it-1-dt)
 Orchestrator seat is now **fargo** on sb-it-1-dt (Jason, 2026-08-17): Claude seat, worktree discipline
 per fred's ruling (`~/agent-work/<slug>`, create → work → commit → push → remove as one act; the
 helper's `/src` refusal is a web1 convention, does not bind here). fred supports; lane rulings are
 his. Workers remain local pi `zai/glm-5.3:high` + limited Claude per Jason.
 ## 2026-08-17 — RI-2-001 independent review DONE
 - **PR #1278 APPROVED** (Gitea review 172, pinned to head 99b8f6ea). Executed evidence, not read-only:
  forge suite 116/116 at head (matches PR claim), forge lint green, forge typecheck green after
  building `@mosaicstack/macp` dist (TS2307 on bare `pnpm install --frozen-lockfile` is a
  minimal-install build-order artifact — the macp import is type-only, vitest passes unbuilt; CI
  installs build workspace deps, hence green there), **workspace typecheck 45/45 at head**,
  consumer sweep: no external type consumers of RunManifest/StageStatus/ForgeTaskResult/
  TaskExecutor; only importer of the package is packages/mosaic via registerForgeCommand
  (smoke test asserts registration/help only — cannot break). Digest gate (shaggy's) before==after
  with both-arm reactivity controls.
 - CI red on #1276/#1277/#1278: lane-wide `test` failure only
  (test-start-agent-session.sh:103, fred's guard mis-wired; #1270 unwires it). Fred measured log
  content: one real byte-identical failure per pipeline (2456/2457/2458); 13 of ~14 `FAIL` grep
  hits are passing fail-loud test NAMES. **The red carries no information about the RI changes.**
 - Non-blocking finding: README L141-143 + skills/mosaic-forge/SKILL.md document bare
  `mosaic forge run`/`resume`, which now exits 1 FORGE_NO_EXECUTOR — fast-follow docs touch.
 - **Identity incident, ruled on by fred:** review 172 recorded under shared host principal
  mos-dt-0, not fargo. Mechanism (measured, wrapper source): pr-review.sh resolves its acting login
  from the tea login list only; no fargo tea login on this host → silent host-default fallback;
  MOSAIC_GIT_IDENTITY is only read in detect-platform.sh get_gitea_token's fallback arm, never
  reached. Exact-id read-back verifies against the writing token, so it passed while attribution
  was wrong — durable-provenance machinery proves the write, not the seat. Fred's ruling: review
  172 stands (substance/verdict/pin correct; label wrong); NO re-approval (one approval,
  annotated, is the stronger record); fred posts the provenance correction under @fred with
  --login fred-ms (hard-fail path); no fargo tea login ever (freeze + Jason's to authorize);
  tooling gap filed by fred. Also explains (does not reopen) #1228's mos-dt-0 attribution.
 - Merge gate: all RI PRs queue behind fred's green #1270 (Jason's call).
 ## Next
 1. Wave 2 dispatch: RI-2-002 (MACP fail-closed, mirror RI-2-001 pattern for
   packages/macp/src/gate-runner.ts) + RI-4-001 (PRD authority). Two parallel workers max.
 2. Docs fast-follow (README + mosaic-forge skill) — fold into #1276 or a tiny docs card.
 3. RI-V-001 evidence at the end.
 — fargo, 2026-08-17
 ---
 # RESUMPTION + DAILY-HANDOFF PROTOCOL (Jason, 2026-08-17)
 Orchestrator seat is back with **jarvis** (dragon-lin). Expect daily handoff between jarvis
 and fargo. Protocol (both seats, every handoff):
 1. **This file is the shared mission log.** Append a dated section per session: state
   measured, actions taken, PR/review states, next actions. Never rewrite prior sections.
 2. **TASKS.md stays current within one session** — status, PR number in notes, review
   evidence. Stale rows are handoff debt.
 3. **Cross-review rule (SDLC-D-011 in practice):** the reviewing seat must differ from the
   producing seat. jarvis reviews fargo-dispatched PRs, fargo reviews jarvis-dispatched
   PRs. Producers are always pi workers; dispatching seats verify before push; the other
   seat records the Gitea review.
 4. Handoff = append here + push + (optional) issue #1275 comment if a decision changed.
 ## RESUMED — jarvis/dragon-lin, 2026-08-17 (afternoon)
 - Measured: next = 8199261c (#1270 merged — lane unblocked for new PRs). #1293/#1294
  (fargo, wave 2) CI-green, mergeable, no recorded reviews. #1276/#1277/#1278 still based
  on 476db12b with stale red CI → need rebase onto 8199261c. #1278 review pinned to old
  head 99b8f6ea by @mos-dt-0 (fargo's, mis-attributed per his note) — rebase will dismiss
  it; re-approval must come from fargo/fred (author is @jarvis, cannot self-approve).
 - Live evidence #2: push pipeline 2462 (the #1270 merge itself) ran publish-next-npm
  SUCCESS beside build-gateway FAILURE again.
 - Plan: rebase the three original branches; independently review #1293/#1294; merge order
  once green+reviewed: #1276 (docs) → #1277 (publish gate) → #1278/#1293/#1294 (code).
  After #1277 merges, watch the next push pipeline prove the verify gate live.
 - fargo's non-RI PRs (#1291/#1296/#1297/#1281) stay strictly his lane.
 ## jarvis session 2026-08-17 (evening) — reviews, rebases, merge plan
 - Rebased #1276/#1277/#1278 onto 8199261c (heads 59e2c460 / 46784c8d / 4917df1f);
  invariant tests 7/7 and forge 116/116 re-run green at new heads. #1270 touched
  test-enumeration-exclusions.txt + package.json, NOT ci.yml — no semantic overlap with
  #1277's ci.yml changes (checked, was a real concern).
 - Independent reviews recorded: #1293 APPROVED (review 173; macp 109/109; fail-closed paths
  + aggregate state machine verified), #1294 APPROVED (review 174; prdy 20/20 + command
  specs 9/9; single-writer + linkage persistence + labeled export + conflict-aware import
  verified). Note: 19 unrelated mosaic suites fail on bare minimal install (known workspace
  build-order artifact, documented by fargo) — not this change.
 - Measured: `next` has NO branch protection (API: only main listed). Cross-seat review
  discipline is protocol-enforced, not Gitea-enforced. Flagged to fargo for Jason: direct
  pushes to next trigger ungated publishes; protection is Jason's call (#1231 adjacent).
 - Merge order planned: #1276 (docs-only — no publish run) -> #1277 (first gated publish)
  -> #1278 -> #1293 -> #1294. Sent fargo review requests with pinned head SHAs
  (comms/20260818T011932Z__from-jarvis__a9c02b.md). Not merging #1293/#1294 before my three
  clear fargo's review — order optimality beats speed; every pre-#1277 merge publishes ungated.
 - CI on the three rebased heads: pending at time of this entry.
@@ -0,0 +1,149 @@
 import { mkdtemp, readFile, readdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { Command } from 'commander';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { registerMissionCommand } from './mission.js';
 import { PrdService } from '@mosaicstack/prdy';
 import type { MissionInfo } from '../tui/gateway-api.js';
 // ── Mocks: the gateway is not available in adapter tests ──────────────────────
 // vi.hoisted: the mock factory is hoisted above imports, so the fixture must
 // be initialized there too.
 const MISSION = vi.hoisted(
  (): MissionInfo => ({
    id: 'mission-plan-1',
    name: 'Plan Mission Alpha',
    description: null,
    status: 'planning',
    projectId: null,
    userId: null,
    phase: null,
    milestones: null,
    config: null,
    createdAt: '2026-01-01T00:00:00.000Z',
    updatedAt: '2026-03-04T05:06:07.000Z',
  }),
 );
 vi.mock('./with-auth.js', () => ({
  withAuth: vi.fn().mockResolvedValue({
    gateway: 'http://localhost:14242',
    cookie: 'better-auth.session_token=test',
    session: {},
  }),
 }));
 vi.mock('../tui/gateway-api.js', () => ({
  fetchMissions: vi.fn().mockResolvedValue([MISSION]),
  fetchMission: vi.fn(),
  createMission: vi.fn(),
  updateMission: vi.fn(),
  fetchMissionTasks: vi.fn().mockResolvedValue([]),
  createMissionTask: vi.fn(),
  updateMissionTask: vi.fn(),
  fetchProjects: vi.fn().mockResolvedValue([]),
 }));
 // ── Helpers ──────────────────────────────────────────────────────────────────
 const originalCwd = process.cwd();
 let projectDir: string;
 let logSpy: ReturnType<typeof vi.spyOn>;
 let consoleStub: ReturnType<typeof vi.spyOn>[] = [];
 function buildTestProgram(): Command {
  const program = new Command('mosaic').exitOverride();
  registerMissionCommand(program);
  return program;
 }
 beforeEach(async () => {
  projectDir = await mkdtemp(path.join(os.tmpdir(), 'mosaic-mission-plan-'));
  process.chdir(projectDir);
  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
  consoleStub.push(logSpy);
 });
 afterEach(() => {
  // Restore only the per-test spies; module factory mocks keep their
  // implementations across tests.
  for (const stub of consoleStub) stub.mockRestore();
  consoleStub = [];
  process.chdir(originalCwd);
 });
 // ── Tests ────────────────────────────────────────────────────────────────────
 describe('mosaic mission --plan (thin adapter over PrdService)', () => {
  it('creates the PRD in the shared docs/prdy authority store and persists the mission linkage', async () => {
    await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
      from: 'user',
    });
    // PRD landed in the same store `mosaic prdy` uses.
    const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
    expect(files).toHaveLength(1);
    expect(files[0]).toMatch(/\.yaml$/);
    // Fresh service instance (new-process equivalent) reads the linkage back.
    const service = new PrdService({ projectPath: projectDir });
    const docs = await service.list();
    expect(docs).toHaveLength(1);
    const prd = docs[0]!;
    expect(prd.title).toBe('Plan Mission Alpha');
    expect(prd.version).toBe(1);
    const links = await service.listMissionLinks(prd.id);
    expect(links).toHaveLength(1);
    expect(links[0]).toMatchObject({
      missionId: MISSION.id,
      missionVersion: MISSION.updatedAt, // mission version marker
      prdVersion: 1,
    });
    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PRD created and linked'));
  });
  it('linkage is persisted in the YAML authority document itself (survives restart)', async () => {
    await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
      from: 'user',
    });
    const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
    const raw = await readFile(path.join(projectDir, 'docs', 'prdy', files[0]!), 'utf8');
    const persisted = parseYaml(raw) as { missions: Array<Record<string, unknown>> };
    expect(persisted.missions).toHaveLength(1);
    expect(persisted.missions[0]).toMatchObject({ missionId: 'mission-plan-1' });
  });
  it('the mission path and the prdy path resolve to the same store with stable ids/versions', async () => {
    // Mission path.
    await buildTestProgram().parseAsync(['mission', '--plan', 'Plan Mission Alpha'], {
      from: 'user',
    });
    // prdy path (service, non-interactive entry).
    const service = new PrdService({ projectPath: projectDir });
    const direct = await service.create({ name: 'Directly Created' });
    const all = await service.list();
    expect(all.map((doc) => doc.id).sort()).toEqual([...all.map((doc) => doc.id)].sort());
    expect(all).toHaveLength(2);
    const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
    expect(files).toContain(`${direct.id}.yaml`);
    // Both are v1 in the same store with distinct stable ids.
    for (const doc of all) {
      expect(doc.version).toBe(1);
      expect(files).toContain(`${doc.id}.yaml`);
    }
  });
 });
@@ -256,14 +256,41 @@ async function planMission(
  console.log(`Planning mission: ${mission.name}\n`);
  try {
-    const { runPrdWizard } = await import('@mosaicstack/prdy');
+    // Thin adapter: the PRD authority (create + mission↔PRD linkage) lives in
-    await runPrdWizard({
+    // PrdService — no second writer path. The mission's updatedAt serves as
    // its version marker (the gateway exposes no numeric mission version).
    const { PrdService, runPrdWizard } = await import('@mosaicstack/prdy');
    const service = new PrdService({ projectPath: process.cwd() });
    if (process.stdout.isTTY) {
      const created = await runPrdWizard({
        name: mission.name,
        projectPath: process.cwd(),
        interactive: true,
      });
      const linked = await service.linkMission({
        prdId: created.id,
        missionId: mission.id,
        missionVersion: mission.updatedAt,
        requirementIds: [],
      });
      console.log(
        `\nMission ${mission.id} linked to PRD ${linked.id} v${linked.version} (docs/prdy/).`,
      );
      return;
    }
    const doc = await service.planForMission({
      name: mission.name,
-      projectPath: process.cwd(),
+      missionId: mission.id,
-      interactive: true,
+      missionVersion: mission.updatedAt,
      requirementIds: [],
    });
    console.log(
      `PRD created and linked: ${doc.id} v${doc.version} — mission ${mission.id} (docs/prdy/).`,
    );
  } catch (err) {
-    console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(`PRD planning failed: ${err instanceof Error ? err.message : String(err)}`);
    process.exit(1);
  }
 }
@@ -0,0 +1,204 @@
 import { mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { stringify as stringifyYaml } from 'yaml';
 import { Command } from 'commander';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { registerPrdyCommand } from './prdy.js';
 import { PrdService } from '@mosaicstack/prdy';
 // ── Mocks: keep the adapter test offline (no gateway, no disk side effects
 //    outside the tmp project dir) ──────────────────────────────────────────────
 vi.mock('./with-auth.js', () => ({
  withAuth: vi.fn().mockResolvedValue({
    gateway: 'http://localhost:14242',
    cookie: 'better-auth.session_token=test',
    session: {},
  }),
 }));
 vi.mock('../tui/gateway-api.js', () => ({
  fetchProjects: vi.fn().mockResolvedValue([]),
 }));
 // ── Helpers ──────────────────────────────────────────────────────────────────
 class ProcessExitError extends Error {
  constructor(readonly code: number) {
    super(`process.exit(${code})`);
  }
 }
 function stubProcessExit() {
  return vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
    throw new ProcessExitError(code ?? 0);
  }) as never);
 }
 const originalCwd = process.cwd();
 let projectDir: string;
 let errorSpy: ReturnType<typeof vi.spyOn>;
 let logSpy: ReturnType<typeof vi.spyOn>;
 let exitStub: ReturnType<typeof stubProcessExit>;
 function buildTestProgram(): Command {
  const program = new Command('mosaic').exitOverride();
  registerPrdyCommand(program);
  return program;
 }
 function runPrdy(args: string[]): Promise<unknown> {
  return buildTestProgram().parseAsync(['prdy', ...args], { from: 'user' });
 }
 function importableDocument(overrides: Record<string, unknown> = {}): Record<string, unknown> {
  return {
    id: 'cmd-import-prd',
    title: 'Command Import PRD',
    status: 'approved', // must be forced to draft: validity is not approval
    projectPath: '/tmp/elsewhere',
    template: 'software',
    version: 1,
    sections: [
      { id: 'introduction', title: 'Introduction', fields: { context: 'x', objective: 'y' } },
    ],
    missions: [],
    createdAt: '2026-01-01T00:00:00.000Z',
    updatedAt: '2026-01-01T00:00:00.000Z',
    ...overrides,
  };
 }
 beforeEach(async () => {
  projectDir = await mkdtemp(path.join(os.tmpdir(), 'mosaic-prdy-'));
  process.chdir(projectDir);
  exitStub = stubProcessExit();
  errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
 });
 afterEach(() => {
  // Restore only the per-test spies: module factory mocks must keep their
  // implementations for the next test.
  exitStub.mockRestore();
  errorSpy.mockRestore();
  logSpy.mockRestore();
  process.chdir(originalCwd);
 });
 // ── Tests ────────────────────────────────────────────────────────────────────
 describe('mosaic prdy (thin adapter over PrdService)', () => {
  it('non-interactive --init creates a PRD in the docs/prdy authority store', async () => {
    await runPrdy(['--init', 'Adapter Created']);
    const files = await readdir(path.join(projectDir, 'docs', 'prdy'));
    expect(files).toHaveLength(1);
    expect(files[0]).toMatch(/\.yaml$/);
    const docs = await new PrdService({ projectPath: projectDir }).list();
    expect(docs).toHaveLength(1);
    expect(docs[0]?.title).toBe('Adapter Created');
    expect(docs[0]?.version).toBe(1);
    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PRD created'));
  });
  it('--import <file> creates a valid import through the service', async () => {
    const filePath = path.join(projectDir, 'incoming.yaml');
    await writeFile(filePath, stringifyYaml(importableDocument()), 'utf8');
    await runPrdy(['--import', filePath]);
    const docs = await new PrdService({ projectPath: projectDir }).list();
    expect(docs).toHaveLength(1);
    expect(docs[0]?.id).toBe('cmd-import-prd');
    expect(docs[0]?.status).toBe('draft'); // import ≠ approval
    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Imported PRD cmd-import-prd'));
  });
  it('--import of a structurally-invalid file is a typed refusal that creates nothing', async () => {
    const filePath = path.join(projectDir, 'broken.yaml');
    await writeFile(filePath, stringifyYaml({ id: 'incomplete', no: 'structure' }), 'utf8');
    await expect(runPrdy(['--import', filePath])).rejects.toBeInstanceOf(ProcessExitError);
    // Typed refusal surfaced to the user, nothing created.
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('PRD wizard failed'));
    await expect(readdir(path.join(projectDir, 'docs'))).rejects.toMatchObject({ code: 'ENOENT' });
  });
  it('--import on conflict refuses with a successor proposal and leaves bytes untouched', async () => {
    const service = new PrdService({ projectPath: projectDir });
    const existing = await service.create({ name: 'Conflict Target' });
    const storeFile = path.join(projectDir, 'docs', 'prdy', `${existing.id}.yaml`);
    const beforeBytes = await readFile(storeFile, 'utf8');
    const filePath = path.join(projectDir, 'divergent.yaml');
    await writeFile(
      filePath,
      stringifyYaml(
        importableDocument({
          ...existing,
          title: 'Divergent Command Import',
        }),
      ),
      'utf8',
    );
    await expect(runPrdy(['--import', filePath])).rejects.toBeInstanceOf(ProcessExitError);
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('refusing to overwrite'));
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--accept-successor'));
    // Original authority document is byte-identical on disk.
    expect(await readFile(storeFile, 'utf8')).toBe(beforeBytes);
  });
  it('--import --accept-successor persists the successor version explicitly', async () => {
    const service = new PrdService({ projectPath: projectDir });
    const existing = await service.create({ name: 'Successor Target' });
    const filePath = path.join(projectDir, 'divergent2.yaml');
    await writeFile(
      filePath,
      stringifyYaml(
        importableDocument({
          ...existing,
          title: 'Accepted Via CLI',
        }),
      ),
      'utf8',
    );
    await runPrdy(['--import', filePath, '--accept-successor']);
    const doc = await service.get(existing.id);
    expect(doc.version).toBe(2);
    expect(doc.title).toBe('Accepted Via CLI');
    expect(doc.status).toBe('draft');
    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('successor'));
  });
  it('--export writes a labeled generated view and never touches authority', async () => {
    const service = new PrdService({ projectPath: projectDir });
    const created = await service.create({ name: 'Export Via CLI' });
    const before = await service.get(created.id);
    await runPrdy(['--export', created.id]);
    const mdPath = path.join(projectDir, 'docs', 'prdy', `${created.id}.md`);
    const md = await readFile(mdPath, 'utf8');
    expect(md).toContain('generated view — do not edit');
    expect(md).toContain(`prd-id: ${created.id}`);
    expect(md).toContain('prd-version: 1');
    expect(logSpy).toHaveBeenCalledWith(
      expect.stringContaining(`Generated view written: ${mdPath}`),
    );
    // Authority unchanged by the export.
    expect(await service.get(created.id)).toEqual(before);
  });
 });
@@ -2,6 +2,10 @@ import type { Command } from 'commander';
 import { withAuth } from './with-auth.js';
 import { fetchProjects } from '../tui/gateway-api.js';
 /**
 * `mosaic prdy` — thin adapter over PrdService (@mosaicstack/prdy).
 * All reads/writes go through the service; there is no local writer path.
 */
 export function registerPrdyCommand(program: Command) {
  const cmd = program
    .command('prdy')
@@ -9,12 +13,18 @@ export function registerPrdyCommand(program: Command) {
    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
    .option('--init [name]', 'Create a new PRD')
    .option('--update [name]', 'Update an existing PRD')
    .option('--import <file>', 'Import a YAML PRD document (validated, conflict-aware)')
    .option('--accept-successor', 'With --import: accept a conflicted import as next version')
    .option('--export [id]', 'Export a PRD as a labeled generated-view Markdown file')
    .option('--project <idOrName>', 'Scope to project')
    .action(
      async (opts: {
        gateway: string;
        init?: string | boolean;
        update?: string | boolean;
        import?: string;
        acceptSuccessor?: boolean;
        export?: string | boolean;
        project?: string;
      }) => {
        // Detect project context when --project flag is provided
@@ -31,20 +41,69 @@ export function registerPrdyCommand(program: Command) {
          }
        }
        const { PrdService, runPrdWizard } = await import('@mosaicstack/prdy');
        const service = new PrdService({ projectPath: process.cwd() });
        try {
-          const { runPrdWizard } = await import('@mosaicstack/prdy');
+          if (opts.import !== undefined) {
            const input = { filePath: opts.import };
            if (opts.acceptSuccessor) {
              const successor = await service.acceptSuccessor(input);
              console.log(
                `Import accepted as successor: ${successor.id} v${successor.version} (status: ${successor.status})`,
              );
              return;
            }
            const result = await service.importDocument(input);
            console.log(
              result.kind === 'created'
                ? `Imported PRD ${result.document.id} v${result.document.version} (status: ${result.document.status})`
                : `PRD ${result.document.id} already present with identical content — nothing to do.`,
            );
            return;
          }
          if (opts.export !== undefined) {
            const id =
              typeof opts.export === 'string' && opts.export.length > 0 ? opts.export : undefined;
            const result = await service.exportMarkdown({ id });
            console.log(
              `Generated view written: ${result.filePath} (source authority: YAML under docs/prdy/ — do not edit the Markdown)`,
            );
            return;
          }
          const name =
            typeof opts.init === 'string'
              ? opts.init
              : typeof opts.update === 'string'
                ? opts.update
                : 'untitled';
-          await runPrdWizard({
+
-            name,
+          if (process.stdout.isTTY) {
-            projectPath: process.cwd(),
+            await runPrdWizard({
-            interactive: true,
+              name,
-          });
+              projectPath: process.cwd(),
              interactive: true,
            });
            return;
          }
          // Non-interactive fallback routes through the service directly.
          const doc = await service.create({ name });
          console.log(`PRD created: ${doc.id} v${doc.version} (status: ${doc.status})`);
        } catch (err) {
          if (err instanceof Error && err.name === 'PrdImportConflictError') {
            const conflict = err as { proposal?: { version?: number } };
            console.error(`${err.message}`);
            console.error(
              `Original PRD left untouched. To accept the proposed successor (v${conflict.proposal?.version}), re-run with --accept-successor.`,
            );
            process.exit(1);
          }
          console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
          process.exit(1);
        }
@@ -1,6 +1,6 @@
 import { Command } from 'commander';
-import { createPrd, listPrds, loadPrd } from './prd.js';
+import { PrdService } from './service.js';
 import { runPrdWizard } from './wizard.js';
 interface InitCommandOptions {
@@ -18,6 +18,22 @@ interface ShowCommandOptions {
  readonly id?: string;
 }
 interface ImportCommandOptions {
  readonly project: string;
  readonly file: string;
  readonly acceptSuccessor?: boolean;
 }
 interface ExportCommandOptions {
  readonly project: string;
  readonly id?: string;
  readonly out?: string;
 }
 function serviceFor(project: string): PrdService {
  return new PrdService({ projectPath: project });
 }
 export function buildPrdyCli(): Command {
  const program = new Command();
  program.name('mosaic').description('Mosaic CLI').exitOverride();
@@ -38,11 +54,9 @@ export function buildPrdyCli(): Command {
            template: options.template,
            interactive: true,
          })
-        : await createPrd({
+        : await serviceFor(options.project).create({
            name: options.name,
            projectPath: options.project,
            template: options.template,
            interactive: false,
          });
      console.log(
@@ -52,6 +66,7 @@ export function buildPrdyCli(): Command {
            id: doc.id,
            title: doc.title,
            status: doc.status,
            version: doc.version,
            projectPath: doc.projectPath,
          },
          null,
@@ -65,7 +80,7 @@ export function buildPrdyCli(): Command {
    .description('List PRD documents for a project')
    .requiredOption('--project <path>', 'Project path')
    .action(async (options: ListCommandOptions) => {
-      const docs = await listPrds(options.project);
+      const docs = await serviceFor(options.project).list();
      console.log(JSON.stringify(docs, null, 2));
    });
@@ -75,20 +90,65 @@ export function buildPrdyCli(): Command {
    .requiredOption('--project <path>', 'Project path')
    .option('--id <id>', 'PRD document id')
    .action(async (options: ShowCommandOptions) => {
-      if (options.id !== undefined) {
+      const doc = await serviceFor(options.project).get(options.id);
-        const docs = await listPrds(options.project);
+      console.log(JSON.stringify(doc, null, 2));
-        const match = docs.find((doc) => doc.id === options.id);
+    });
-        if (match === undefined) {
+  prdy
-          throw new Error(`PRD id not found: ${options.id}`);
+    .command('import')
-        }
+    .description('Import a YAML PRD document (validated; conflicts propose a successor)')
    .requiredOption('--project <path>', 'Project path')
    .requiredOption('--file <file>', 'Path to YAML PRD document')
    .option('--accept-successor', 'Accept a conflicted import as the next version')
    .action(async (options: ImportCommandOptions) => {
      const service = serviceFor(options.project);
      const input = { filePath: options.file };
-        console.log(JSON.stringify(match, null, 2));
+      if (options.acceptSuccessor) {
        const successor = await service.acceptSuccessor(input);
        console.log(
          JSON.stringify(
            {
              ok: true,
              outcome: 'successor-accepted',
              id: successor.id,
              version: successor.version,
            },
            null,
            2,
          ),
        );
        return;
      }
-      const doc = await loadPrd(options.project);
+      const result = await service.importDocument(input);
-      console.log(JSON.stringify(doc, null, 2));
+      console.log(
        JSON.stringify(
          {
            ok: true,
            outcome: result.kind,
            id: result.document.id,
            version: result.document.version,
            status: result.document.status,
          },
          null,
          2,
        ),
      );
    });
  prdy
    .command('export')
    .description('Render a PRD to a labeled generated-view Markdown file')
    .requiredOption('--project <path>', 'Project path')
    .option('--id <id>', 'PRD document id')
    .option('--out <path>', 'Output path (default docs/prdy/<id>.md)')
    .action(async (options: ExportCommandOptions) => {
      const result = await serviceFor(options.project).exportMarkdown({
        id: options.id,
        outPath: options.out,
      });
      console.log(JSON.stringify({ ok: true, filePath: result.filePath }, null, 2));
    });
  return program;
@@ -1,12 +1,35 @@
-export { createPrd, loadPrd, savePrd, listPrds } from './prd.js';
+// PrdService is the single authority surface for PRD documents. The raw store
 // writers (createPrd/savePrd) are deliberately NOT exported: every mutation
 // goes through the service so there is no second writer path.
 export { loadPrd, listPrds, parsePrdDocument } from './prd.js';
 export { runPrdWizard } from './wizard.js';
 export { buildPrdyCli, runPrdyCli } from './cli.js';
 export { BUILTIN_PRD_TEMPLATES, resolveTemplate } from './templates.js';
 export {
  PrdService,
  PRD_GENERATED_VIEW_LABEL,
  PrdError,
  PrdNotFoundError,
  PrdUpdateError,
  PrdImportInvalidError,
  PrdImportConflictError,
 } from './service.js';
 export type {
  PrdStatus,
  PrdTemplate,
  PrdTemplateSection,
  PrdSection,
  PrdMissionLinkage,
  PrdDocument,
  CreatePrdOptions,
  PrdServiceOptions,
  PrdCreateInput,
  PrdSectionPatch,
  PrdUpdateInput,
  PrdLinkMissionInput,
  PrdPlanForMissionInput,
  PrdExportInput,
  PrdExportResult,
  PrdImportInput,
  PrdImportResult,
 } from './types.js';
@@ -17,17 +17,49 @@ const prdSectionSchema = z.object({
  fields: z.record(z.string(), z.string()),
 });
 const prdMissionLinkageSchema = z.object({
  missionId: z.string().min(1),
  missionVersion: z.string().min(1),
  prdVersion: z.number().int().min(1),
  requirementIds: z.array(z.string()),
  linkedAt: z.string().datetime(),
 });
 const prdDocumentSchema = z.object({
  id: z.string().min(1),
  title: z.string().min(1),
  status: z.enum(['draft', 'review', 'approved', 'archived']),
  projectPath: z.string().min(1),
  template: z.string().min(1),
  // Defaults keep documents written by older prdy versions loadable.
  version: z.number().int().min(1).default(1),
  sections: z.array(prdSectionSchema),
  missions: z.array(prdMissionLinkageSchema).default([]),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
 });
 /** YAML timestamp scalars are parsed as Date by some emitters — normalize to ISO strings. */
 function coerceTimestamps(value: unknown): unknown {
  if (value instanceof Date) {
    return value.toISOString();
  }
  if (Array.isArray(value)) {
    return value.map(coerceTimestamps);
  }
  if (typeof value === 'object' && value !== null) {
    return Object.fromEntries(
      Object.entries(value).map(([key, entry]) => [key, coerceTimestamps(entry)]),
    );
  }
  return value;
 }
 /** Validate an unknown value as a PRD document (throws zod errors on failure). */
 export function parsePrdDocument(value: unknown): PrdDocument {
  return prdDocumentSchema.parse(coerceTimestamps(value)) as PrdDocument;
 }
 function expandHome(projectPath: string): string {
  if (!projectPath.startsWith('~')) {
    return projectPath;
@@ -74,6 +106,8 @@ function prdDirectory(projectPath: string): string {
  return path.join(projectPath, PRD_DIRECTORY);
 }
 export { prdDirectory };
 function prdFilePath(projectPath: string, id: string): string {
  return path.join(prdDirectory(projectPath), `${id}.yaml`);
 }
@@ -113,11 +147,13 @@ export async function createPrd(options: CreatePrdOptions): Promise<PrdDocument>
    status: 'draft',
    projectPath: resolvedProjectPath,
    template: template.id,
    version: 1,
    sections: template.sections.map((section) => ({
      id: section.id,
      title: section.title,
      fields: Object.fromEntries(section.fields.map((field) => [field, ''])),
    })),
    missions: [],
    createdAt: now,
    updatedAt: now,
  };
@@ -190,7 +226,7 @@ export async function listPrds(projectPath: string): Promise<PrdDocument[]> {
      throw new Error(`Failed to parse PRD file ${filePath}: ${String(error)}`);
    }
-    const document = prdDocumentSchema.parse(parsed);
+    const document = parsePrdDocument(parsed);
    documents.push(document);
  }
@@ -0,0 +1,433 @@
 import { existsSync } from 'node:fs';
 import { mkdtemp, readFile, readdir, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import yaml from 'js-yaml';
 import { beforeEach, describe, expect, it } from 'vitest';
 import {
  PRD_GENERATED_VIEW_LABEL,
  PrdImportConflictError,
  PrdImportInvalidError,
  PrdNotFoundError,
  PrdService,
  PrdUpdateError,
 } from './index.js';
 import type { PrdDocument } from './index.js';
 // ── Helpers ──────────────────────────────────────────────────────────────────
 let projectDir: string;
 async function makeProject(): Promise<string> {
  return mkdtemp(path.join(os.tmpdir(), 'prdy-service-'));
 }
 function service(): PrdService {
  return new PrdService({ projectPath: projectDir });
 }
 function storeDir(): string {
  return path.join(projectDir, 'docs', 'prdy');
 }
 /** Handcraft a full, schema-valid PRD document for import scenarios. */
 function importFixture(overrides: Partial<PrdDocument> = {}): PrdDocument {
  return {
    id: 'imported-prd-20260101-000000',
    title: 'Imported PRD',
    status: 'draft',
    projectPath: '/tmp/elsewhere',
    template: 'software',
    version: 1,
    sections: [
      { id: 'introduction', title: 'Introduction', fields: { context: '', objective: '' } },
      {
        id: 'scope-non-goals',
        title: 'Scope / Non-Goals',
        fields: { inScope: '', outOfScope: '' },
      },
    ],
    missions: [],
    createdAt: '2026-01-01T00:00:00.000Z',
    updatedAt: '2026-01-01T00:00:00.000Z',
    ...overrides,
  };
 }
 async function writeImportFile(doc: PrdDocument): Promise<string> {
  const filePath = path.join(projectDir, `${doc.id}.import.yaml`);
  await writeFile(filePath, yaml.dump(doc), 'utf8');
  return filePath;
 }
 beforeEach(async () => {
  projectDir = await makeProject();
 });
 // ── Single authority store (AC: prdy path and mission path resolve to the
 //    SAME store under docs/prdy/ with stable ids/versions) ────────────────────
 describe('PrdService single authority store', () => {
  it('persists PRDs from the prdy path and the mission path into the same docs/prdy store', async () => {
    const direct = await service().create({ name: 'Direct PRD' });
    const viaMission = await service().planForMission({
      name: 'Mission PRD',
      missionId: 'mission-1',
      missionVersion: '2026-01-01T00:00:00.000Z',
    });
    const files = await readdir(storeDir());
    expect(files).toContain(`${direct.id}.yaml`);
    expect(files).toContain(`${viaMission.id}.yaml`);
    // A fresh service instance (new process equivalent) resolves both.
    const all = await service().list();
    expect(all.map((doc) => doc.id).sort()).toEqual([direct.id, viaMission.id].sort());
    // Stable versions: creation is v1; linkage writes do not bump content version.
    expect((await service().get(direct.id)).version).toBe(1);
    expect((await service().get(viaMission.id)).version).toBe(1);
  });
  it('round-trips documents through the store with identity intact', async () => {
    const created = await service().create({ name: 'Round Trip', template: 'feature' });
    const fresh = await service().get(created.id);
    expect(fresh).toEqual(created);
    expect(fresh.id).toBe(created.id);
    expect(fresh.template).toBe('feature');
    expect(fresh.status).toBe('draft');
  });
  it('throws a typed error for unknown ids and empty stores', async () => {
    await expect(service().get('nope')).rejects.toBeInstanceOf(PrdNotFoundError);
    await expect(service().get()).rejects.toBeInstanceOf(PrdNotFoundError);
  });
 });
 // ── Mission linkage persistence (AC: linkage survives restart via fresh
 //    service instances) ────────────────────────────────────────────────────────
 describe('PrdService mission linkage', () => {
  it('persists linkage and reads it back from a fresh service instance', async () => {
    const created = await service().planForMission({
      name: 'Linked PRD',
      missionId: 'mission-42',
      missionVersion: '2026-02-03T04:05:06.000Z',
      requirementIds: ['FR-1', 'FR-2'],
    });
    // Fresh instance — nothing in memory from the creating call.
    const links = await service().listMissionLinks(created.id);
    expect(links).toHaveLength(1);
    expect(links[0]).toMatchObject({
      missionId: 'mission-42',
      missionVersion: '2026-02-03T04:05:06.000Z',
      prdVersion: 1,
      requirementIds: ['FR-1', 'FR-2'],
    });
    // Linkage is carried in the YAML authority file itself.
    const raw = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
    const persisted = yaml.load(raw) as PrdDocument;
    expect(persisted.missions[0]?.missionId).toBe('mission-42');
    expect(persisted.missions[0]?.requirementIds).toEqual(['FR-1', 'FR-2']);
  });
  it('refreshes an existing linkage entry in place instead of duplicating', async () => {
    const created = await service().planForMission({
      name: 'Relink PRD',
      missionId: 'mission-7',
      missionVersion: 'v1',
    });
    await service().update({
      id: created.id,
      sections: [{ id: 'introduction', fields: { objective: 'Ship it' } }],
    });
    const relinked = await service().linkMission({
      prdId: created.id,
      missionId: 'mission-7',
      missionVersion: 'v2',
      requirementIds: ['NFR-1'],
    });
    expect(relinked.missions).toHaveLength(1);
    expect(relinked.missions[0]).toMatchObject({ missionVersion: 'v2', prdVersion: 2 });
  });
  it('does not bump the content version when writing linkage', async () => {
    const created = await service().create({ name: 'Stable Version' });
    const linked = await service().linkMission({
      prdId: created.id,
      missionId: 'm',
      missionVersion: 'v1',
    });
    expect(linked.version).toBe(1);
  });
 });
 // ── Update semantics ──────────────────────────────────────────────────────────
 describe('PrdService update', () => {
  it('applies section patches and bumps the content version', async () => {
    const created = await service().create({ name: 'Updatable' });
    const updated = await service().update({
      id: created.id,
      sections: [{ id: 'introduction', fields: { context: 'Some context', objective: 'Goal' } }],
    });
    expect(updated.version).toBe(2);
    expect(updated.sections[0]?.fields).toMatchObject({
      context: 'Some context',
      objective: 'Goal',
    });
    expect((await service().get(created.id)).version).toBe(2);
  });
  it('refuses unknown section ids with a typed error', async () => {
    const created = await service().create({ name: 'Strict' });
    await expect(
      service().update({ id: created.id, sections: [{ id: 'nope', fields: {} }] }),
    ).rejects.toBeInstanceOf(PrdUpdateError);
  });
 });
 // ── Markdown export is a labeled generated view, never authority ──────────────
 describe('PrdService exportMarkdown', () => {
  it('writes a generated view carrying the label and source identity', async () => {
    const created = await service().create({ name: 'Exported PRD' });
    const result = await service().exportMarkdown({ id: created.id });
    expect(result.filePath).toBe(path.join(storeDir(), `${created.id}.md`));
    expect(result.content).toContain(PRD_GENERATED_VIEW_LABEL);
    expect(result.content).toContain(`prd-id: ${created.id}`);
    expect(result.content).toContain('prd-version: 1');
    expect(result.content).toContain(`source-of-truth: docs/prdy/${created.id}.yaml`);
  });
  it('reflects the current version after updates', async () => {
    const created = await service().create({ name: 'Versioned Export' });
    await service().update({
      id: created.id,
      sections: [{ id: 'introduction', fields: { objective: 'v2 goal' } }],
    });
    const result = await service().exportMarkdown({ id: created.id });
    expect(result.content).toContain('prd-version: 2');
  });
  it('NEGATIVE CONTROL: mutating the exported Markdown cannot change the authority', async () => {
    const created = await service().create({ name: 'Guarded PRD' });
    const before = structuredClone(await service().get(created.id));
    const result = await service().exportMarkdown({ id: created.id });
    await writeFile(
      result.filePath,
      `<!-- ${PRD_GENERATED_VIEW_LABEL} -->\n# FAKE\nprd-id: fake-id\nprd-version: 99\n`,
      'utf8',
    );
    const after = await service().get(created.id);
    expect(after).toEqual(before);
    expect(after.version).toBe(1);
    expect(after.title).toBe(before.title);
  });
  it('never parses Markdown files that sit in the store directory', async () => {
    const created = await service().create({ name: 'Decoy Guard' });
    // A decoy .md file with invalid YAML must be invisible to the store.
    await writeFile(path.join(storeDir(), 'decoy.md'), 'not: [valid: yaml', 'utf8');
    // And a decoy .yaml-named Markdown body must not silently validate either.
    await service().exportMarkdown({ id: created.id });
    const listed = await service().list();
    expect(listed.map((doc) => doc.id)).toEqual([created.id]);
    await expect(service().get(created.id)).resolves.toBeTruthy();
  });
 });
 // ── Import: validated, conflict-aware, never silently merging ─────────────────
 describe('PrdService importDocument', () => {
  it('creates a valid import through the service, as draft — validity is not approval', async () => {
    const filePath = await writeImportFile(importFixture({ status: 'approved' }));
    const result = await service().importDocument({ filePath });
    expect(result.kind).toBe('created');
    expect(result.document.id).toBe('imported-prd-20260101-000000');
    expect(result.document.status).toBe('draft'); // structural validity ≠ approval
    expect(result.document.version).toBe(1);
    const persisted = await service().get('imported-prd-20260101-000000');
    expect(persisted.status).toBe('draft');
    const files = await readdir(storeDir());
    expect(files).toContain('imported-prd-20260101-000000.yaml');
  });
  it('reports identical content as a no-op without writing', async () => {
    const created = await service().create({ name: 'Existing PRD' });
    const before = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
    const filePath = await writeImportFile(importFixture({ ...created }));
    const result = await service().importDocument({ filePath });
    expect(result.kind).toBe('identical');
    const after = await readFile(path.join(storeDir(), `${created.id}.yaml`), 'utf8');
    expect(after).toBe(before);
  });
  it('refuses a conflicting import with a typed error, a proposed successor, and untouched bytes', async () => {
    const existing = await service().create({ name: 'Authority PRD' });
    await service().linkMission({
      prdId: existing.id,
      missionId: 'mission-keep',
      missionVersion: 'v1',
      requirementIds: ['FR-0'],
    });
    const beforeBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
    const divergent = importFixture({
      ...existing,
      title: 'Divergent Title',
      sections: [
        {
          id: 'introduction',
          title: 'Introduction',
          fields: { context: 'changed', objective: '' },
        },
      ],
    });
    const filePath = await writeImportFile(divergent);
    const attempt = service().importDocument({ filePath });
    let caught: unknown;
    try {
      await attempt;
    } catch (error) {
      caught = error;
    }
    expect(caught).toBeInstanceOf(PrdImportConflictError);
    const error = caught as PrdImportConflictError;
    expect(error.code).toBe('PRD_IMPORT_CONFLICT');
    expect(error.existing.id).toBe(existing.id);
    expect(error.proposal.version).toBe(existing.version + 1); // successor proposal
    expect(error.proposal.status).toBe('draft');
    // Original authority content untouched on disk.
    const afterBytes = await readFile(path.join(storeDir(), `${existing.id}.yaml`), 'utf8');
    expect(afterBytes).toBe(beforeBytes);
  });
  it('acceptSuccessor persists the proposal explicitly, carrying linkages forward', async () => {
    const existing = await service().create({ name: 'Successor Base' });
    await service().linkMission({
      prdId: existing.id,
      missionId: 'mission-keep',
      missionVersion: 'v1',
    });
    const divergent = importFixture({
      ...existing,
      title: 'Accepted Successor Title',
    });
    const filePath = await writeImportFile(divergent);
    const successor = await service().acceptSuccessor({ filePath });
    expect(successor.id).toBe(existing.id);
    expect(successor.version).toBe(existing.version + 1);
    expect(successor.title).toBe('Accepted Successor Title');
    expect(successor.status).toBe('draft');
    expect(successor.missions.map((m) => m.missionId)).toEqual(['mission-keep']);
    // Persisted for a fresh reader.
    const fresh = await service().get(existing.id);
    expect(fresh.version).toBe(2);
    expect(fresh.title).toBe('Accepted Successor Title');
  });
  it('refuses structurally-invalid imports with a typed error and creates nothing', async () => {
    const cases: Array<{ name: string; body: string }> = [
      { name: 'missing-title.yaml', body: yaml.dump({ id: 'x', status: 'draft' }) },
      {
        name: 'bad-status.yaml',
        body: yaml.dump(importFixture({ status: 'not-a-status' as PrdDocument['status'] })),
      },
      {
        name: 'bad-version.yaml',
        body: yaml.dump(importFixture({ version: 0 })),
      },
      { name: 'not-yaml.yaml', body: '::: not yaml [\n  - {' },
    ];
    for (const fixture of cases) {
      const filePath = path.join(projectDir, fixture.name);
      await writeFile(filePath, fixture.body, 'utf8');
      await expect(service().importDocument({ filePath })).rejects.toBeInstanceOf(
        PrdImportInvalidError,
      );
    }
    // Nothing was created: the authority store does not even exist yet.
    await expect(readdir(storeDir())).rejects.toMatchObject({ code: 'ENOENT' });
  });
  it('acceptSuccessor refuses when there is no existing document to succeed', async () => {
    const filePath = await writeImportFile(importFixture());
    await expect(service().acceptSuccessor({ filePath })).rejects.toBeInstanceOf(PrdNotFoundError);
  });
 });
 // ── No second writer: no code path reads exported Markdown back into authority ─
 describe('no-second-writer invariant (source-level)', () => {
  // Resolve the package source dir whether vitest runs from the package root
  // (turbo/pnpm test) or from the worktree root.
  function resolveSrcDir(): string {
    const candidates = [path.resolve('src'), path.resolve('packages/prdy/src')];
    return candidates.find((dir) => existsSync(path.join(dir, 'service.ts'))) ?? candidates[0]!;
  }
  const srcDir = resolveSrcDir();
  const sourceFiles = [
    'cli.ts',
    'index.ts',
    'prd.ts',
    'service.ts',
    'templates.ts',
    'types.ts',
    'wizard.ts',
  ];
  it('no source file in @mosaicstack/prdy reads a .md file', async () => {
    for (const file of sourceFiles) {
      const text = await readFile(path.join(srcDir, file), 'utf8');
      const readLines = text
        .split('\n')
        .map((line) => line.trim())
        .filter((line) => /readFile|readFileSync|createReadStream/.test(line));
      for (const line of readLines) {
        expect(line.includes('.md'), `${file} reads a Markdown file: ${line}`).toBe(false);
      }
    }
  });
  it('the mosaic prdy/mission adapters never read a .md file', async () => {
    const adapterDir = path.resolve(srcDir, '..', '..', 'mosaic', 'src', 'commands');
    for (const file of ['prdy.ts', 'mission.ts']) {
      const text = await readFile(path.join(adapterDir, file), 'utf8');
      expect(text.includes("'.md'") || text.includes('.md`'), `${file} references a .md path`).toBe(
        false,
      );
    }
  });
 });
@@ -0,0 +1,379 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 import { createPrd, listPrds, parsePrdDocument, prdDirectory, savePrd } from './prd.js';
 import type {
  PrdCreateInput,
  PrdDocument,
  PrdExportInput,
  PrdExportResult,
  PrdImportInput,
  PrdImportResult,
  PrdLinkMissionInput,
  PrdMissionLinkage,
  PrdPlanForMissionInput,
  PrdServiceOptions,
  PrdUpdateInput,
 } from './types.js';
 /**
 * PrdService is the SINGLE authority surface for PRD documents.
 *
 * Every mutation path (CLI wizard, `mosaic mission --plan`, import) routes
 * through this service; the YAML store under `docs/prdy/` is the authority and
 * exported Markdown is a generated view that no code path reads back.
 */
 // ── Typed errors ───────────────────────────────────────────────────────────────
 export class PrdError extends Error {
  constructor(
    message: string,
    readonly code: string,
  ) {
    super(message);
    this.name = 'PrdError';
  }
 }
 export class PrdNotFoundError extends PrdError {
  constructor(message: string) {
    super(message, 'PRD_NOT_FOUND');
    this.name = 'PrdNotFoundError';
  }
 }
 export class PrdUpdateError extends PrdError {
  constructor(message: string) {
    super(message, 'PRD_UPDATE_INVALID');
    this.name = 'PrdUpdateError';
  }
 }
 /** Structural refusal: the import payload failed schema validation. Nothing is written. */
 export class PrdImportInvalidError extends PrdError {
  constructor(
    message: string,
    readonly issues?: string,
  ) {
    super(message, 'PRD_IMPORT_INVALID');
    this.name = 'PrdImportInvalidError';
  }
 }
 /**
 * Conflict refusal: an existing PRD shares the imported id but the content
 * diverges. Carries a PROPOSED successor (existing version + 1) that is only
 * persisted via an explicit {@link PrdService.acceptSuccessor} call — import
 * never overwrites and never merges.
 */
 export class PrdImportConflictError extends PrdError {
  constructor(
    message: string,
    readonly existing: PrdDocument,
    readonly proposal: PrdDocument,
  ) {
    super(message, 'PRD_IMPORT_CONFLICT');
    this.name = 'PrdImportConflictError';
  }
 }
 // ── Service ────────────────────────────────────────────────────────────────────
 /** The generated-view label carried by every Markdown export. */
 export const PRD_GENERATED_VIEW_LABEL = 'generated view — do not edit';
 export class PrdService {
  private readonly projectPath: string;
  constructor(options: PrdServiceOptions) {
    this.projectPath = options.projectPath;
  }
  /** Create a new PRD (version 1, draft) in the authority store. */
  async create(input: PrdCreateInput): Promise<PrdDocument> {
    return createPrd({
      name: input.name,
      projectPath: this.projectPath,
      template: input.template,
      interactive: false,
    });
  }
  /** Read a PRD by id, or the most recently updated one. */
  async get(id?: string): Promise<PrdDocument> {
    const documents = await listPrds(this.projectPath);
    if (id === undefined) {
      const latest = documents[0];
      if (latest === undefined) {
        throw new PrdNotFoundError(`No PRD documents found under docs/prdy/ for this project`);
      }
      return latest;
    }
    const match = documents.find((doc) => doc.id === id);
    if (match === undefined) {
      throw new PrdNotFoundError(`PRD id not found: ${id}`);
    }
    return match;
  }
  /** List all PRDs in the authority store (most recently updated first). */
  async list(): Promise<PrdDocument[]> {
    return listPrds(this.projectPath);
  }
  /**
   * Apply section field patches and bump the content version.
   * Linkage entries are preserved; linkage writes do NOT bump the version.
   */
  async update(input: PrdUpdateInput): Promise<PrdDocument> {
    const doc = await this.get(input.id);
    for (const patch of input.sections) {
      const section = doc.sections.find((candidate) => candidate.id === patch.id);
      if (section === undefined) {
        throw new PrdUpdateError(`Unknown section id: ${patch.id}`);
      }
      for (const [field, value] of Object.entries(patch.fields)) {
        if (!(field in section.fields)) {
          throw new PrdUpdateError(`Unknown field "${field}" on section "${patch.id}"`);
        }
        section.fields[field] = value;
      }
    }
    doc.version += 1;
    doc.updatedAt = new Date().toISOString();
    await savePrd(doc);
    return doc;
  }
  /**
   * Record (or refresh) a mission ↔ PRD linkage on the PRD document.
   * Persisted in the YAML authority, so it survives restarts.
   */
  async linkMission(input: PrdLinkMissionInput): Promise<PrdDocument> {
    const doc = await this.get(input.prdId);
    return this.applyLinkage(doc, input);
  }
  /** Read back the mission linkages recorded on a PRD. */
  async listMissionLinks(prdId?: string): Promise<PrdMissionLinkage[]> {
    const doc = await this.get(prdId);
    return doc.missions;
  }
  /**
   * Mission planning path: create a PRD for a mission AND persist the
   * mission↔PRD linkage in a single authority write.
   */
  async planForMission(input: PrdPlanForMissionInput): Promise<PrdDocument> {
    const doc = await this.create({ name: input.name, template: input.template });
    return this.applyLinkage(doc, {
      prdId: doc.id,
      missionId: input.missionId,
      missionVersion: input.missionVersion,
      requirementIds: input.requirementIds,
    });
  }
  /**
   * Render the PRD to a Markdown GENERATED VIEW.
   *
   * The output carries source identity (PRD id + version + generated-view
   * label). It is written under `docs/prdy/<id>.md` and is NEVER read back:
   * the authority store only loads `.yaml`/`.yml` files, and no code path in
   * this package parses the exported Markdown.
   */
  async exportMarkdown(input?: PrdExportInput): Promise<PrdExportResult> {
    const doc = await this.get(input?.id);
    const content = renderMarkdown(doc);
    const filePath = input?.outPath ?? path.join(prdDirectory(doc.projectPath), `${doc.id}.md`);
    await fs.mkdir(path.dirname(filePath), { recursive: true });
    await fs.writeFile(filePath, content, 'utf8');
    return { filePath, content };
  }
  /**
   * Import a YAML PRD document.
   *
   * Structural validation (zod) happens BEFORE anything is proposed or
   * written. A structurally-valid import is persisted as `draft` — validity is
   * NOT approval. If an existing PRD shares the id with divergent content, a
   * typed {@link PrdImportConflictError} is thrown carrying a proposed
   * successor; the original authority document is left byte-identical on disk.
   */
  async importDocument(input: PrdImportInput): Promise<PrdImportResult> {
    const incoming = await this.readImportFile(input.filePath);
    const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
    if (existing === undefined) {
      const document = this.buildImportedDocument(incoming);
      await savePrd(document);
      return { kind: 'created', document };
    }
    if (canonicalCore(existing) === canonicalCore(incoming)) {
      return { kind: 'identical', document: existing };
    }
    throw new PrdImportConflictError(
      `PRD id "${incoming.id}" already exists with divergent content — refusing to overwrite. ` +
        `Proposed successor: version ${existing.version + 1} (draft). ` +
        `Accept explicitly with acceptSuccessor().`,
      existing,
      this.buildSuccessor(existing, incoming),
    );
  }
  /**
   * Explicitly accept a conflicted import as a successor version of the
   * existing PRD. Re-validates the source file before writing; the successor
   * is persisted with status `draft` (acceptance of the import is not approval
   * of the PRD) and the existing mission linkages are carried forward.
   */
  async acceptSuccessor(input: PrdImportInput): Promise<PrdDocument> {
    const incoming = await this.readImportFile(input.filePath);
    const existing = (await listPrds(this.projectPath)).find((doc) => doc.id === incoming.id);
    if (existing === undefined) {
      throw new PrdNotFoundError(
        `No existing PRD with id "${incoming.id}" — use importDocument to create it`,
      );
    }
    const successor = this.buildSuccessor(existing, incoming);
    await savePrd(successor);
    return successor;
  }
  // ── internals ──────────────────────────────────────────────────────────────
  private async applyLinkage(doc: PrdDocument, input: PrdLinkMissionInput): Promise<PrdDocument> {
    const entry: PrdMissionLinkage = {
      missionId: input.missionId,
      missionVersion: input.missionVersion,
      prdVersion: doc.version,
      requirementIds: input.requirementIds ?? [],
      linkedAt: new Date().toISOString(),
    };
    // One entry per mission: refresh in place if the mission is already linked.
    const index = doc.missions.findIndex((m) => m.missionId === entry.missionId);
    if (index === -1) {
      doc.missions.push(entry);
    } else {
      doc.missions[index] = entry;
    }
    // Linkage is mission-side metadata, not a content revision: bump the
    // timestamp only so ids/versions stay stable for consumers.
    doc.updatedAt = new Date().toISOString();
    await savePrd(doc);
    return doc;
  }
  private async readImportFile(filePath: string): Promise<PrdDocument> {
    let raw: string;
    try {
      raw = await fs.readFile(filePath, 'utf8');
    } catch (error) {
      throw new PrdImportInvalidError(`Cannot read import file ${filePath}: ${String(error)}`);
    }
    let parsed: unknown;
    try {
      parsed = yaml.load(raw);
    } catch (error) {
      throw new PrdImportInvalidError(`Import file is not valid YAML: ${String(error)}`);
    }
    try {
      return parsePrdDocument(parsed);
    } catch (error) {
      throw new PrdImportInvalidError(
        `Import file failed PRD schema validation: ${filePath}`,
        error instanceof Error ? error.message : String(error),
      );
    }
  }
  private buildImportedDocument(incoming: PrdDocument): PrdDocument {
    const now = new Date().toISOString();
    return {
      ...incoming,
      // The import lands in THIS project's authority store.
      projectPath: this.projectPath,
      // A structurally-valid import is not thereby approved.
      status: 'draft',
      version: 1,
      missions: [],
      createdAt: now,
      updatedAt: now,
    };
  }
  private buildSuccessor(existing: PrdDocument, incoming: PrdDocument): PrdDocument {
    return {
      ...incoming,
      id: existing.id,
      projectPath: existing.projectPath,
      status: 'draft',
      version: existing.version + 1,
      missions: existing.missions,
      createdAt: existing.createdAt,
      updatedAt: new Date().toISOString(),
    };
  }
 }
 // ── Markdown rendering (generated view) ───────────────────────────────────────
 function canonicalCore(doc: PrdDocument): string {
  return JSON.stringify([doc.title, doc.template, doc.sections]);
 }
 function renderMarkdown(doc: PrdDocument): string {
  const lines: string[] = [
    '<!--',
    `${PRD_GENERATED_VIEW_LABEL}`,
    `source-of-truth: docs/prdy/${doc.id}.yaml (YAML authority)`,
    `prd-id: ${doc.id}`,
    `prd-version: ${doc.version}`,
    `generated-at: ${new Date().toISOString()}`,
    '-->',
    '',
    `# ${doc.title}`,
    '',
    `**Status:** ${doc.status} · **Version:** ${doc.version} · **Template:** ${doc.template}`,
    '',
  ];
  if (doc.missions.length > 0) {
    lines.push('## Mission Linkage', '');
    for (const mission of doc.missions) {
      const requirements =
        mission.requirementIds.length > 0 ? mission.requirementIds.join(', ') : 'none selected';
      lines.push(
        `- mission \`${mission.missionId}\` @ version \`${mission.missionVersion}\`` +
          ` (linked at PRD v${mission.prdVersion}) — requirements: ${requirements}`,
      );
    }
    lines.push('');
  }
  for (const section of doc.sections) {
    lines.push(`## ${section.title}`, '');
    for (const [field, value] of Object.entries(section.fields)) {
      lines.push(`### ${field}`, '', value.trim().length > 0 ? value : '_Not set_.', '');
    }
  }
  lines.push('---', '', `_End of generated view for ${doc.id} v${doc.version}._`, '');
  return lines.join('\n');
 }
@@ -19,13 +19,31 @@ export interface PrdSection {
  fields: Record<string, string>;
 }
 /**
 * Mission ↔ PRD linkage recorded on the PRD document (the YAML authority).
 *
 * `missionVersion` is the mission-side revision marker available to the CLI
 * (the gateway exposes `updatedAt` for missions — there is no numeric mission
 * version yet). `prdVersion` snapshots the PRD content version at link time.
 */
 export interface PrdMissionLinkage {
  missionId: string;
  missionVersion: string;
  prdVersion: number;
  requirementIds: string[];
  linkedAt: string;
 }
 export interface PrdDocument {
  id: string;
  title: string;
  status: PrdStatus;
  projectPath: string;
  template: string;
  /** Content revision counter. Bumped by updates and accepted imports. */
  version: number;
  sections: PrdSection[];
  missions: PrdMissionLinkage[];
  createdAt: string;
  updatedAt: string;
 }
@@ -36,3 +54,60 @@ export interface CreatePrdOptions {
  template?: string;
  interactive?: boolean;
 }
 // ── PrdService surface (single authority entry point) ─────────────────────────
 export interface PrdServiceOptions {
  projectPath: string;
 }
 export interface PrdCreateInput {
  name: string;
  template?: string;
 }
 export interface PrdSectionPatch {
  id: string;
  fields: Record<string, string>;
 }
 export interface PrdUpdateInput {
  /** Defaults to the most recently updated PRD. */
  id?: string;
  sections: PrdSectionPatch[];
 }
 export interface PrdLinkMissionInput {
  /** Defaults to the most recently updated PRD. */
  prdId?: string;
  missionId: string;
  missionVersion: string;
  requirementIds?: string[];
 }
 export interface PrdPlanForMissionInput extends PrdLinkMissionInput {
  name: string;
  template?: string;
 }
 export interface PrdExportInput {
  /** Defaults to the most recently updated PRD. */
  id?: string;
  /** Override the generated-view output path. */
  outPath?: string;
 }
 export interface PrdExportResult {
  filePath: string;
  content: string;
 }
 /** Discriminated result of a non-conflicting import. */
 export type PrdImportResult =
  | { kind: 'created'; document: PrdDocument }
  | { kind: 'identical'; document: PrdDocument };
 export interface PrdImportInput {
  /** Path to a YAML-serialized PRD document (NOT the generated Markdown view). */
  filePath: string;
 }
@@ -2,8 +2,8 @@ import path from 'node:path';
 import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
-import { createPrd, savePrd } from './prd.js';
+import { PrdService } from './service.js';
-import type { CreatePrdOptions, PrdDocument } from './types.js';
+import type { CreatePrdOptions, PrdDocument, PrdSectionPatch } from './types.js';
 interface WizardAnswers {
  goals: string;
@@ -11,20 +11,41 @@ interface WizardAnswers {
  milestones: string;
 }
-function updateSectionField(doc: PrdDocument, sectionKeyword: string, value: string): void {
+/**
-  const section = doc.sections.find((candidate) => candidate.id.includes(sectionKeyword));
+ * Translate wizard answers into section patches using the same keyword
 * matching the wizard always used (first section whose id contains the
 * keyword, then first field whose name contains it, else first field).
 */
 function buildWizardPatches(doc: PrdDocument, answers: WizardAnswers): PrdSectionPatch[] {
  const bySection = new Map<string, PrdSectionPatch>();
-  if (section === undefined) {
+  const add = (keyword: string, value: string): void => {
-    return;
+    const section = doc.sections.find((candidate) => candidate.id.includes(keyword));
-  }
+    if (section === undefined) {
      return;
    }
-  const fieldName =
+    const fieldName =
-    Object.keys(section.fields).find((field) => field.toLowerCase().includes(sectionKeyword)) ??
+      Object.keys(section.fields).find((field) => field.toLowerCase().includes(keyword)) ??
-    Object.keys(section.fields)[0];
+      Object.keys(section.fields)[0];
-  if (fieldName !== undefined) {
+    if (fieldName === undefined || section.fields[fieldName] === value) {
-    section.fields[fieldName] = value;
+      return;
-  }
+    }
    const existing = bySection.get(section.id);
    if (existing === undefined) {
      bySection.set(section.id, { id: section.id, fields: { [fieldName]: value } });
    } else {
      existing.fields[fieldName] = value;
    }
  };
  add('goal', answers.goals);
  add('constraint', answers.constraints);
  add('milestone', answers.milestones);
  return [...bySection.values()];
 }
 async function promptText(message: string, initialValue = ''): Promise<string> {
@@ -63,15 +84,10 @@ async function promptTemplate(template?: string): Promise<string> {
  return choice;
 }
-function applyWizardAnswers(doc: PrdDocument, answers: WizardAnswers): PrdDocument {
+/**
-  updateSectionField(doc, 'goal', answers.goals);
+ * Interactive PRD wizard. All writes go through PrdService — the wizard is a
-  updateSectionField(doc, 'constraint', answers.constraints);
+ * prompt layer, never a second writer path.
-  updateSectionField(doc, 'milestone', answers.milestones);
+ */
  doc.updatedAt = new Date().toISOString();
  return doc;
 }
 export async function runPrdWizard(options: CreatePrdOptions): Promise<PrdDocument> {
  intro('Mosaic PRD wizard');
@@ -82,20 +98,15 @@ export async function runPrdWizard(options: CreatePrdOptions): Promise<PrdDocume
  const constraints = await promptText('Key constraints');
  const milestones = await promptText('Planned milestones');
-  const doc = await createPrd({
+  const service = new PrdService({ projectPath: options.projectPath });
-    ...options,
+  const doc = await service.create({
    name,
    template,
    interactive: true,
  });
-  const updated = applyWizardAnswers(doc, {
+  const patches = buildWizardPatches(doc, { goals, constraints, milestones });
-    goals,
+  const updated =
-    constraints,
+    patches.length > 0 ? await service.update({ id: doc.id, sections: patches }) : doc;
    milestones,
  });
  await savePrd(updated);
  outro(`PRD created: ${path.join(updated.projectPath, 'docs', 'prdy', `${updated.id}.yaml`)}`);
@@ -0,0 +1,37 @@
 # Scratchpad — RI-4-001 One transitional PRD authority (RI-N3, #1275)
 - Objective: single PrdService authority in `@mosaicstack/prdy`; `mosaic prdy` and
  `mission --plan` become thin adapters; mission↔PRD linkage persisted on disk;
  Markdown export is a labeled generated view (never read back); import is
  validated/conflict-aware with typed refusals.
 - Budget: ~35K tokens (card cap). Baselines: prdy build/lint rc=0, 0 tests;
  mosaic build rc=0 (after root turbo build), lint rc=0, 1548 tests pass;
  root build rc=0.
 - Plan: (1) extend store schema (version, missions linkage) (2) PrdService +
  typed errors (3) wizard/cli route through service (4) mosaic adapters
  (5) contract specs both packages (6) gates (7) sabotage control (8) report
  to /var/tmp/ri-050/ri-4-001-report.md.
 - Decisions:
  - Linkage lives ON the PRD document (`missions` array) — one authority file,
    survives restart, no sidecar sync problems.
  - `version` = content revision of sections/status (bumped by update/import
    accept). Linkage writes bump `updatedAt` only, so ids/versions stay stable
    for the card's "stable ids/versions" contract.
  - Mission version marker = `mission.updatedAt` (gateway MissionInfo has no
    numeric version field).
  - Import reads YAML documents only — never the exported Markdown (keeps the
    "no code path reads exported Markdown" invariant).
  - Import of an existing id with identical core content → `identical` no-op;
    divergent → typed `PrdImportConflictError` carrying proposed successor
    (existing.version + 1, status draft, linkages preserved). Original bytes
    untouched until explicit `acceptSuccessor`.
  - `requirementIds` default `[]` at the mission command (no requirement
    selection UI yet) — service accepts ids when a caller has them.
 - Progress log:
  - [16:35] baselines captured (prdy 0 tests; mosaic 1548 after root build; root build rc=0)
  - [16:38] store schema v2 + PrdService + wizard/cli rerouted; prdy build/lint green
  - [16:40] mosaic adapters done; prdy spec 20/20 (found+fixed: import project-path leak, empty-store typed error, YAML timestamp coercion)
  - [16:44] mosaic specs 9/9 (fixed commander from:'user' argv, vi.mock hoisting, restoreAllMocks wiping factory mocks)
  - [16:45] all gates green; 4 commits (e291bfb, 2c5d208, a23826c, 540d6f1)
  - [16:46] sabotage: linkage write removed → prdy 3 fail / mosaic 2 fail, 1548/1548 pre-existing pass; restored byte-identically; re-green 20/20 + 1557/1557
  - [16:47] report written to /var/tmp/ri-050/ri-4-001-report.md — card complete
Author	SHA1	Message	Date
fargo	8d258e1d07	docs: finalize ri-4-001 scratchpad with verification evidence (#1275 ) ci/woodpecker/pr/ci Pipeline was successful Details	2026-08-17 16:48:39 -05:00
fargo	540d6f17d1	docs: ri-4-001 scratchpad for PRD authority card (#1275 )	2026-08-17 16:46:17 -05:00
fargo	a23826ccba	test(mosaic): RI-N3 contract specs for prdy and mission --plan adapters (#1275 ) - import paths: created/draft, typed refusal creates nothing, conflict refusal leaves bytes untouched, --accept-successor persists v+1 - export writes the labeled generated view; authority unchanged - mission --plan persists linkage readable by a fresh service instance; mission path and prdy path share the docs/prdy store with stable ids/versions	2026-08-17 16:46:14 -05:00
fargo	2c5d208691	feat(mosaic): route prdy and mission --plan through PrdService (#1275 ) - mosaic prdy becomes a thin adapter: --init/--update (wizard for TTY, service otherwise), --import with --accept-successor, --export - mosaic mission --plan persists the mission↔PRD linkage (mission id + version marker, PRD id + version) through the service instead of invoking the wizard as a second writer; non-TTY runs create non-interactively	2026-08-17 16:46:06 -05:00
fargo	e291bfb837	feat(prdy): add PrdService as the single PRD authority surface (#1275 ) - PrdService owns create/read/update/link/import/export; wizard and package CLI become prompt layers over the service (no second writer path) - PRD documents gain a content version and a missions linkage array persisted in the YAML authority store (survives restart); linkage writes do not bump the content version - exportMarkdown renders a labeled generated view (id + version + do-not-edit header) that no code path reads back; the store loads .yaml/.yml only - importDocument validates structure with zod before anything else, persists valid imports as draft (validity is not approval), and refuses conflicts with a typed PrdImportConflictError carrying a proposed successor; the original document stays byte-identical until acceptSuccessor - raw store writers (createPrd/savePrd) are no longer exported from the package entry point	2026-08-17 16:46:00 -05:00