@openrig/cli 0.5.5 → 0.5.7

package/daemon/docs/reference/product-journey-sdlc.md

@@ -0,0 +1,305 @@
+# Product-journey SDLC components
+
+This is a reusable menu for building the smallest complete user outcome. A
+mission or slice selects only the components its work needs and records their
+order in mission/slice YAML. This is **not a mode, pipeline, topology, rig
+shape, or mandatory gate set**. If no composition is present, use the light
+Part A flow in `sdlc-conventions.md`.
+
+## The doghouse and the moon base
+
+The **doghouse** is the actual product outcome the user asked for. A
+**missing door** is an implementation that may be polished internally but
+cannot perform its basic user job. A **moon base** is elaborate machinery—
+often guards, abstractions, proof ceremony, security theatre, or process
+scaffolding—that consumes most of the effort without making the doghouse work.
+
+Use that disclosure ladder in this order:
+
+1. Name the doghouse in one sentence, without process vocabulary.
+2. Exercise its door through the public surface before admiring internals.
+3. Repair the smallest missing product seam.
+4. Consider deeper machinery only when evidence shows the layer below is
+   causing the visible failure.
+5. Remove or decline anything that does not protect or deliver a named user
+   outcome.
+
+The same discipline works for a new mission and for rescuing one that drifted.
+In a new mission, it prevents the moon base. In a rescue, it finds whether a
+usable doghouse remains and separates it from machinery that should not be
+carried forward.
+
+## Component contract
+
+Every component below states:
+
+- **Use when** — the evidence that admits it.
+- **Skip when** — the cheapest reason not to run it.
+- **Input** — what the responsible agent must actually read or observe.
+- **Action** — the bounded work performed.
+- **Output** — the artifact or observable result handed to the next component.
+- **Stop** — the boundary that prevents the component expanding itself.
+- **Next** — the normal successor; YAML may choose another explicit edge.
+
+Component IDs are stable addresses. Their prose may improve without forcing
+mission YAML to change.
+
+## Component catalog
+
+### context.fresh-start
+
+- **Use when:** prior context may carry stale architecture, verdicts, or
+  implementation momentum.
+- **Skip when:** the current agent can independently state the user outcome,
+  starting candidate, and boundaries from primary sources.
+- **Input:** world install, mission/slice YAML, and the addresses it names.
+- **Action:** start or clear a session, load only the selected context, and
+  derive current identity and source state.
+- **Output:** a one-paragraph readiness statement naming role, user outcome,
+  starting candidate, and boundaries.
+- **Stop:** do not reconstruct old queue lore merely because it exists.
+- **Next:** `intent.recover` or `journey.choose`.
+
+### intent.recover
+
+- **Use when:** work already exists but may have drifted from its original user
+  intent.
+- **Skip when:** this is greenfield work with one current, unambiguous intent.
+- **Input:** the earliest authoritative intent, later mission/slice specs,
+  candidate code, and observed user behavior.
+- **Action:** distinguish requirements from later planner elaboration; identify
+  the smallest still-required outcomes and explicit anti-goals.
+- **Output:** a concise salvage map: keep, inspect, and not-required—never a
+  destructive verdict by itself.
+- **Stop:** do not treat prior review intensity or sunk cost as product value.
+- **Next:** `journey.probe`.
+
+### journey.choose
+
+- **Use when:** a new mission has intent but no proven product path yet.
+- **Skip when:** `intent.recover` already names the next smallest outcome.
+- **Input:** authoritative intent and current public product surface.
+- **Action:** select one end-to-end user journey whose completion provides
+  standalone value.
+- **Output:** one observable outcome plus its smallest credible public probe.
+- **Stop:** one outcome only; adjacent capability is another composition.
+- **Next:** `journey.probe`.
+
+### journey.probe
+
+- **Use when:** always, before product code is added or rescued.
+- **Skip when:** never; scale the probe down instead.
+- **Input:** the public CLI, API, UI, or other surface a real user operates.
+- **Action:** run the smallest disposable end-to-end journey and inspect its
+  effects, not merely its exit status.
+- **Output:** PASS with no code needed, or one concrete user-visible gap with
+  preserved evidence.
+- **Stop:** a passing journey does not authorize speculative hardening.
+- **Next:** finish on PASS; otherwise `depth.look-below` or
+  `build.minimal-gap`.
+
+### depth.look-below
+
+- **Use when:** the public failure recurs, crosses a component boundary, is
+  contradicted by lower-level state, or a surface patch would duplicate logic
+  already owned below.
+- **Skip when:** the failure is local, understood, and repairable at the public
+  seam without duplication; also skip when the only argument is “more robust.”
+- **Input:** one observed public failure and the immediately responsible seam.
+- **Action:** descend **one layer only**; state the causal hypothesis, name the
+  lower-layer observation that would falsify it, and inspect or probe that
+  layer.
+- **Output:** one of three depth decisions:
+  - `LOCAL` — repair the public seam;
+  - `BELOW` — repair the named load-bearing seam and replay the public journey;
+  - `HOUSEKEEPING` — repair environment/data/topology hygiene before changing
+    product code.
+- **Stop:** one descent per admission. A second descent requires new evidence
+  and a newly stated hypothesis. “While here,” generalized prevention, and
+  unrelated cleanup are out of scope.
+- **Next:** `build.minimal-gap`, `research.before-build`, or housekeeping.
+
+This component is the balance point. Refusing ever to look below produces
+surface patches and recurring defects. Looking below without an evidence gate
+produces a moon base. The aim is the first load-bearing seam, not the deepest
+possible explanation.
+
+### research.before-build
+
+- **Use when:** the causal hypothesis depends on an unstable external fact or
+  a product contract that cannot be derived locally.
+- **Skip when:** source, runtime state, and the public probe already establish
+  the mechanism.
+- **Input:** one answerable uncertainty and its decision consequence.
+- **Action:** acquire only enough primary evidence to decide the implementation
+  shape.
+- **Output:** decision, citations, and remaining uncertainty.
+- **Stop:** research ends when the implementation decision is supported.
+- **Next:** `build.minimal-gap`.
+
+### build.minimal-gap
+
+- **Use when:** a failed journey and causal seam are established.
+- **Skip when:** `journey.probe` passed or the finding is housekeeping rather
+  than code.
+- **Input:** the user-visible gap, depth decision, existing seam, and explicit
+  boundaries.
+- **Action:** add the shortest readable change that completes the journey,
+  reusing the existing product seam.
+- **Output:** one clean candidate and focused evidence of the failure changing
+  for the stated reason.
+- **Stop:** no new framework, security layer, schema, abstraction, or adjacent
+  verb unless the outcome cannot work without it.
+- **Next:** `qa.public-journey`.
+
+### qa.public-journey
+
+- **Use when:** a candidate claims a complete user outcome.
+- **Skip when:** never before integration; it may be held by the builder on a
+  tiny change only when independence was not selected.
+- **Input:** exact candidate, original public probe, and boundaries.
+- **Action:** run the journey from the user surface in a disposable context;
+  inspect resulting state and partial-failure behavior.
+- **Output:** CLEAR or one concrete mismatch.
+- **Stop:** QA does not redesign the product or demand unselected ceremony.
+- **Next:** `review.scope-maintainability` or back to `build.minimal-gap`.
+
+### review.scope-maintainability
+
+- **Use when:** independent review is selected for the outcome.
+- **Skip when:** the composition deliberately keeps a low-risk change within
+  the light single-agent path.
+- **Input:** exact candidate, intent, public QA evidence, and base diff.
+- **Action:** judge correctness, readability, necessity, reuse of existing
+  seams, and whether the public journey—not an internal proxy—works.
+- **Output:** CLEAR or a bounded source/product finding.
+- **Stop:** a reviewer may not ratchet rigor merely because prior review found
+  something; review the product, not the ceremony.
+- **Next:** `integrate.one-outcome` or back to `build.minimal-gap`.
+
+### integrate.one-outcome
+
+- **Use when:** the selected evidence for one outcome is complete.
+- **Skip when:** the candidate is not clear or its base moved incompatibly.
+- **Input:** exact candidate identity and selected QA/review results.
+- **Action:** integrate the smallest coherent outcome and keep unrelated
+  candidates separate.
+- **Output:** clean canonical source containing one additional user outcome.
+- **Stop:** do not batch unrelated salvage because it shares a release label.
+- **Next:** `runtime.adopt` or the next `journey.choose`.
+
+### runtime.adopt
+
+- **Use when:** the outcome needs installed-runtime or migration proof.
+- **Skip when:** source-level proof is sufficient and no live behavior changed.
+- **Input:** clean canonical commit, rollback boundary, and runtime SOP.
+- **Action:** build/package/install the exact commit, switch atomically, and
+  verify health plus continuity.
+- **Output:** exact live version and preserved rollback point.
+- **Stop:** adoption is deployment, not permission to change topology or data.
+- **Next:** `qa.installed-smoke`.
+
+### qa.installed-smoke
+
+- **Use when:** `runtime.adopt` ran or packaging/path resolution is part of the
+  product claim.
+- **Skip when:** no installed artifact or runtime behavior is in scope.
+- **Input:** exact live version and disposable public journey.
+- **Action:** exercise the installed command path and verify effects and
+  cleanup.
+- **Output:** installed-runtime CLEAR or one concrete mismatch.
+- **Stop:** do not convert a smoke test into fleet-wide monitoring.
+- **Next:** finish the outcome or return to `build.minimal-gap`.
+
+## Composition rules
+
+1. `mission.yaml` may declare the catalog and mission defaults.
+2. `slice.yaml` selects or overrides the components for that slice.
+3. Edges are explicit data. Array order is presentation, not dependency.
+4. Select the fewest components that honestly fit the work.
+5. A component may be held by the same seat as its neighbor unless independence
+   is an intentional property of the composition.
+6. YAML describes the work; it is not an enforcement engine and creates no
+   automatic gates.
+
+Repository-address example:
+
+```yaml
+sdlc:
+  catalog:
+    root: repository
+    address: docs/reference/product-journey-sdlc.md#component-catalog
+  components:
+    - id: journey.choose
+      owner: planner
+    - id: journey.probe
+      owner: qa
+    - id: depth.look-below
+      owner: builder
+      admission: evidence-gated
+    - id: build.minimal-gap
+      owner: builder
+    - id: qa.public-journey
+      owner: qa
+  edges:
+    - from: journey.choose
+      to: journey.probe
+    - from: journey.probe
+      to: depth.look-below
+      when: public failure needs causal discrimination
+    - from: journey.probe
+      to: build.minimal-gap
+      when: local gap is already established
+    - from: depth.look-below
+      to: build.minimal-gap
+      when: decision is LOCAL or BELOW
+    - from: build.minimal-gap
+      to: qa.public-journey
+```
+
+Resolve repository addresses from `git rev-parse --show-toplevel`. Use the
+`loading-addressable-markdown` skill for `path#h2-slug` and
+`path#h2-slug/h3-slug` addresses outside the context library.
+
+## Example compositions
+
+### Greenfield product journey
+
+`context.fresh-start → journey.choose → journey.probe →
+build.minimal-gap → qa.public-journey → review.scope-maintainability →
+integrate.one-outcome`
+
+Add `depth.look-below` only when the probe meets its admission rule. A new
+mission does not need rescue archaeology.
+
+### Drifted-mission rescue
+
+`context.fresh-start → intent.recover → journey.probe →
+depth.look-below? → build.minimal-gap → qa.public-journey →
+review.scope-maintainability → integrate.one-outcome`
+
+The question is not “which old commits pass review?” It is “which required
+user outcome works, what prevents the next one, and how little code completes
+it?”
+
+### Recurring cross-layer defect
+
+`journey.probe → depth.look-below → research.before-build? →
+build.minimal-gap → qa.public-journey → qa.installed-smoke?`
+
+The recurrence admits one causal descent. It does not authorize a general
+platform rewrite.
+
+## Blank-agent start
+
+An agent with only the base world install should:
+
+1. Read `mission.yaml`, then the active `slice.yaml`.
+2. Resolve the catalog address and only the additional addresses those files
+   name.
+3. State: **my role; the user outcome; the starting candidate; the
+   boundaries**.
+4. Follow the selected component edges and their stop conditions.
+5. If no composition exists, use Part A in `mission-slice-sop`.
+6. If current reality contradicts the YAML, stop treating the YAML as fact,
+   record the discrepancy, and re-derive from the public journey and source.

