@openrig/cli 0.5.8 → 0.5.10

package/daemon/docs/reference/health-diagnosis.md

@@ -0,0 +1,305 @@
+# Agent-operated System Health diagnosis
+
+System Health can give a responsible agent one durable investigation packet when
+a configured detector needs interpretation. The packet preserves the finding,
+policy version, evidence, and current authority documents. It invites the agent
+to investigate beyond that selection, including its own contribution. It does
+not declare a pathology or perform corrective actions.
+
+## Enable a bounded diagnosis loop
+
+```sh
+rig health policy --json > effective-policy.json
+jq '.policy' effective-policy.json > health-policy.json
+# Edit health-policy.json: diagnosis.enabled=true and diagnosis.owner=<seat@rig>.
+rig health policy --file health-policy.json
+rig health diagnose                    # preview; no writes or wakes
+rig health diagnose --apply            # evaluate now and apply admitted actions
+rig health diagnosis list
+rig health diagnosis show <qitem-id>
+```
+
+The daemon checks enabled policy once per minute. `health policy` reports whether
+that check is scheduled and its last result, including errors. Ordinary `health`
+list/explain commands remain observational. Diagnosis defaults to disabled;
+ceremony amplification is the only default diagnosis trigger. A continuing
+episode keeps one qitem, receives at most one additional presentation by default,
+and shares an owner cooldown across episodes (one hour by default). A disposition
+stops re-presentation. Disabling policy stops automatic admission and presentation.
+Ownership changes do not silently reroute existing occurrences.
+Outside a managed seat, name the writer with `rig health --actor <name> ...`.
+Managed-seat transport identity takes precedence over that declared name.
+Only the occurrence's assigned owner may record its disposition or request human
+notification. Other agents can advise the owner; a policy-owner change does not
+grant custody of existing occurrences. Writes retain the sender's identity
+provenance on the queue transition.
+
+Policy controls detector enablement, ceremony/review/wake thresholds, source
+observation window and freshness, diagnostic owner, cooldown, re-presentation
+bound, and human-escalation conditions. Edit plain JSON and apply it with the
+command; unknown keys and invalid values refuse without changing the policy.
+Applied proposals and their predecessors are retained under the configured
+OpenRig home in `health/policy-history/`. The effective version also includes
+the existing `health.context_pressure.warning_percent` and `critical_percent`
+settings, which remain configurable with `rig config`. Their defaults are 95
+and 99. CLI/TUI finding explanations show the policy version used.
+
+## Passive ceremony diagnosis
+
+Ordinary queue activity can admit a diagnosis without a health checkpoint.
+The source discovers declared handoff families touched in the observation window,
+uses their explicit `mission:` / `slice:` tags, and collects exact transition IDs,
+normal project/mission/slice authority, progress and proof references, and workflow
+closure evidence. It never interprets Markdown or counts proof files, approvals,
+C1 pairing, commits, tests, or terminal rows as accepted product outcomes.
+
+At the configured traffic threshold (20 transitions by default), a fresh,
+complete family becomes `ceremony.stage=needs-diagnosis`, `status=indeterminate`,
+and `severity=info`. CLI/TUI call this **needs diagnosis**, not a confirmed
+warning. Enabled diagnosis policy admits one bounded packet even though the
+product denominator is unknown. Ordinary unavailable/stale detector records
+remain ineligible. Diagnosis and human-notification traffic are excluded from
+the numerator and cannot recursively generate another investigation.
+
+The agent reads the actual evidence, including beyond the supplied references,
+and resolves the semantic outcome granularity and consequence boundary. Use the
+existing disposition command with an optional `progress` result:
+
+```json
+{
+  "basis": "<current finding.ceremony.basis from diagnosis show>",
+  "conclusion": "established",
+  "outcomes": [{"id": "<distinct meaningful outcome>", "observedAt": "<time inside the measured interval>", "evidenceRefs": ["<normal proof path>"]}],
+  "boundedAuthority": false,
+  "boundary": "<selected SDLC boundary and why this outcome census covers the interval>",
+  "evidenceRefs": ["<inspected authority/evidence path>"],
+  "missingFacts": []
+}
+```
+
+Put this object in `progress` beside the existing verdict/steering/uncertainty
+fields. `established` affirms a complete census for the exact interval; an empty
+outcome list affirms zero outcomes, not failed discovery. `false-positive`
+clears the suspicion without inventing a denominator when no missing facts remain.
+A false-positive assessment that still names missing facts stays indeterminate
+and does not close the episode interval. `indeterminate` supplies
+no outcomes and names the missing fact in `missingFacts`. Required references
+must resolve inside the workspace; extra evidence beyond the initial packet is
+allowed. The receipt retains the actual actor, timestamp, identity provenance,
+source basis, and evidence hashes. A changed basis refuses a stale submission.
+Later evidence changes make confirmation indeterminate rather than preserving
+a false ratio. Outcome meaning remains attributed agent judgment.
+
+Only an established, current assessment permits a ratio. The projector computes
+it from the distinct listed outcomes and exact transitions; a qualifying ratio
+with no bounded-authority counter-signal becomes `confirmed` / `active` /
+`warning`. Proportionate or bounded-authority results clear the episode. An
+explicitly cleared assessment marks the end of that interval; sufficient later
+traffic in the same family starts a new episode. Repeated reads never advance
+these boundaries. One occurrence and the existing owner cooldown apply to each
+episode; a disposition stops repeated requests.
+
+This bounded source covers explicitly tagged mission work: at most 2,000 touched
+qitems, 200 roots, 1,000 members / 10,000 transitions per family, 200 workflow
+receipts, 200 declared slices, and 100 proof files per selected slice. Overflow
+refuses visibly. Context files are bounded to 64 KiB. A lineage beginning before
+the retained window remains indeterminate, with the missing interval named.
+Untagged or ambiguously mission-tagged work is outside this source's coverage;
+absence is not health. The packet includes missing context references so an agent
+can name or repair its own knowledge gap without manufacturing source truth.
+
+## Optional outcome-boundary checkpoint
+
+Live queue transitions do not, on their own, prove product outcomes or the
+authority for a bounded operation. At a meaningful outcome boundary, the agent
+holding those facts may submit a census for one qitem lineage and time window. Set `includeHandoffs: true`
+to follow its declared handoff descendants; this is the normal path for work that
+passed between seats. The root alone usually misses the review/return traffic.
+Prefer the existing proof/progress/outcome artifact as evidence. Do not add a
+checkpoint to each edit or message. This is a fallback for explicitly supplied evidence;
+normal activity uses passive diagnosis above. An existing checkpoint owns its
+lineage so the passive source does not create a duplicate episode.
+
+```json
+{
+  "schema": "openrig.health-checkpoint/v0alpha1",
+  "lineageQitemId": "<existing-product-qitem>",
+  "includeHandoffs": true,
+  "scope": {"type": "slice", "projectId": "<project>", "missionId": "<mission>", "sliceId": "<slice>"},
+  "startedAt": "<ISO timestamp>",
+  "observedAt": "<ISO timestamp>",
+  "transitionIds": "derive",
+  "productOutcomes": [
+    {"id": "<outcome-id>", "observedAt": "<ISO timestamp>", "evidenceRef": "<proof-artifact-path>"}
+  ],
+  "productCensusRef": "<artifact establishing the complete outcome census for this lineage/window>",
+  "boundedAuthority": {"applies": false, "evidenceRef": "<bounded-effect-authority assessment>"},
+  "sdlc": {"expectation": "<selected components and review boundary>", "evidenceRef": "<authority for that selection>"},
+  "authorityPaths": {
+    "project": ["<current project SPEC and project.yaml paths>"],
+    "mission": ["<current mission SPEC and mission.yaml paths>"],
+    "slice": ["<current slice SPEC and slice.yaml paths>"]
+  }
+}
+```
+
+```sh
+rig queue transitions <existing-product-qitem>
+rig health checkpoint --file checkpoint.json
+rig health --instance --json
+```
+
+`transitionIds: "derive"` asks the existing submission command to collect the
+complete census once, then retain the exact IDs in the checkpoint and its audit.
+The author supplies outcomes and their meaning, not a row-by-row bookkeeping
+ritual. An explicit ID array is also supported for sealed replay or a
+caller-supplied census. Later reads never silently extend either form.
+
+The daemon verifies that transition IDs are the complete census for that exact
+qitem and window, including all handoff descendants when selected. It does not
+infer shared lineage from similar names or seat names. The complete transition
+census may be assembled from the queue ledger; omitting a descendant refuses.
+Explicit mission/slice tags on counted family members must match the checkpoint
+scope; untagged descendants inherit the declared handoff relationship.
+The bound is 1,000 linked qitems and 10,000 transitions; an oversized family
+refuses rather than silently sampling it. Independent roots are separate censuses. It counts
+those transitions and the distinct, evidenced product outcomes, and explains
+both sides of the ratio, the literal gate-tag breakdown, and the selected SDLC
+expectation. These are custody/status transitions, not messages or judgments
+about whether each review was useful. A product outcome is a distinct evidenced
+user-visible result; commits, test runs, returns and fixes needed to achieve
+that same promised result do not each create another denominator unit. The
+census must state its outcome granularity and coverage. The same granularity
+must be used for positive and proportionate controls. An empty outcome list requires the same census evidence
+as a nonempty one. An unavailable product census is a null denominator: the explanation says
+no ratio was computed, rather than silently substituting zero or one.
+`boundedAuthority.applies=null` means unknown, never false.
+Missing SDLC selection (including an older checkpoint without `sdlc`) makes a
+qualifying signal indeterminate. Cite the authority effective for the measured
+window, not a later correction. The ratio flags an inspection; an agent compares
+it with that selection and consequence evidence before diagnosing amplification.
+Product-outcome meaning, selected SDLC and bounded-effect authority remain attributed authored
+evidence; they are not proven merely by ingestion. Findings label that source
+and use medium confidence. Required evidence references must resolve to nonempty,
+readable local files (at most 1 MiB) inside the configured workspace. Absolute
+paths and paths relative to that workspace are supported; other reference kinds
+(including section addresses) remain unavailable. Resolved evidence records carry
+a SHA-256; missing files and symlink escapes remain attributed claims but force
+indeterminate source truth and cannot admit a diagnosis. Availability is checked
+again on every projection; presence does not certify the artifact's meaning.
+This authority assessment is distinct from the
+project/mission/slice documents supplied to the diagnosing agent. Embedded
+context is limited to canonical `SPEC.md` and project/mission/slice YAML files
+at their corresponding work-tree nodes, at most 64 KiB each. Other paths and
+symlink aliases are reported unavailable without embedding their contents.
+Each entry retains its authority level. Project files must be at the configured
+project root; mission files must belong to the finding's mission; slice files
+must also have a sibling `SPEC.md` declaring the finding's slice ID (and matching
+mission when declared). A sibling slice or another mission is unavailable even
+when its filename is canonical. Without mission/slice scope, those authority
+levels remain unavailable.
+
+Checkpoints are audited under `health/checkpoints/history/`; replaying identical
+bytes writes nothing. Later censuses advance observation time. High-to-high
+observations retain episode identity; a clearing checkpoint and later recurrence
+produce a cleared episode and a new ID. Reads never update checkpoint state.
+Stale, unavailable, contradictory, clipped, or missing evidence cannot admit a
+diagnosis. No findings is not a healthy assertion. The current source bounds are
+200 lineages, 10,000 transitions and 1,000 product outcomes per checkpoint, and
+1 MiB per input. Unsupported or invalid sources fail visibly.
+
+## Investigate and record a disposition
+
+Read the exact evidence and the current authority. Trace where the pattern
+began, test whether your own actions amplified it, and distinguish another seat
+or stale guidance. A second opinion is optional. The packet is a starting point,
+not a closed evidence set.
+
+```json
+{
+  "verdict": "insufficient evidence",
+  "causalStart": null,
+  "steering": "Inspect the product-outcome census before changing work.",
+  "uncertainty": "The cited artifact does not yet establish the denominator.",
+  "evidenceRefs": ["<inspected-evidence-path>"]
+}
+```
+
+```sh
+rig health diagnosis record <qitem-id> --file disposition.json
+rig health diagnosis show <qitem-id>
+```
+
+Verdicts are `false positive`, `early real condition`, `established pathology`,
+`insufficient evidence`, or `resolved`. The disposition is retained on the
+diagnostic qitem's transitions and visible in CLI output and the queue. Recording
+it does not close or alter the underlying product work. Changed dispositions
+retain earlier testimony; exact replay is a no-op. A detector clearing is
+recorded separately from an agent declaring the problem resolved.
+
+## Human delivery
+
+An assigned agent may explicitly request human escalation:
+
+```sh
+rig health diagnosis notify <qitem-id>
+```
+
+It requires a registered `human.address` and an admitted `human.conditions`
+entry (`critical`, `established pathology`, or `confirmed ceremony`). The connector must be enabled
+and pass live readiness checks. The current connector implementation verifies
+Slack scopes and channel membership; the diagnosis service itself uses a
+transport-neutral readiness port. The existing gateway owns delivery policy
+and posting. One human request is retained per episode, and its actual delivery
+outcome comes from queue receipts. `pending` is never presented as `posted`.
+Inspect the returned qitem's transitions for the connector receipt. No periodic
+health check performs remediation. With `human.conditions=["confirmed ceremony"]`,
+the enabled diagnosis loop automatically requests one notification for an active,
+confirmed passive ceremony episode. Provisional, indeterminate, cleared, and stale
+episodes never notify. The existing readiness/gateway path owns the effect; an
+unready connector leaves a visible, deduplicated readiness receipt. Later checks
+may retry readiness but never create a second request for an existing episode.
+Read-only list/explain/preview commands never send.
+
+## Read-only consumers and calibration
+
+A consumer such as a later Herder plugin reads `GET /api/health` and
+`GET /api/health/:findingId`, or the identical `rig health --json` and
+`rig health explain <finding-id> --json` records. The record schema is
+`openrig.health/v0alpha1`; list metadata is `openrig.health-list/v0alpha1`.
+Preserve ID, status, policy version, time window, freshness, evidence and
+threshold together. There is no health score or implicit remediation authority.
+The default list excludes cleared records; explicit cleared queries and exact
+ID reads retain them while the source can still project them. A recurrence after
+clear receives a new episode ID. This is an on-demand projection, not a history
+store; a detail 404 does not prove resolution.
+
+Lists default to 100 and cap at 200, with `total` and `truncated` explicit.
+Ceremony findings take precedence before the cap so context pressure cannot
+hide the primary signal. Narrow a truncated query; do not certify the unseen
+remainder. Empty is not healthy, unavailable is not empty, and an indeterminate
+finding cannot authorize a diagnostic occurrence except the explicit, fresh
+`needs-diagnosis` passive candidate described above. An existing occurrence may
+receive one status-observation receipt when its source becomes indeterminate;
+that does not create another obligation or wake.
+
+Live sources supply context pressure, passive ceremony candidates and attributed
+assessments, plus optional ceremony checkpoints.
+Behavioral and epistemic categories intentionally have no detector. Review
+carousel, redundant wakes, stale directives and scope admission have typed
+evaluators and replay controls, but the live source does not infer their missing
+candidate-change, rescue, directive-conflict or admission-authority facts.
+Untagged work and undeclared relationships remain outside passive ceremony
+coverage; normal tagged work no longer requires a special outcome census. A small lineage below the configured threshold may still deserve an
+agent's inspection; the threshold is a conservative admission rule, not a
+definition of good process.
+
+`packages/daemon/scripts/probe-health-calibration.mjs` accepts a sealed replay
+export and output directory after daemon/CLI/TUI builds. It drives the compiled
+checkpoint/list/explain/diagnosis commands, renders the TUI, retains exact
+records and screens, compares database and filesystem effects around reads,
+and measures query cost against declared budgets. Every write uses a disposable
+home and database. Historical expected states must be grounded independently
+of the detector formula; incomplete outcome evidence is an indeterminate case,
+not a denominator of one. A calibration report describes its selected corpus
+and remaining blind spots, not a fleet-wide false-positive rate.

