@openrig/cli 0.6.5 → 0.6.6

package/daemon/docs/reference/chain-file-convention.md

@@ -50,13 +50,19 @@ Established chain names on the topology tree:
 - `LEARNED.md` — what a POSITION has learned; never shared or shipped as-is.
   A seat's LEARNED is identified by its PATH: the same seat name in two rigs
   is two different files.
-- `CULTURE.md` — norms layered into members at startup.
+- `CRAFT.md` — how work is done at that altitude (shipped at instance, rig and
+  seat), with `ORCHESTRATION-CRAFT.md` at rig level for orchestration practice.
+- `CULTURE.md` — team norms. Note that startup delivers the rig spec's own
+  `culture_file` (a path beside `rig.yaml`), not a `CULTURE.md` under
+  `topology.root`.
 
 ### The project tree
 
 Rooted at the workspace keys (`workspace.root`, `workspace.slices_root`).
 Chain names there: `SPEC.md` (intent in frontmatter composes up the chain;
-specification is a leaf property), `PROOF.md`, `PROGRESS.md`.
+specification is a leaf property), `PROOF.md`, `PROGRESS.md`. The walkers also
+read `NOTES.md` (or `MISSION_NOTES.md`), and fall back to `README.md` for a node
+without a `SPEC.md`.
 
 **Project-tree context cannot ship.** It describes what *you* are building —
 mission intent, slice specifications, proof contracts. No vendor can author it
@@ -70,8 +76,11 @@ defaults.)
 
 Before this convention the topology tree lived at `~/.openrig/shared-docs/rigs/`
 (design decision 2026-08-14: an arbitrary folder on one machine, not a product
-path). That location **stays readable** as a per-level fallback so existing
-rigs migrate instead of breaking — but every read that resolves there emits a
+path). That location **stays readable** as a per-level fallback for
+`rig context trace`, at the rig and seat levels, so existing rigs migrate instead
+of breaking. The refocus trace, `seat:` profile atoms and handover priming read
+only `topology.root`, so until migration they report those files as missing. Every
+read that resolves to the legacy location emits a
 named advisory (`legacy-topology-read: …`) stating the legacy source, the
 canonical destination under `topology.root`, and the config key. A silent
 legacy read is a defect. The legacy literal lives in exactly one helper per
@@ -93,9 +102,9 @@ reproduces the drift it was meant to catch. Run it; do not recall it.
 
 ## Shipped defaults and the curation path
 
-Included rigs (product-team first) ship sensible-default chain files at the
-applicable instance, rig, pod, and seat altitudes, installed under
-`topology.root` at rig-up.
+Included rigs ship sensible-default chain files under a `topology/` folder,
+installed under `topology.root` at rig-up. Today only `factory` ships one,
+with instance, rig and seat defaults; the installer also supports pod defaults.
 A shipped default is a **starting point** the occupying team appends to — it
 is never overwritten by a later rig-up (existing files win).
 

package/daemon/docs/reference/developing.md