package/daemon/docs/reference/product-management-pass.md

@@ -0,0 +1,139 @@
+# The product-management pass — what runs above planning, before planners touch a mission
+
+Graduated 2026-08-28 from a working SOP born during live release preparation; the
+originating team's channel specifics stay in its playbook.
+
+## Why this layer exists (read this or the steps are ceremony)
+
+The build is a lossy compression pipeline: product intent → planner spec → builder
+code, and each stage is a narrower reader than the one above. Nothing leaks downward
+by proximity — a dimension the product owner's seat holds and does not WRITE AND
+ROUTE is deleted from the product, and the deletion is silent: the downstream agent
+invents a plausible replacement rather than raising a hand. This pass is the only
+point where product taste physically enters the pipeline. Its output is judged by one
+measuring stick:
+
+> A slice folder is ready when SPEC.md alone, plus only what SPEC.md explicitly
+> routes to, reproduces the design intent in a reader who has none of your context.
+
+## The steps
+
+1. **GROUND IN THE RAW MATERIAL.** Survey where the ideas actually live: owner intent
+   layers, prior-era designs, the conversations. Enumerate cheaply first (intent
+   frontmatter, indexes); read the centerpiece documents yourself; fan out readers for
+   breadth, requiring citation-bearing reports (claims with openable paths; status:
+   shipped / partial / designed-never-built). Never grep-and-hope.
+2. **SYNTHESIZE ONE SCOPE OF RECORD.** Theme; waves; binding design principles; an
+   explicitly-NOT-in list (decisions, not omissions); the owner-decision set, each
+   with a recommendation. Archive superseded planning where a cold reader cannot
+   mistake it for authoritative. Every other surface DERIVES from this document;
+   where they disagree, it wins.
+3. **PRESENT DECISIONS DECISION-READY.** One at a time, lettered, recommendation
+   first, records cited. The owner's ruling gates everything downstream —
+   mechanically where possible (a blocked-on anchor), never by memory.
+4. **MINT SLICES AT PLAN TIME** with real one-paragraph intents.
+5. **DEPOSIT THE DESIGN — the fidelity law.** Every design-bearing slice's SPEC.md
+   carries the full design contract INLINE: the owner's words verbatim, the settled
+   do-not-reopen decisions, the live evidence, the shape of done, the anti-goals. A
+   one-line intent is a ~20:1 lossy compression; building from it alone matches the
+   design only by coincidence. Design that happened in conversation is deposited at
+   mint time or it dies with the author's context window. Mechanical slices with
+   durable named seeds may stay thin — thinness is a per-slice judgment, never a
+   default.
+6. **ROUTE EVERYTHING — the spec is the router.** The downstream reader's world is
+   SPEC.md; their curiosity does not extend past it, and a file's existence is not a
+   route. The spec itself carries the complete per-slice reading list (the exact
+   sources YOU used, with one line of why each) and per-slice research routing
+   (which tool answers which question — including explicit NOs where outside
+   frameworks would contaminate an owner-designed model). Nothing load-bearing may
+   depend on a reader's initiative.
+7. **FRAME THE PLANNING PER SLICE.** In each spec: the planning-dial rung WITH its
+   reason (`docs/reference/planning-dial.md`); what matters most; the required output
+   shape. Author the research prompts for research-round slices yourself — the
+   context gate: prompts come from the agent who holds the product context;
+   execution can fan out. Constraints binding every spec are stated in the spec,
+   never assumed known.
+8. **THE THEORY-OF-MIND REREAD.** Before releasing the batch, reread each spec AS the
+   narrow downstream reader — an agent who got a queue ticket, will read this one
+   file, and will invent anything missing without asking. Every "but how would they
+   know X?" is a hole to fix now.
+9. **SEQUENCE AND GATE.** Waves file-disjoint; anything that must precede dispatch
+   gates it as a row dependency, never a remembered intention; elaboration batons
+   carry the dial assignments and route back per slice.
+10. **KEEP THE RECORD LIVE.** The owner-facing board re-derives from the scope of
+    record; corrections land in the governing document first and project outward.
+
+## The failure modes this pass exists to prevent (each observed live)
+
+- Thin intents shipped as if elaboration could recover fidelity the elaborator never
+  had.
+- Beautiful context written to disk but never routed — write-only artifacts.
+- Reading lists that were curated excerpts of the real source set.
+- Research needs known to the shaper but never assigned a tool or a question.
+- Dispatch before the gate; sequencing held in memory instead of a row.
+- Knowing the world at ten dimensions and writing for readers as if the missing
+  seven would leak through on their own. They do not. Route it or it is gone.
+
+## Addressing the wide-angle seat: context, never instructions
+
+When any seat sends findings, problems, or proposals to a wide-angle seat (an
+advisor, a product shaper), it frames them as CONTEXT ON THE TABLE — the problem
+articulated, the grounding, candidate solutions if it has them — and explicitly
+leaves the steering to the receiver. Never as instructions, even with a confident
+recommendation in hand. Why: narrow-aperture seats produce narrow solutions and
+default to imperative speech; a wide-angle seat that trusts the sender will comply,
+and that is exactly how narrow decisions leak into a product unsynthesized. The
+pattern converts the sender's intensity (deep, focused, current) into the receiver's
+synthesis (wide, cross-cutting, temporal). This is the inbound half of the fidelity
+law: outbound, the shaper deposits design so compression cannot eat it; inbound,
+senders frame as context so aperture cannot bypass synthesis.
+
+THE PROTOCOL IS BIDIRECTIONAL. Downward — orchestrator to builder — the same wire
+discipline applies in mirror: put the goal, the acceptance criteria, and the
+complete context ON THE TABLE, and leave the implementation steering to the
+receiver. An orchestrator that converts context into step-by-step orders bypasses
+the builder's synthesis exactly the way a narrow seat's imperative speech bypasses
+a wide seat's. Empowerment is delivered as context, never as instructions — in
+both directions.
+
+## Aperture narrows by default — and that is the point
+
+Do not read the above as "assign every seat an aperture." Agents inevitably narrow:
+heads-down on one kind of work, a seat specializes, and the narrowing IS the
+specialization effect — the system's core mechanism, never a flaw to correct.
+Widening a specialist diffuses what made them elite. Never set a narrow aperture
+intentionally; seats arrive at theirs on their own. The ONLY aperture you ever steer
+is the wide one: wide-angle is itself a specialization, and its defining discipline
+is MAINTAINING width against the same pull that narrows everyone else. State
+aperture in a role only when the role must hold altitude.
+
+## The topology pairing (blueprint note)
+
+A strong topology pairs an ORCHESTRATION seat (flow: dispatch, sequencing, capacity —
+wide across the board, narrow in the act) with a PRODUCT-SHAPING seat (taste:
+coherence, contracts, temporal judgment — wide across the product), each with its
+aperture stated in its role. The context-not-instructions rule is the wire protocol
+between them.
+
+## Price one layer lower — the right-layer check
+
+Before accepting the fix your hands reached for, price ONE LAYER LOWER. The tendency
+is to fix high — high fixes are easy to write and test — and narrow is sometimes
+exactly right: sometimes all you need is a band-aid. But sometimes you are setting a
+bone, and the tells are learnable:
+
+- **The bone tell:** the lower fix collapses several open problems at once, and is
+  often SMALLER than the patch — it deletes or reuses instead of adding.
+- **The band-aid tell:** the lower layer is stable, correct, and merely
+  inconvenient; the defect is genuinely local; nothing else downstream shares it.
+- **The floor:** there is a sweet spot. A fix below the primitives you own is
+  someone else's lane, and a new engine where composition suffices fails the
+  simplicity bar.
+- **The move, mechanically:** name the layer you instinctively chose; name the
+  layer below it; state what each fixes and what each leaves broken; choose with
+  the price visible.
+
+This is the vertical twin of the wide-angle lens above: where
+context-not-instructions protects synthesis across seats, ARE-YOU-AT-THE-RIGHT-LAYER
+protects it across layers — a question to ask of every fix, and one layer lower
+deserves a look every time.