package/daemon/docs/reference/instance-layout.md

@@ -0,0 +1,106 @@
+# OpenRig Instance Layout
+
+An OpenRig instance keeps its managed state under one configured
+`$OPENRIG_HOME`. `rig daemon start` and direct daemon first start reconcile the
+same additive layout before the database is opened or the listener binds.
+
+```text
+$OPENRIG_HOME/
+  config.json             # typed instance settings; created as an empty object
+  state/                  # runtime-owned durable state
+  context/                # addressable context library (`context.root`)
+    system/
+      system-world.yaml   # selected baseline context + skill identities
+  skills/                 # managed skill catalog (`skills.root`)
+  workspace/              # project work tree (`workspace.root`)
+    SPEC.md                # project intent
+    project.yaml           # project context and skill selection
+    workspace.yaml         # project-location catalog
+    .gitignore
+    missions/
+    exhaust/
+  specs/                  # canonical instance spec library
+  topology/               # instance, rig, pod, and seat continuity tree
+  plugins/                # installed OpenRig plugins
+  run/                    # process coordination files
+  logs/                   # daemon and operation logs
+  transcripts/            # durable per-seat terminal transcripts
+  backups/                # operator-created recovery artifacts
+  secrets/                # local connector and host secrets
+```
+
+The initializer creates only missing managed entries. It never overwrites an
+existing file, and it checks every managed path before the first write. A path
+with the wrong type is reported by its exact location; unrelated user-owned
+content is preserved. A second run against an already-converged instance writes
+nothing.
+
+The workspace subtree is owned by the [Project Workspace
+Contract](project-workspace.md). The instance initializer calls that owner
+rather than carrying another copy of its file bytes. `skills/` and `topology/`
+are created as empty roots; their respective catalog and topology workflows own
+their contents.
+
+## Context library setting
+
+The addressable context library has one typed setting and one environment
+override:
+
+| Surface | Value |
+| --- | --- |
+| Config key | `context.root` |
+| Environment | `OPENRIG_CONTEXT_ROOT` |
+| Default | `$OPENRIG_HOME/context` |
+| Resolved property | `contextRoot` |
+
+The removed `context.packs_root`, `context.packsRoot`, and
+`OPENRIG_CONTEXT_PACKS_ROOT` spellings are refused with guidance to use
+`context.root`; they are not compatibility aliases. Bundle installation and
+`rig context add` both resolve the same configured landing root.
+
+## System World
+
+The System World is the instance-wide baseline selected before topology/role
+and Project World material. Its versioned manifest contains ordered context-pack
+references plus managed skill identities; it never contains authoritative skill
+bytes. The default manifest is installed additively at
+`$OPENRIG_HOME/context/system/system-world.yaml`.
+
+| Surface | Value |
+| --- | --- |
+| Config key | `context.system_world` |
+| Environment | `OPENRIG_CONTEXT_SYSTEM_WORLD` |
+| Default | `default` |
+| Resolved property | `systemWorld` |
+
+`default` selects the installed manifest, a safe relative or absolute path
+selects an explicit replacement, and `disabled` is an explicit off state.
+Missing or malformed selections fail; absence is never inferred as disablement.
+`rig context work-install --json` reports the effective state, source, manifest,
+context selectors, and skills. With `--runtime`, its managed skill loadout then
+combines System World, topology, and Project World selectors with provenance.
+
+For a pre-0.5.9 home, use the `openrig-upgrade` skill's
+`migrate-telemetry-state-0.5.9.mjs` helper as an Agent-Operated Migration. Its
+order is plan → `--apply-state` → separately activate the target runtime →
+paired new-root samples newer than any bounded legacy tail → `--verify` → the
+non-destructive finalizer `--apply-library`. During activation, runtime readers
+are canonical-first with legacy-fallback and a custom context-library root
+remains stable. Verification binds exact accepted tail bytes; finalization
+revalidates them, copies without overwrite, and switches config last. It never
+removes the legacy telemetry or library. `--rollback` reverses only helper-owned
+config, System World, empty-directory, and copied-library effects. The helper
+must stop rather than claim success if writer/reader convergence, resumed legacy
+writes, byte drift, collision, or any migration-owned path cannot be proved.
+`--help` prints the phase grammar without inventorying; no phase flag is the
+intentional read-only plan, and unknown options fail nonzero before plan or
+mutation.
+
+## Existing spec libraries
+
+Creating `$OPENRIG_HOME/specs` does not migrate existing launch-era specs.
+Upgraded installations may still have a separate legacy specs library that the
+runtime reads for compatibility. Treat the two-home state as an explicit
+limitation: use the live spec-library commands to determine where a spec is
+served from, and do not infer convergence merely because the canonical
+directory exists.

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