@@ -9,6 +9,11 @@ external network, and an installed-package scenario (`scripts/run-pr-scenarios.s
 with one difference: `npm test` does not include the UI suite, which CI runs as
 `package-tests (ui)`. Run `npm run test:ui` for it.
 
+**In a fresh clone or worktree, run `npm ci`, then `npm run build`,** as CI's build-and-package and
+package-test jobs do (typecheck and repo-checks build only the daemon, through their scripts; see
+`CONTRIBUTING.md` and [worktree builds](worktree-builds.md)).
+Locally, `npm test` builds only the daemon, and `test:workspaces` and `test:ui` build nothing.
+
 ## Blocking gates (must pass before a candidate moves)
 
 | Gate | Command | Covers |
@@ -18,6 +23,8 @@ with one difference: `npm test` does not include the UI suite, which CI runs as
 | Repo scripts | `npm run test:repo` | daemon build, script self-tests, docs guard, skill mirror check, context-pack generation check |
 | Unit tests | `npm run test:workspaces` | `packages/daemon` + `packages/cli` + `packages/tui` |
 | UI unit tests | `npm run test:ui` | `packages/ui` vitest. NOT part of `npm test`, but every pull request runs it as `package-tests (ui)` (the `package-tests` matrix in `.github/workflows/tests.yml`) |
+| Installed-package scenario | CI only: `scripts/run-pr-scenarios.sh` | the installed package, a daemon restart and a seeded durability failure. The script refuses to run outside GitHub Actions unless given `--remote` with `DOCKER_HOST=ssh://…` |
+| Package file lists | CI only | records each package's published file list (`npm pack --dry-run`) |
 
 `npm test` runs `test:repo` and `test:workspaces`; `npm run test:ui` is the separate UI
 suite. Both sets are readable in the root `package.json` scripts.

package/daemon/docs/reference/edge-types.md

@@ -1,8 +1,7 @@
 # Edge Types Reference
 
-Version: 0.2.0
-Last validated against code: 2026-04-11
-Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/rigspec-instantiator.ts`
+Last validated against code: 2026-10-05, at main `fcaf1f8e`
+Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/rigspec-instantiator.ts`, `packages/daemon/src/domain/queue-owner.ts`
 
 ---
 
@@ -17,17 +16,18 @@ See `docs/reference/rig-spec.md` for the YAML syntax.
 
 ## Edge Kinds
 
-Five edge kinds are accepted by the validator:
+Five edge kinds are accepted by the pod-aware validator (the legacy flat-node format accepts only `delegates_to`,
+`spawned_by` and `can_observe`):
 
 | Kind | Accepted | Has Runtime Behavior | Description |
 |------|----------|---------------------|-------------|
-| `delegates_to` | yes | **yes — affects launch order** | Source delegates work to target |
-| `spawned_by` | yes | **yes — affects launch order** | Target was spawned by source |
+| `delegates_to` | yes | **yes — launch order and queue escalation** | Source delegates work to target |
+| `spawned_by` | yes | **yes — affects launch order** | Source was spawned by target |
 | `can_observe` | yes | no | Source can observe target's output |
 | `collaborates_with` | yes | no | Peer collaboration |
 | `escalates_to` | yes | no | Source escalates to target |
 
-## What Edges Actually Do Today (OpenRig 0.1.x)
+## What Edges Actually Do Today
 
 ### Launch ordering
 
@@ -36,10 +36,16 @@ Only `delegates_to` and `spawned_by` affect runtime behavior. They constrain the
 - **`delegates_to`**: source launches BEFORE target. The delegator must be up before the delegate.
 - **`spawned_by`**: target (parent) launches BEFORE source (child). The parent must be up before the child it spawned.
 
-This ordering is enforced in both `PodRigInstantiator` (initial launch) and `RestoreOrchestrator` (restore from snapshot). The code uses topological sort over the dependency graph — if there's a cycle, instantiation fails.
+This ordering is enforced in both `PodRigInstantiator` (initial launch) and `RestoreOrchestrator` (restore from snapshot). The code uses topological sort over the dependency graph — if there's a cycle, instantiation fails with `cycle_error` before the rig is created. A `delegates_to` or `spawned_by` edge from a member to itself counts as a cycle. Restore uses the same sort but has no cycle check of its own.
 
 All other edge kinds (`can_observe`, `collaborates_with`, `escalates_to`) do NOT constrain launch order.
 
+### Queue escalation
+
+`delegates_to` also names a seat's orchestrator for the queue: the source of the `delegates_to` edge into a seat. The
+wake ladder escalates an unacknowledged row to that orchestrator, and stuck-row findings and recovery go to it. A seat
+with no incoming `delegates_to` edge has no default orchestrator. `spawned_by` plays no part here.
+
 ### Graph visualization
 
 All edges are rendered in the UI topology graph. They create visual connections between nodes, helping the operator understand the team structure. Pod-local edges appear within the pod group; cross-pod edges connect across groups.
@@ -50,13 +56,15 @@ All edges appear in `rig whoami --json` output under `edges.outgoing` and `edges
 
 ### Attach hint heuristic
 
-The post-command handoff (the "Attach:" line after `rig up` and `rig restore`) uses edges to prefer the orchestrator as the default attach target. The heuristic looks for the first node with `delegates_to` outgoing edges.
+The post-command handoff (the "Attach:" line after `rig up` and `rig restore`) doesn't use edges. It names the first
+node, in creation order, whose session is running, or else the first node with a session name.
 
 ## What Edges Do NOT Do Today
 
 Edges do NOT currently:
 
-- **Route messages** — `rig send` can target any session, regardless of edges
+- **Route messages** — `rig send` can target any session, regardless of edges (queue escalation, above, is the one
+  daemon path that follows `delegates_to`)
 - **Enforce delegation** — an agent can communicate with any peer, not just its edge targets
 - **Control permissions** — there's no edge-based access control
 - **Affect transport** — `rig capture`, `rig broadcast`, etc. work based on session identity, not edge topology