@openrig/cli 0.5.4 → 0.5.6

package/daemon/docs/reference/lore-routing.md

@@ -0,0 +1,173 @@
+# Lore routing — position knowledge by address
+
+Lore is knowledge earned by one durable position while doing its work. It stays
+under that position's seat tree and is composed by address when another artifact
+needs it. The value is the combination of the content and where it was learned;
+copying the bytes into a shared library destroys that distinction.
+
+This convention defines the item shape, stable address, composition grant, and
+the only path by which lore-derived content may leave the position boundary. It
+adds no resolver, source kind, curator role, or transcript-mining process.
+
+## Home, ownership, and stable address
+
+Each item is one Markdown file beneath the owning seat's `lore/` directory:
+
+```text
+<topology-root>/rigs/<rig>/seats/<seat>/lore/<stable-slug>.md
+```
+
+Resolve `topology.root` from configuration; never hardcode the root. The owning
+seat is the sole direct author. It writes as the durable position, not as a
+particular occupant or predecessor.
+
+The filename describes the situation or trigger and never contains a stage,
+date, occupant generation, or version. Its address is therefore stable:
+
+```text
+seat:lore/<stable-slug>.md
+seat:lore/<stable-slug>.md#situation
+```
+
+A stage change edits frontmatter and `date`; it never renames the file. Existing
+citations must continue to resolve after the change.
+
+## Required metadata
+
+Every lore item carries these fields from birth:
+
+| field | meaning |
+|---|---|
+| `taxonomy` | Exactly `lore`. This is the machine-readable privacy class. |
+| `stage` | Current epistemic maturity. Legal values come only from [`knowledge-maturity.md`, “Two encodings, one ladder”](knowledge-maturity.md#two-encodings-one-ladder); do not copy or extend that vocabulary here. |
+| `method` | How the owning position could know the claim: the observation, comparison, incident, or source method. |
+| `date` | UTC date-time of the current stage decision or substantive revision. Update it when `stage` changes. |
+| `position` | Canonical owning seat address, `<seat>@<rig>`. It names the position, never an occupant. |
+
+`taxonomy: lore` is required both in each item's frontmatter and on any
+manifest-bearing lore pack that serves it. A misspelling is not equivalent and
+must fail any machine pin that extracts the class.
+
+## Item template
+
+Start a situation-shaped item with this template. Replace every placeholder;
+`wip` is the starting label, while the authoritative vocabulary remains the
+citation above.
+
+```markdown
+---
+taxonomy: lore
+stage: wip
+method: "<how this position could know>"
+date: "YYYY-MM-DDTHH:MM:SSZ"
+position: "<seat>@<rig>"
+---
+
+# <Short situation or trigger>
+
+## Situation
+
+**Position:** `<seat>@<rig>`
+
+**Moment.** <What is happening when this knowledge becomes useful?>
+
+**Reflex.** <What tempting response is likely to be wrong?>
+
+**Instead.** <What should the reader do?>
+
+**Because.** <What evidence or failure made the difference?>
+```
+
+Facts may use `## Fact` instead when a fact genuinely is the transferable unit.
+Any H2 intended as a section-level attachment repeats the canonical `Position:`
+line so attribution remains visible when the resolver returns only that section.
+
+## Addressing and composition
+
+Lore uses the existing `seat:` grammar and an explicit rig-and-seat read grant.
+The address says which file or section to read; the grant says whose seat tree
+the address is relative to. No grant means no read.
+
+For an install, compose the whole item address (`seat:lore/<slug>.md`) so its
+frontmatter, taxonomy, stage, method, date, and position travel with the content.
+A composed piece must visibly retain:
+
+- the `seat` source label supplied by the resolver;
+- the owning `position` from the item's bytes; and
+- the `taxonomy: lore` class from both item and lore-pack metadata.
+
+Serving one seat's lore into another seat's install is allowed only when the
+caller deliberately grants the owning seat tree. The resulting piece remains
+attributed to that owner; the receiving seat does not inherit its identity.
+
+An attachment point is only a pointer paired with the owning position:
+
+```yaml
+lore:
+  address: "seat:lore/<stable-slug>.md#situation"
+  position: "<seat>@<rig>"
+```
+
+An attachment never embeds or copies the lore bytes. The reader resolves it
+with the named position's explicit grant when the deeper context is relevant.
+
+## Stage changes
+
+To change maturity:
+
+1. Edit only `stage` and `date` unless the claim itself also changed.
+2. Re-resolve the same `seat:lore/<stable-slug>.md` address.
+3. Confirm the address is unchanged and the new stage and date are visible.
+
+If a stage change would break the address, stop: that storage shape violates
+this convention. `superseded` and `retired` follow the semantics at the cited
+maturity home; no lore-specific alternatives are invented here.
+
+## The outward gate
+
+A lore artifact never crosses from rig-local position knowledge into a shared
+or shippable audience by copy, export, serving, or packaging. Grant-gated
+read-side composition inside the rig is not graduation and keeps the source
+address and position attached. Its content may inform a new outward artifact
+only through authored re-homing:
+
+1. The owning seat authors the destination artifact, or records an explicit
+   delegation to its author.
+2. The destination is written for its new audience in its own words; the lore
+   file itself remains byte-unchanged.
+3. The destination records the graduation event:
+
+```yaml
+graduation:
+  source_address: "seat:lore/<stable-slug>.md"
+  source_stage: "<stage at graduation>"
+  date: "YYYY-MM-DDTHH:MM:SSZ"
+  owner: "<seat>@<rig>"
+  delegation: "none | <who delegated to whom>"
+  warrant: "<why the content earned the new audience>"
+```
+
+4. If the destination is shippable, it must pass the public-substance admission
+   gate. Renaming, rewrapping, or declaring copied lore as another pack class is
+   laundering, not graduation.
+
+The source address, source stage, owner/delegation, date, and warrant make the
+move auditable from the destination. The source lore item is never edited merely
+to announce that another artifact graduated from it.
+
+## Privacy boundary
+
+Lore is rig-local position knowledge. Shippable projection and bundle paths must
+refuse `taxonomy: lore` structurally, independently of token deny-lists or content
+scanners. Existing containment protections for seat files remain in force.
+
+This convention deliberately does not create:
+
+- automatic transcript or memory mining;
+- a lore librarian, central curation queue, or review ceremony;
+- cross-rig lore sharing;
+- a new address grammar, resolver kind, or public export form.
+
+Growth is owner-authored and organic. A seat writes an item when lived work makes
+the situation worth preserving; consumers attach or compose it by address when
+their situation calls for it.

package/daemon/docs/reference/mission-install.md

@@ -0,0 +1,194 @@
+---
+doc: reference
+title: The mission install — the project half of agent onboarding
+stage: established
+warrant: >-
+  Minted 2026-08-28 from three lived installs run before this convention was written
+  (receipts preserved in the minting slice's proof directory): a full five-layer seat
+  rebuild with a verified correction round, a release-boundary re-prime of a whole team
+  at two depths, and a successor install composed entirely from a mission's own
+  artifacts. Confirmed by a three-leg research round: the anatomy maps 1:1 onto the
+  shipped three-source composition contract, push-composition is convergent practice in
+  independent agent systems, and the only measured causal evidence available supports
+  composing authored artifacts over generating summaries.
+sources:
+  - the minting slice's SPEC design-contract block (recorded direction, decisions, prototypes)
+  - the minting slice's research synthesis (machinery table, tensions, evidence weights)
+  - docs/reference/sdlc-conventions.md (the build conventions this composes with)
+---
+
+# The mission install
+
+An agent joining work needs two installs. The **world install** teaches the system it
+now lives in — what this place is, how to act, what it can do. The **mission install**
+teaches the project — what is being built, how it got here, where it stands, and what
+is theirs to do. This document is the convention for the second half. It applies to any
+project a mission tree can hold: software, a book, accounting, research.
+
+**The reader who cannot help you wrote this convention.** A freshly started or freshly
+cleared agent cannot pull context — it does not know what exists, so it cannot ask.
+Every rule below follows from that: the install is **composed on the agent's behalf and
+pushed**, piece by piece, by someone who already holds the project.
+
+## When to run one
+
+- A fresh seat joins a mission.
+- An occupant handover: the successor inherits the seat, then gets the project.
+- A release or phase boundary: every continuing seat re-primes on the new frontier.
+- A project switch: a seat moves from one mission to another.
+
+Always AFTER the world install. The mission install assumes a situated reader.
+
+## The five layers
+
+Compose every install from these layers, in this order. They are a skeleton, not a
+script — depth profiles (below) select how much of each layer a given seat receives.
+
+1. **PIECES** — the authored history and design: the artifacts that explain how the
+   project got to now. Composed by address from the mission tree, each piece carrying
+   its source path and content hash. Never paraphrased.
+2. **ARRANGEMENT** — how the pieces connect. This is the one layer whose content is
+   not on disk anywhere else: an authored recap by someone who held the work, stating
+   what joins the pieces, what to trust, and what supersedes what. If no arrangement
+   document exists, writing one is part of preparing the install — it is the
+   dispatcher's knowledge, deposited.
+3. **POSITION** — what this seat specifically has learned and holds: its accumulated
+   lessons file and its most recent recap. Position is private to the lineage; it is
+   installed, never published.
+4. **CONTRACT** — the current plan and the open decisions. This is the fastest-moving
+   layer, so every contract piece must carry its own `updated-at`, and any fact not
+   re-derived at compose time carries an explicit `UNVERIFIED` marker. A stale plan
+   misleads more than a missing one.
+5. **DERIVE-YOUR-OWN-DELTA** — the final walked piece assigns a **derive list**: the
+   volatile facts the installee must re-derive itself, each stated as the command that
+   derives it (never as a remembered value). The installee runs the list and writes a
+   **dated delta** — what is true now that the install did not say — as its first
+   artifact, homed beside the seat's recap. This is the layer that turns a briefing
+   into an instrument check.
+
+## Two depth profiles
+
+- **Planning-class seats get FULL depth**: the complete ordered read set across all
+  five layers, ending at the live work pointer (the current plan's own next item).
+- **Execution-class seats get HIGH-ALTITUDE depth**: a handful of addressed reads —
+  the project frame, the governing scope contract, the source index, the operating
+  playbook — plus layer 5. Slice-level depth deliberately arrives LATER, with each
+  routed work item, whose own spec opens with its full design contract.
+
+The situation (fresh, handover, boundary, switch) selects subsets over the layers;
+the seat class selects depth. Do not send everyone everything. Two invariants hold at
+every depth: **the arrangement layer is never skipped** (it is what tells the reader
+whom to trust), and **a profile slot with no matching artifact is never authored at
+install time** — fill it with a derived listing (add it to the derive list) or leave
+it empty and say so.
+
+## Delivery rules
+
+- **Push, composed on the agent's behalf.** The dispatcher composes; the installee
+  receives. One piece per message, paced, with room to absorb between pieces — a
+  concatenated dump of the same bytes is a failed delivery regardless of content.
+- **Pointer-walk by default**: for a world-installed seat, each paced message names
+  the artifact to read and frames the read as a prerequisite to the seat's own next
+  task. The seat executes the read itself; reading is the install.
+- **Byte-walk only where the seat cannot read** (no file access, cross-machine
+  delivery): then the walk carries the bytes, in pieces, never as one block.
+- **Ask for a reaction per piece** where consumption matters: one line stating what
+  the piece changes for the reader. A silent walk is unverified delivery.
+- **A pointer may be section-scoped.** When one file mixes install content with
+  reference material, the pointer names the sections to read and the sections that
+  are reference; the reader's reaction names the sections actually read. Splitting
+  the file is better when two consumers keep needing different subsets.
+
+## Composition, not generation
+
+The install **composes authored, cited artifacts. It never generates summary prose at
+install time.** A generated summary is a second source that drifts and cannot be
+trusted or verified; an authored piece carries its provenance. The one place authorship
+is created for the install is the arrangement layer — and that is deposited knowledge
+written by someone accountable for it, kept and reused, not regenerated per install.
+
+## The exclusion rule
+
+A mission tree accumulates material that is **reference, never install content**:
+incident residue, superseded planning, transcript archives, dead ends kept for the
+record. The install inherits a **cleaned** view — current truth plus the arrangement's
+account of how it got there. Excluded material stays addressable; the arrangement may
+point at it, but the walk never carries it. When preparing an install, sort every
+candidate piece: install content, or reference. If unsure, it is reference.
+
+## The layer-5 verification loop
+
+Layer 5 is a sequence, not a suggestion. Run all of it:
+
+1. The dispatcher's final walked piece assigns the derive list — each volatile fact
+   paired with the command that derives it — **and names the exact destination path
+   for the delta** (a fresh seat has no recap yet to sit beside; the dispatcher
+   decides the home, the installee does not guess).
+2. The installee runs every command and writes the dated delta at the named path.
+3. The dispatcher verifies the artifact **exists** (not that it is claimed).
+4. A second reader — anyone but the installee — checks the delta's **facts**. When
+   the project has only a dispatcher and an installee, the dispatcher performs the
+   fact check and the delta records that the check was self-performed — an honest
+   degradation, stated, never silent.
+5. A factual error triggers a re-derive round: the installee re-runs the commands,
+   corrects, and reseals the delta. The correction round is value, not overhead:
+   it verifies consumption and calibrates the instrument in one act.
+
+A volatile fact with **no deriving command** — one only a human or external party can
+settle — goes on the list anyway, marked `UNVERIFIED` with an explicit
+ask-instruction; the delta carries it forward unresolved rather than silently
+adopting a value.
+
+An install without a landed, checked delta is not complete. It is a broadcast.
+
+## The fidelity law
+
+Design detail that lives in conversation gets **deposited at mint time**. A work item
+whose spec holds only a one-line intent, when the real design filled a discussion, is
+a 20:1 compression — and building from it makes correctness a coincidence. The
+convention therefore names where deposited design lives: the work item's own
+**design-contract block** (or a DESIGN-INPUT file beside it). Layer-1 pieces point at
+that full-fidelity record, never at the compressed intent line.
+
+## The boundary
+
+**The mission install stops at the mission root.** Everything above it — what the
+wider system is, the team's shape, the culture — belongs to the world install, which
+runs first. Tracing above the project root is a separate tool for a separate question.
+One install, one tree.
+
+## Composing with the shipped machinery
+
+The layers compose from surfaces that already exist; no new mechanism is required:
+
+- Pieces and contract: one `--mission` grant spans the mission and its slices —
+  `rig context profile <pack-ref> --situation <fresh|handover|post-compaction> --mission <mission>`
+  composes addressed sections with per-piece provenance and content hashes. The
+  `--situation` flag is required and is a SEPARATE input from the depth profile:
+  situation says which composition menu applies (fresh boot, occupant handover,
+  post-compaction restore); FULL vs HIGH-ALTITUDE says how much of each layer the
+  seat class receives. Choose both, independently.
+- Position: the `--rig`/`--seat` grant serves the seat's lessons and recap.
+- Delivery: `rig walk <seat> --through <files> --pace <interval>` for byte-walks;
+  paced sends naming addressed reads for pointer-walks.
+- The delta: a dated markdown file beside the seat's recap; verified by reading it.
+
+Where these verbs are unavailable (a different toolchain, a plain filesystem), the
+convention still holds: compose by copying addressed sections with their source paths,
+deliver paced, assign the derive list, require the delta.
+
+## Quickstart for any project
+
+1. Sort the mission's artifacts: install content vs reference (the exclusion rule).
+2. Write or update the arrangement document — how the pieces connect, what to trust.
+3. Mark every contract piece with `updated-at`; mark underived facts `UNVERIFIED`.
+4. Choose the profile: planning-class full, or execution-class high-altitude.
+5. Compose the ordered piece list with provenance; deliver it paced, pointer-first.
+6. End with the derive list; require the dated delta; verify existence; second-read
+   the facts; re-derive on error.
+
+A project of any kind fits this: for a book, the pieces are the outline's history and
+voice decisions, the arrangement is how the drafts relate, the position is this
+editor-seat's lessons, the contract is the current chapter plan with its dates, and
+the derive list is "count the chapters, read the latest editorial notes, state today's
+word count" — facts the new agent must touch, not trust.

package/daemon/docs/reference/planning-dial.md

@@ -0,0 +1,55 @@
+# The planning dial — how much rigor a plan gets, chosen per piece
+
+Planning is a spectrum, not a binary. The build phase prices its care by wave
+composition; planning needs the same flexibility, or every piece gets one protocol —
+over-working the trivial and under-working the hard. Graduated 2026-08-28 from the
+working SOP that ran a full release; the lived examples behind each rung stay in the
+originating team's playbook.
+
+## The rungs — dial up by what the piece is
+
+- **P0 — mini-requirements + pointers.** A few observable outcomes and where to look;
+  the builder figures out the how. Right for simple, reversible, well-trodden work.
+- **P1 — authored spec.** Intent, mini-requirements, a failing-test-first proof
+  contract, declared territory. The default.
+- **P2 — plus a research round,** run BEFORE the spec freezes, never during the build.
+  The research prompt is authored by an agent who holds the product context (see the
+  gate below); execution may fan out to any agents — web legs, documentation legs,
+  code-reading legs in parallel. Research returns as CONTEXT with citations, never
+  prescriptions; synthesis against your own architecture and intent follows, and it
+  differs for greenfield (design the thing) versus brownfield (sharpen your approach).
+- **P3 — plus an adversarial pass.** A non-author who holds the product context
+  attacks the plan in both directions with the product goals as judge. Amendments land
+  with proof-contract teeth — a new or changed checkbox — never as prose advice.
+- **P4 — plus a blind design gate.** A from-scratch design is committed before reading
+  the priors, then diffed. Similar → proceed; significantly different → stop for a
+  design session with the owner.
+
+## The context gate
+
+Only agents with the product's world context installed may author research prompts,
+run adversarial passes, or weigh in on architecture questions. Execution researchers
+and builders need no such install — the agent CREATING their instructions must have
+it. The reason: research shaped by someone who does not know what the product is for
+returns answers to the wrong question, fluently.
+
+## What earns P2 or P3 — importance is not the test
+
+A piece earns **P2** when the spec would otherwise freeze on an unresolved external
+unknown — a feasibility door or an open design space only research can close. A piece
+earns **P3** when its failure mode is invisible to its own author: load-bearing
+substrate where a plausible, self-consistent plan would ship the exact disease it
+exists to kill. The discriminator is "would a wrong plan be expensive, hard to undo,
+and invisible from inside" — never "is this piece central." Importance without an
+unclosable unknown or an author-blind failure mode stays at P1. Planning is text-only
+work, so the dial's cost stays proportional: a targeted P2 can take minutes; a full
+P3 an hour or two — cheap against a wrong plan built.
+
+## Cost calibration (dated observations from the graduating team, 2026-08)
+
+A P2+P3 pass on the most load-bearing piece of a release took about two hours end to
+end and produced the most-attacked spec in the release before a line of its code
+existed. A P3 alone ran ~70 minutes and returned six findings, two behavior-changing.
+A targeted P2 resolved a feasibility door in ~5 minutes against primary sources and
+caught two defects in an already-in-flight candidate. The recurring lesson the rungs
+carry: run the research BEFORE the build dispatches, not during.

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/project-workspace.md

@@ -1,6 +1,6 @@
 # Project Workspace Contract
 
-OpenRig's Project UI is a file-backed view over a workspace root. The folder
+OpenRig's Project TUI is a file-backed view over a workspace root. The folder
 shape is intentionally simple so humans and agents can create or repair it
 without daemon-internal knowledge.
 
@@ -16,29 +16,35 @@ workspace/
   missions/
     README.md
     idea-ledger/
-      README.md
+      SPEC.md
+      NOTES.md
       PROGRESS.md
       slices/
         capture-product-ideas/
-          README.md
+          SPEC.md
           PROGRESS.md
-          IMPLEMENTATION-PRD.md
+          PROOF.md
+          proof/
         triage-product-ideas/
-          README.md
+          SPEC.md
           PROGRESS.md
-          IMPLEMENTATION-PRD.md
+          PROOF.md
+          proof/
     handoff-loop/
-      README.md
+      SPEC.md
+      NOTES.md
       PROGRESS.md
       slices/
         route-work-packets/
-          README.md
+          SPEC.md
           PROGRESS.md
-          IMPLEMENTATION-PRD.md
+          PROOF.md
+          proof/
         verify-loop-evidence/
-          README.md
+          SPEC.md
           PROGRESS.md
-          IMPLEMENTATION-PRD.md
+          PROOF.md
+          proof/
   progress/
   field-notes/
   specs/
@@ -51,8 +57,10 @@ workspace/
 - `workspace.root/missions/<mission-id>/slices/<slice-id>` maps to a Project slice.
 - Mission `PROGRESS.md` frontmatter supplies the mission status badge when the
   file root is allowlisted.
-- Slice `README.md`, `PROGRESS.md`, and `IMPLEMENTATION-PRD.md` frontmatter
-  supply display name, lifecycle status, mission id, and queue linkage hints.
+- Mission and slice `SPEC.md` frontmatter supplies intent, advisory sibling
+  build-order `depends_on`, lifecycle status, and queue linkage hints.
+- Slice `PROGRESS.md` is the durable acceptance checklist; `PROOF.md` and
+  `proof/` retain evidence paired to the SPEC proof contract.
 
 Mission and slice ids should be stable kebab-case strings. Keep slice ids
 unique inside the workspace so `/project/slice/<slice-id>` resolves without
@@ -93,7 +101,7 @@ If Project shows a mission discovery warning:
 2. Run `rig config get workspace.slices_root --show-source`.
 3. Confirm `workspace.slices_root` points at a folder containing mission
    directories with `slices/` children.
-4. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the UI
+4. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the TUI
    can read mission `PROGRESS.md`.
 5. If the workspace is missing, run `rig config init-workspace` after operator
    approval.