@@ -187,9 +187,19 @@ The layers compose from surfaces that already exist; no new mechanism is require
   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.
+- Named install profiles make that independent depth/ordering choice explicit.
+  `rig context profile world-public --situation fresh --runtime codex --profile codex-coverage
+  --rig <rig> --seat <seat> --mission <mission> --slice <slice> --json` is
+  delivery-free inspection: it reports the selected profile, ordered phases,
+  exact pieces, token estimates, hashes, and source provenance before anything
+  reaches a seat. The `codex-coverage` profile orders bootstrap → concrete
+  project/mission/role/task → coverage map; `guided` keeps the fuller authored
+  walk separately selectable. Both select from the same source graph.
 - 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.
+- Delivery: `rig walk <seat> --through-profile world-public --profile <profile>
+  --situation <situation> ...` applies the already-inspected profile;
+  `--through <files> --pace <interval>` remains the raw byte-walk path. Paced
+  sends naming addressed reads serve 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

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

@@ -52,9 +52,10 @@ mission YAML to change.
   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.
+- **Input:** identity, project/mission/slice YAML, and the selected addresses.
+- **Action:** load the selected context into a fresh session, or reorient the
+  current session from live sources. Clearing a seat requires its separate
+  continuity decision; selecting this component does not authorize it.
 - **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.