package/daemon/docs/reference/release-boundary.md

@@ -0,0 +1,88 @@
+# The release boundary — housekeeping run once per fence
+
+A CHECKLIST OF JUDGMENT GUIDES, not gates: every item says WHY, most items are one
+act, and anything situational expires at the next boundary. Runs once per release
+fence, after the prior release's ceremony completes. Graduated 2026-08-28 from the
+working SOP; the graduating team's seat-specific ceremony details stay in its
+playbook.
+
+## 1. Seats — reset or re-prime, per each seat's continuity needs
+
+- **Builder, QA, and reviewer seats: FRESH GENERATIONS.** Graceful exit with a
+  deposit (recap where provisioned), then relaunch. Why, twice proven: accumulated
+  release context becomes noise that reads as knowledge, and long-running seats
+  carry stale injected catalogs — only a fresh launch carries current skills and
+  canon.
+- **Planning seats: MANAGED COMPACTION + RE-PRIME,** not fresh — planning continuity
+  is the seat's point; the post-compaction restore is exactly the width-restore case
+  the context machinery exists for.
+- **The continuity-bearing orchestration seat: STAYS.** Its memory is the release's
+  memory and the ceremony's custody. Known cost, accepted: its injected catalog
+  stays stale until its own next generation — the capability delta covers the gap by
+  content.
+- **Re-prime = the world walk + the current capability delta + the mission install**
+  per the mission-install convention (`docs/reference/mission-install.md`): the world
+  half restores where-you-are; the project half (five layers, two depth profiles,
+  paced pointer-walk) restores what-you-are-doing. Composing the packet by
+  improvisation is the trap this convention closed.
+- **THE CEREMONY IS THE EXPERIMENT.** Every act above runs on the product's own
+  primitives, so the ceremony doubles as their live test. Observe passively: what did
+  each re-primed seat's first natural turns reach for, and what broke? Findings land
+  in one dated observations file beside the boundary record.
+
+## 2. Memory — distill, never accumulate
+
+- Per-seat learned files: a distillation pass. The cut test: "has this changed a
+  decision recently?" Keep those; move the rest to a dated archive section in the
+  same file. A learned file at volume stops constraining and starts justifying.
+- Any shared agent memory: same pass, same test; retire entries the release
+  falsified.
+- The finished release's mission notes: SEALED AS RECORD, carried as nothing. The
+  new mission starts thin. Rules do not migrate; requirements do, via the plan.
+
+## 3. Queue — sweep by destination, disposition everything
+
+- Every seat sweeps its DESTINATION for open rows (wakes are unreliable; the sweep
+  is the read). Each open row from the finished release gets exactly one of:
+  done-with-receipt · carried-to-the-new-mission (re-filed against the new plan,
+  never dragged) · closed-superseded. Ghost obligations accumulate silently without
+  this — the measured specimen was a dozen cold rows against one seat.
+- Verify every closing-paper inheritance has a live intake row with an owner. Zero
+  orphans.
+
+## 4. Substrate — teardown as its own atom
+
+- Prune worktrees; remove session-scoped scratch trees; verify merged branches
+  deleted (merge receipts authorize).
+- Scratch homes and scenario roots in temp directories: swept.
+- Runtime installs: keep LIVE + LAST-KNOWN-GOOD; archive the hotfix chain;
+  disposition launcher backups.
+- Mid-release vendored-file backups removed once the release containing the real
+  fix is live.
+- Snapshots of torn-down topology: indexed in one line each, or deleted.
+
+## 5. Instruments and boards
+
+- The finished release's tracking and planning boards: FROZEN as records, labeled
+  so. The new mission gets fresh boards — source-of-truth markdown first, board
+  derived.
+- Frozen review criteria: archived beside their evidence, marked "available,
+  unweakened, not gates."
+- Capture ONE clean-box baseline receipt at mission start (load, process counts,
+  health tail latency) — the next performance question deserves a before.
+
+## 6. The capability-delta lifecycle (standing law)
+
+Each release's capability delta is authored at the fence and bound to the exact
+published cut. Canon absorbs its named items; the canon header then names the delta,
+which EXPIRES it — verify the expiry fired, and never cite an expired delta. The new
+release's delta obligations start at ITS cut. A delta that outlives its absorption
+is a stale teaching site wearing a version number.
+
+## 7. What deliberately does NOT happen at the boundary
+
+- No process migration: situational rules expired at the fence. The standing corpus
+  is the four checking principles — verify by effect · evidence at source · honest
+  verdicts including against yourself · never fabricate.
+- No re-litigating the finished release's verdicts; the sealed paper is the record.
+- No additions to this checklist without a lived specimen attached.