@@ -213,7 +214,8 @@ possible explanation.
 
 ## Composition rules
 
-1. `mission.yaml` may declare the catalog and mission defaults.
+1. `project.yaml` may declare project defaults; `mission.yaml` may select the
+   catalog and override those defaults for the mission.
 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.
@@ -290,16 +292,52 @@ build.minimal-gap → qa.public-journey → qa.installed-smoke?`
 The recurrence admits one causal descent. It does not authorize a general
 platform rewrite.
 
+## Resolve the selected path
+
+On a fresh start, restore, or new assignment:
+
+1. Derive identity with `rig whoami --json`. Resolve the project's work root from
+   the assignment/workspace binding; `rig config get workspace.root` locates the
+   configured work tree, which may differ from the seat's code checkout.
+2. Read `project.yaml` and its project-authority context. Follow its mission root
+   to the assigned `mission.yaml`, then its composition ref to the active
+   `slice.yaml`. Read the current intent and acceptance files those records name.
+   Do not choose a mission from an old onboarding packet or a folder's recency.
+3. Resolve SDLC selection in order: project defaults, mission defaults, then the
+   active slice's explicit selection/override. A narrower explicit selection
+   replaces the broader component list; it does not append every ancestor's
+   gates. Follow an addressed wave map for its membership, review model and
+   boundary; an explicit named-slice exception applies only to that slice.
+4. Read only the selected components and additional addressed context. Repository
+   references resolve from the code repository root; installed references from
+   `$OPENRIG_HOME/reference`; context-pack refs use `rig context get`. For a
+   Markdown `#section` address, use `loading-addressable-markdown` rather than
+   loading an entire unrelated manual. Expand the investigation when the task's
+   evidence requires it: the address map is a starting point, not a search limit.
+5. State briefly the user outcome, current role, candidate, selected path and
+   next completion boundary. No composition means the light Part A flow in
+   `sdlc-conventions.md#a1-the-flow-in-one-pass`. Do not author a
+   composition merely to have one, or mint QA, guard, review, lock or proof gates
+   because those roles exist. On a tiny change the builder can verify the whole
+   outcome; independent review happens only when selected.
+
+A missing referenced file is a named gap, not evidence of no selection. Inspect
+or ask the owner to resolve a consequential ambiguity; do not silently fall back
+from an explicitly selected rigorous path. An owner can explicitly amend the
+selection for named work; record that decision at the work's authority. Current
+command/source reality outranks stale YAML as a factual claim: record the
+mismatch, re-derive, and preserve the distinction between scope and observed state.
+
+Startup overlays, role guidance, available seats, old mode names and historical
+packets cannot add steps to this selection. They supply capabilities. Skills load
+when the selected work calls for them; there is no quiz, per-file ACK gate or
+universal preloading requirement.
+
 ## 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.
+Follow **Resolve the selected path** above before choosing work. For an authored
+wave, build and verify each slice with its local discipline and integrate serially
+where required; request independent review once when the authored wave boundary
+arrives. Do not start per-slice reviews while waiting. A separately selected
+rigorous slice retains its named checks. Review findings justify bounded repairs,
+not an automatic increase in process for the next round.

package/daemon/docs/reference/project-workspace.md

@@ -4,6 +4,9 @@ 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.
 
+This subtree is part of the wider [OpenRig Instance Layout](instance-layout.md).
+The instance initializer delegates these exact workspace bytes to this owner.
+
 ## Default Shape
 
 `rig config init-workspace` creates the default workspace at
@@ -11,48 +14,70 @@ without daemon-internal knowledge.
 
 ```text
 workspace/
-  README.md
-  STEERING.md
+  SPEC.md
+  project.yaml
+  workspace.yaml
+  .gitignore
   missions/
-    README.md
-    idea-ledger/
-      SPEC.md
-      NOTES.md
-      PROGRESS.md
-      slices/
-        capture-product-ideas/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-        triage-product-ideas/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-    handoff-loop/
-      SPEC.md
-      NOTES.md
-      PROGRESS.md
-      slices/
-        route-work-packets/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-        verify-loop-evidence/
-          SPEC.md
-          PROGRESS.md
-          PROOF.md
-          proof/
-  progress/
-  field-notes/
-  specs/
+  exhaust/
+```
+
+The scaffold is additive: it creates missing canonical entries and never
+overwrites existing files, including with the deprecated `--force` flag.
+`exhaust/` and local `.openrig/` runtime projections are ignored; authored
+project context and mission/slice files remain versionable. `workspace.yaml`
+is the project-location catalog. The project manifest exposes empty
+`install.context` and `install.skills` selectors for ordered Markdown
+addresses and stable managed-catalog skill IDs, but neither skill source nor a
+System World belongs in this tree.
+
+## Project-world install
+
+`project.yaml` may select project context and managed skills together:
+
+```yaml
+schema: openrig.project/v0alpha1
+kind: project
+install:
+  intent: SPEC.md
+  context:
+    - conventions.md
+  skills:
+    - repository-maintenance
 ```
 
+`install.context` contains project-relative Markdown addresses. `install.skills`
+contains stable skill identities only. Skill source bytes live in the single
+configured managed catalog (`skills.root`, default `$OPENRIG_HOME/skills`),
+never under the project or workspace. `rig context work-install --runtime
+<claude-code|codex>` resolves both parts; add `--apply-skills` to reconcile the
+selected exact bytes into `.claude/skills/` or `.agents/skills/` under the
+caller's current working directory. Use `--cwd` when the receiving agent works
+somewhere else; the project-world metadata root is never assumed to be its code
+working directory.
+
+The generated harness directories and `.openrig/skill-loadouts/` ownership
+receipts are projections, not source. Product repositories should ignore them.
+Reconciliation removes a deselected entry only when its current bytes still
+match OpenRig's last owned projection; unrelated and locally modified entries
+are preserved or reported as conflicts.
+
+Seats of the same runtime commonly share one working directory. Their topology
+selectors are retained per canonical seat identity and projected as a union, so
+starting one role cannot remove another role's skill. A changed projection is
+visible only to a fresh harness process; reconciliation reports that boundary
+instead of claiming a running seat hot-reloaded it.
+
+An installed project selection is also retained in that working directory's
+ownership receipt. A later seat start with no project-world input preserves it;
+an explicit install whose `install.skills` is empty clears it. This keeps
+"project not supplied" distinct from "project deliberately selects no skills."
+
 ## UI Mapping
 
 - `workspace.root` maps to the Project workspace.
+- `workspace.catalog_path` maps to the `workspace.yaml` project catalog.
+- `workspace.projects_root` is the default home for catalogued project worlds.
 - `workspace.root/missions/<mission-id>` maps to a Project mission.
 - `workspace.root/missions/<mission-id>/slices/<slice-id>` maps to a Project slice.
 - Mission `PROGRESS.md` frontmatter supplies the mission status badge when the
@@ -98,12 +123,13 @@ default setup contract.
 If Project shows a mission discovery warning:
 
 1. Run `rig config get workspace.root --show-source`.
-2. Run `rig config get workspace.slices_root --show-source`.
-3. Confirm `workspace.slices_root` points at a folder containing mission
+2. Run `rig config get workspace.catalog_path --show-source`.
+3. Run `rig config get workspace.slices_root --show-source`.
+4. Confirm `workspace.slices_root` points at a folder containing mission
    directories with `slices/` children.
-4. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the TUI
+5. 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
+6. If the workspace is missing, run `rig config init-workspace` after operator
    approval.
 
 No daemon restart is required for most config reads. Restart when changing