@openrig/cli 0.6.4 → 0.6.6

package/daemon/docs/reference/sdlc-conventions.md

@@ -1,8 +1,8 @@
 # SDLC conventions — the markdown control plane
 
 > **Source of truth:** this repo document is the living SSOT for the SDLC
-> conventions. Scaffold templates, the advisory scope audit, the
-> `mission-slice-sop` skill, and the shipped bootstrap overlay all point HERE —
+> conventions. Scaffold templates, the advisory scope audit and the
+> `mission-slice-sop` skill all point HERE —
 > they must not restate this document in full (restatement is how drift is born).
 
 OpenRig is a software factory the human steers from a high altitude. The human
@@ -37,7 +37,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
 | **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
 | **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
 | **BUILD** | **Part A, the simple flow** (below — the default) · **product-journey components** — a mission-selectable menu for greenfield work, drift recovery, public journey probes, one evidence-gated look at the layer below, minimal repair, independent QA/review, integration, and installed smoke; compose only what the work needs in mission/slice YAML, never as a new mode or mandatory pipeline. Full reference: `product-journey-sdlc.md` · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
-| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live on a durable queue row tagged `wave-map` + `format:wave-map-v1` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
+| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
 | **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence and bound to the exact candidate, then reconciled to the published cut. Expiry requires both the canon header naming the absorbed delta and a distinct successor delta existing; a draft header alone is insufficient. Verify the actual boundary event and stop citing an expired delta. Full statement: `release-boundary.md` §6. |
 | **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
 
@@ -46,7 +46,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
 > planning dial — `planning-dial.md` · the product-journey component catalog —
 > `product-journey-sdlc.md` · the wave model — `wave-sdlc.md` · the release
 > boundary (including the capability-delta lifecycle law) — `release-boundary.md` ·
-> the mission install — `mission-install.md` (lands with its own slice). The
+> the mission install — `mission-install.md`. The
 > summaries above remain the one-glance description; this document remains the SSOT
 > pointer for the whole menu.
 
@@ -99,14 +99,17 @@ Each slice directory carries:
     (numbered list). This is the human operator's first structured catchpoint;
     approval starts here.
   - **`## Proof contract`** — a checkbox list of promised deliverables (see
-    §3). The UI's DELIVERED section pairs each item with its proof.
-- **`PROGRESS.md`** — the slice's acceptance checklist: the durable
-  mission/slice-level to-do checked at acceptance. In-process steps stay in
-  the working agent's own todo tool.
+    B1). The UI's DELIVERED section pairs each item with its proof.
+- **`PROGRESS.md`** — the slice's current delivery state and retained outcome
+  log. Record material changes with links to proof; historical checkboxes are
+  testimony, not current acceptance authority. For a selected proof policy,
+  `rig proof show <mission>/slices/<slice>` derives current readiness from the proof contract
+  and attributed judgments. In-process steps stay in the working agent's
+  own todo tool.
 - **`PROOF.md`** — the retained proof summary, explicitly paired to the
   `SPEC.md` proof contract.
 - **`proof/`** — the proof-artifact directory. Curated canonical evidence
-  lands here via `rig proof` with valid C1 headers (§5).
+  lands here via `rig proof` with valid C1 headers (B3).
 
 Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
 readable indefinitely. New scaffolds do not create or mirror them, and repair
@@ -125,7 +128,9 @@ Part B or add a mandatory review gate.
 
 The three sections project into the UI's one review structure: a vertical
 stack of **INTENT → PLAN → DELIVERED**. A slice missing a section still
-renders (the projection degrades to a muted "—", never invents content) —
+renders (a missing Intent or Delivered source shows a muted "—", missing
+mini-requirements show "Not compliant · mini-requirements not authored";
+nothing is invented) —
 but it does not carry its weight in review.
 
 ## A3. Honesty rails (public surfaces + cited hashes)
@@ -206,24 +211,31 @@ are losslessness checks on the decompression from intent to delivery, not
 paperwork. Scaffolding emits the sections; it must never mint ceremony.
 ## A6. The audit (advisory, fail-open — always)
 
-`rig scope audit` (and the advisory rows in `rig workspace validate` /
-`doctor`) checks these conventions: the section headings present, the proof
-contract well-formed, `proof/` artifacts carrying valid C1 headers, UI slices
-referencing a mockup. Every finding **records and advises — it never blocks a
-write path and never changes exit semantics into a gate**. Unknown is
+`rig scope audit --mission <name>` (and the advisory `sdlc_convention_sections`
+row in `rig workspace doctor`) checks these conventions: the section headings
+present, the proof contract well-formed, `proof/` artifacts carrying valid C1
+headers, UI slices referencing a mockup. Convention findings are low or info
+severity, except an invalid C1 header on a `proof/` artifact, which is medium.
+All of them **record and advise — they never block a write path and never
+change the exit code**. (`rig scope audit` exits 1 only on high-severity
+structural findings, such as a missing `PROGRESS.md` or id.) Unknown is
 reported as unknown, not failure.
 ## A7. Where the knowledge lives (the four pointers)
 
 - **This document** — the SSOT.
-- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `PROGRESS.md` +
-  `PROOF.md` + `proof/` for every template kind; `rig scope mission create`
-  emits an intent-bearing `SPEC.md` + `NOTES.md`. Core emits only this
+- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `slice.yaml` +
+  `PROGRESS.md` + `PROOF.md` + `proof/` for every template kind (and registers
+  the slice in `mission.yaml` when that manifest exists; legacy missions
+  without one remain supported); `rig scope mission create` emits an
+  intent-bearing `SPEC.md` + `mission.yaml` + `PROGRESS.md` + `NOTES.md` +
+  `slices/` (plus `CAPABILITY-DELTA-v<version>.md` for a `release-X.Y.Z`
+  mission). Core emits only this
   mode-neutral shape; mode plugins add richer material through the extension
   seam rather than teaching core a mode.
 - **Skill**: `mission-slice-sop` teaches **Part A**, the light default. **Part B**
   is defined below and applies only when assigned — never self-selected.
-- **Bootstrap**: the shipped agent overlay points fresh seats at the skill
-  and this document at boot.
+- **Bootstrap**: the shipped `pm` rig culture points its seats at the skill
+  and this document; the generic `openrig-start.md` overlay no longer does.
 
 # PART B — THE RIGOROUS OVERLAY (assigned only)
 
@@ -263,7 +275,8 @@ deliverable, written as an observable outcome:
   that evidence it — that pairing is what the DELIVERED section renders, so
   the human never hunts through dozens of artifacts to find which one proves
   what.
-- **UI deliverables carry a planned mockup** (`plannedRef`): the planning
+- **UI deliverables carry a planned mockup** (`plannedRef`, written as an
+  inline image on the checkbox line, e.g. `- [ ] … ![mockup](mockups/review.png)`): the planning
   agent produces the mockup and attaches it to the locked set. A UI slice
   with no mockup in its locked set is an incomplete plan. Non-UI slices
   (backend, skills, markdown) have no mockup and no `plannedRef` — that is
@@ -280,14 +293,18 @@ append-only audit row land together):
 - **Plan-lock:** `rig scope slice approve <slice> --scope spec` — "the spec
   matches my intent; THIS artifact set is what gets built." Pins `SPEC.md`
   (and planned mockups, when present) out of everything else in the folder.
+  `--locked-artifacts "SPEC.md,…"` names the set explicitly instead; a
+  plan-lock on an unedited scaffold `SPEC.md` with nothing else to pin refuses.
 - **Proof-lock:** `rig scope slice approve <slice> --scope delivery`
-  (the default scope) — the terminal "this is done" sign-off; fires the
-  freeze.
+  (the default scope) — the terminal "this is done" sign-off. (It does not
+  render the frozen export; the approve result reports `freezeFired: false`.)
 
 Approval is freeze/sign-off — **never** proven-green. Proven-green requires a
-recorded verdict (a C1 proof artifact, §5); presence of an approval stamp does
+recorded verdict (a C1 proof artifact, B3); presence of an approval stamp does
 not assert the work was proven. `--on-behalf-of` records delegation honestly
-(the actor stays the real invoking session).
+(the actor stays the real invoking session). A second approve of the same
+scope refuses; `--re-approve --reason "<why>"` supersedes the stamp and keeps
+the prior one in the audit log.
 
 ## B3. Proof drops and the C1 header (closed sets)
 
@@ -320,9 +337,11 @@ that it LOOKED at the evidence. `--media` names the curated media files
 (relative to the slice's `proof/` dir — co-located, never absolute) this
 drop stands behind; the composer projects them into the DELIVERED items'
 proof set. Validation happens at drop time; the audit
-(§6) backstops artifacts that arrived by other paths. **Hand-placing files
-in `proof/` without a drop is the anti-pattern**: the deliverable stays
-unpaired and `unverified` in the DELIVERED view — always attach media via
+(A6) backstops artifacts that arrived by other paths. **Hand-placing files
+in `proof/` without a drop is the anti-pattern**: media alone pairs with
+nothing, so a deliverable with no covering proof artifact (one whose
+`evidences` names it) shows as `missing` in the DELIVERED view, or as current
+acceptance absent under a selected proof policy — always attach media via
 `--media` on a drop.
 
 ## B4. Role contracts (what makes the structure self-enforcing)

package/daemon/docs/reference/slack-app-setup.md

@@ -44,9 +44,15 @@ not fill in; if so, follow the form.
    SLACK_APP_TOKEN=xapp-...
    ```
 
-8. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
-   `rig slack verify`, then `rig slack enable`.
-9. Invite the bot to the channel you configured (`/invite @OpenRig` in that channel).
+8. Invite the bot to the channel you will use (`/invite @OpenRig` in that channel).
+   `rig slack verify` reports NOT ready until the app is a member.
+9. Register yourself as the human the connector delivers to, with a Slack binding that names
+   your Slack user ID (`rig gateway human add`; its `--help` shows the binding format).
+   Messages from Slack users who are not registered are not delivered. `rig slack enable`
+   needs a readable human registry: on a fresh install with no registry, or with an invalid
+   one, it is refused.
+10. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
+    `rig slack verify`, then `rig slack enable`.
 
 ## What the app asks for
 
@@ -58,8 +64,8 @@ groups:
   `rig slack verify` checks these.
 - **Feature scopes**: `files:read` (download attachments people send), `files:write` (upload
   attachments to Slack), and `app_mentions:read` (receive @-mentions of the app). `rig slack verify`
-  does **not** check these, so a READY from verify does not prove attachments or mentions will
-  work.
+  warns when one of these is missing (if Slack returns the granted scopes) but does not require
+  them, so a READY from verify does not prove attachments or mentions will work.
 
 If a feature scope was not granted, the effect differs by feature:
 
@@ -67,8 +73,8 @@ If a feature scope was not granted, the effect differs by feature:
   message with an attachment that could not be downloaded is still delivered, with the failed
   file named in it. A post whose attachment could not be uploaded still delivers its text, and
   the failure appears only in the daemon log (`rig daemon logs`).
-- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app, and
-  nothing in OpenRig reports that they are missing.
+- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app.
+  Only `rig slack verify` warns that the scope is missing; nothing reports the missing events.
 
 So after installing, compare the granted scopes Slack shows for the app with all six scopes that
 `rig slack manifest --json` lists.
@@ -76,6 +82,12 @@ So after installing, compare the granted scopes Slack shows for the app with all
 The app subscribes to messages in public channels it is a member of (`message.channels`) and to
 mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
 
+The manifest also turns on **Interactivity**, so the human can answer a decision's structured
+questions by clicking a button (`rig queue create --human-questions-file`). In Socket Mode the
+clicks arrive over the same socket, so no request URL is needed. An app created from an older
+manifest has Interactivity off: turn it on under **Interactivity & Shortcuts**, or the buttons
+will do nothing. A typed reply in the thread still answers the decision either way.
+
 ## What the connector does with the tokens
 
 The tokens stay in the env file you created. The connector reads them from that file and uses them
@@ -88,3 +100,42 @@ part of OpenRig.
 
 - `rig slack status` shows what is still missing, without contacting Slack.
 - `rig slack verify` checks the granted baseline scopes and channel membership with Slack.
+
+## Reconnect recovery and status
+
+The daemon scans available top-level messages in the configured channel after a
+Socket Mode connection and on its existing five-minute retry cadence. Recovered
+queue rows say **Recovered after a gap** and show the original Slack posting time.
+They use the same sender admission, routing, attachment handling, fixed identity
+and dead-letter path as live messages. A durable dead letter is custody of a
+failed delivery, not successful delivery.
+
+Recovery keeps a per-channel checkpoint across reconnects, restarts and channel
+switches. On upgrade it initializes once from the newest retained accepted
+channel landing; without such evidence it starts at feature adoption. **Older
+history is unknown.** New live messages never move the recovery checkpoint. A
+partial scan resumes its saved interval; only an exhausted interval advances the
+covered boundary. Each new interval ends five seconds before the local clock to
+allow recent messages to become visible; larger clock skew or visibility lag is
+not covered by that margin. A corrupt or unreadable checkpoint leaves recovery unavailable
+and preserves the existing file; live inbound continues.
+
+Each pass admits at most four pages, 100 entries and 15 seconds of work, with a
+five-second history-request ceiling. An already admitted attachment/landing keeps
+its owner until it settles. Rate limits retain Slack's Retry-After across restart.
+Transport and server failures use a five-second backoff unless Slack supplies Retry-After.
+When Slack reports a plan history limit, recovery still lands the available page
+and advances normally, retaining an older-history limitation in status across restarts.
+Missing bot credentials, history scope, membership, retention limits and API
+failures appear as recovery limitations. No additional scope is required to keep
+live delivery working. Thread-reply catch-up and dead-connection detection remain
+outside this recovery scope; global chronological order is not promised.
+
+`rig slack status` retains local configuration checks and adds a bounded daemon
+snapshot: socket state/generation, last event, recovery interval/state/reason,
+retry time and accepted/dead-lettered recovery counts since the connector last
+started (they reset when it is enabled or disabled, and when the daemon restarts).
+Human-readable coverage and pending bounds use ISO timestamps; JSON keeps Slack timestamps.
+The status read calls no Slack API and starts no scan. If the daemon cannot be
+observed, local configuration remains visible and live state is unknown. A
+connected socket or valid configuration alone does not prove end-to-end delivery.

package/daemon/docs/reference/stream-classifier-worker.md

@@ -61,12 +61,19 @@ The smaller of `--limit` and the configured request maximum bounds the wake.
 Unknown answers remain null; a wholly unknown answer abstains. Invalid model,
 provider, answer keys, choices, probabilities or response bytes reject the whole
 answer. Probability sums retain the strict 0.001 tolerance; there is no rounding
-repair or partial salvage. Unavailable/invalid provider work stops that run with
-no classification write. Inspect the returned attempt state: terminal abstentions
+repair or partial salvage. Unavailable/invalid provider work, Ctrl-C or SIGTERM
+stops that run with no classification write; when the classifier returns that
+outcome, the item in hand is recorded as an abstention, final for that classifier
+version, taxonomy version and evidence epoch. The worker's own deadline (the lesser
+of the request timeout and the time left before the next lease heartbeat) is
+different: when it fires
+first, the attempt is recorded as `error` with a retry time, or `exhausted` once the
+retry budget is spent, not as an abstention. Inspect the returned attempt state: terminal abstentions
 are not reopened, and failed/unknown daemon writes must be reconciled through the
 existing ledger. Never change the evidence epoch merely to retry an experiment.
 
-Disable is checked before each call and before applying its result. A separate
+Disable, a changed `--max-requests` or `--timeout-ms`, or an unreadable configuration
+is checked before each call and before applying its result, and stops the run. A separate
 disable command cannot cancel an already forwarded remote request; its late
 result is discarded, with the existing deadline bounding the wait. Ctrl-C or
 SIGTERM requests immediate cancellation of the foreground run. An uncooperative
@@ -169,7 +176,8 @@ source churn can require repeated preparation and is not a throughput claim.
 Each wake processes at most `--limit` items (1–100; default 20), starting with the
 oldest eligible work rather than relying on a lossy notification cursor. Durable
 terminal attempts stay excluded. A new candidate version does **not** authorize
-another pass: only an owner-selected evidence epoch changes that attempt identity.
+another pass: only a new classifier version, taxonomy version or owner-selected
+evidence epoch changes that attempt identity.
 Retain the candidates output beside the decisions and result so its version is
 reproducible. The CLI does not keep a second local ledger.
 
@@ -197,6 +205,9 @@ capture. Retained-no-write is a separate event, never delivery evidence.
 
 Activation requires explicitly supplied `OPENRIG_SHADOW_CAPTURE` JSON at a later
 authorized daemon start. Absence or invalid configuration leaves capture disabled.
+Daemon start checks only that `destination` is an absolute normalized path and the
+numeric ceilings; the private-directory checks and exclusive file creation happen
+at the first drain, and a failure there stops the sink.
 This document supplies no live destination or activation instruction. Required
 fields and engineering ceilings are:
 
@@ -218,8 +229,9 @@ observation; explicit production configuration supplies each value.
 
 `rig project shadow-status` only inspects configuration/counters.
 `rig project shadow-drain` asks the existing HTTP service to drain up to 64 rows;
-it requires an actor and never enables capture. No background drain timer is added.
-`rig project shadow-stop` disables new enqueueing immediately, finishes any active
+it requires an actor (outside a managed seat, name one with `--actor <name>`)
+and never enables capture. No background drain timer is added.
+`rig project shadow-stop` (which needs an actor the same way) disables new enqueueing immediately, finishes any active
 drain and the finite retained queue, then closes the sink. Repeated stop is
 idempotent; it cannot enable capture or delete the existing archive. Existing
 quota and sink-failure losses remain counted. A slow disk can leave stop pending;
@@ -236,8 +248,9 @@ start another writer. Overflow drops new observations. Capacity exhaustion stops
 the sink. Errors stop writes, count losses and preserve any partial file; failed
 batches are not replayed. `reservedRecords/Bytes` include attempted writes, while
 `completedRecords/Bytes` count successful appends. `drained` means removed from
-the observer, not necessarily persisted. Queue count drops, byte-bound drops,
-record errors, missing/unavailable captures and sink failures remain separate.
+the observer, not necessarily persisted. Queue drops (count-bound and byte-bound
+together in `dropped`; `droppedBytes` adds the bytes of byte-bound drops), record
+errors, missing/unavailable captures and sink failures remain separate.
 
 Live collection, private destination/retention selection, corpus labels, hosted
 calibration, native placement, package/install proof and independent visible /

package/daemon/docs/reference/telemetry.md

@@ -0,0 +1,114 @@
+# Finite telemetry metadata
+
+`rig telemetry` reads one bounded page of retained history from the daemon. It is
+useful for collectors and operators that need a cursor without reading OpenRig's
+private SQLite schema. It neither watches nor automatically drains history.
+
+```sh
+rig telemetry events --json
+rig telemetry events --start retained --node NODE_ID --limit 128 --json
+rig telemetry events --start retained --rig RIG_ID --json
+rig telemetry events --cursor CURSOR --node NODE_ID --json
+rig telemetry transitions --start retained --qitem QUEUE_ITEM_ID --json
+rig telemetry tenures NODE_ID --json
+```
+
+Events and transitions initially return an empty checkpoint at the current high
+watermark, with `historical_events_not_read` or `historical_transitions_not_read`.
+Use `--start retained` to request the retained past. Tenures start with the newest
+32 records for the immutable node ID, with a descending continuation when needed.
+An empty match set can still have more source records: check `page.hasMore` and
+`page.nextCursor`. The cursor binds the stream and filters; retain the same filter
+options when continuing. Do not use `--start` with `--cursor`.
+
+## HTTP and envelope
+
+These reads use the daemon's existing browser/access boundary:
+
+| GET path | Query parameters |
+| --- | --- |
+| `/api/telemetry/v1/events` | `cursor`, `limit`, `start=latest\|retained`, `nodeId`, `rigId` |
+| `/api/telemetry/v1/queue-transitions` | `cursor`, `limit`, `start=latest\|retained`, `qitemId` |
+| `/api/telemetry/v1/nodes/:nodeId/tenures` | `cursor`, `limit` |
+
+The envelope contains `schemaVersion: 1`, `stream`, `observedAt`, `source`, `rows`,
+`page`, and `coverage`. Integer IDs are **decimal strings**, including values larger
+than JavaScript's safe integer range. `--json` preserves the complete envelope.
+
+- Events: `seq`, `rigId`, `nodeId`, `type`, `originalTimestamp`, `createdAt`.
+- Transitions: original `transitionId`, `qitemId`, `state`, `actorSession`,
+  `identityProvenance`, `closureReason`, `closureTarget`, `originalTimestamp`, `createdAt`.
+- Tenures: `nodeId`, `generationOrdinal`, `generationUuid`, `kind`,
+  `nativeSessionIdAtBoot`, `originalTimestamp`, `bootAt`.
+
+Normalized `createdAt` and `bootAt` are explicit UTC or null with a named gap.
+SQLite timestamps without a timezone are interpreted as UTC. Original timestamps
+remain available. Streams have separate sequences; their IDs do not establish
+cross-stream causal ordering. Event type alone establishes no readiness, activity,
+or native-exit verdict. Repeated same-state transitions remain separate records.
+Null boot identity stays unknown, and a tenure has no inferred end time. Historical
+records are never joined to today's owner or node name.
+
+`page` reports the requested boundary (`requestedAfter` or `requestedBefore`),
+`lastScanned`, fixed `through`, `retainedHighWatermark`, `hasMore`, `nextCursor`,
+`restartCursor`, and `fetched`, `scanned`, `filtered`, `withheld`, `returned`,
+`capReason`. New writes above a window's `through` wait until that window is
+complete. A complete ascending checkpoint opens another finite window on its next
+use. Descending tenure history ends with a null continuation.
+Its cursor also retains the first observed lower ordinal, so disappearance of that
+older range produces a named gap even when some records remain on the final page.
+
+## Bounds and privacy
+
+The default/max source page is 128 rows; tenures default to 32. Sparse filters run
+**after** that bound, so matching nothing still advances over scanned records.
+Transitions fetch at most 128 candidates from each of the active/archive tables
+in one read snapshot, then process at most 128 distinct ordered IDs. Equal
+projected duplicates collapse; conflicting IDs are withheld with a named gap.
+Physical `fetched` can therefore exceed logical `scanned`.
+
+Responses are at most 128 KiB, with a 4 KiB projected-record cap. SQL guards bound
+fields before fetching them: identifiers 256 bytes, timestamps/enums 128 bytes,
+and actor/closure references 512 bytes. Oversized fields become null with an
+`oversized_field` gap, and non-text values become null with an `invalid_type` gap;
+they are never truncated into a different identity. A record
+whose JSON escaping still exceeds 4 KiB is withheld and counted. A response-byte
+stop leaves the next unprocessed record for the continuation. Gap details are
+capped at 32; `gapCount` and `gapDetailsTruncated` preserve the count. Cursor input
+is limited to 2 KiB. These are work/size bounds, not a disk-latency guarantee.
+
+No event payload, transition note, queue body/summary, transcript, command, path,
+or environment is selected. Operational IDs, native conversation IDs and actor
+addresses are intentional metadata; they can still identify people or seats.
+This interface does not make that metadata public or anonymous.
+
+## Unknown history and errors
+
+`coverage.historyCompleteness` is always `unknown`. Coverage status is
+`retained_window`, `partial`, or `unavailable`; a retained window does not prove
+that older history exists or is complete. `retainedMinimum` and named gaps expose
+missing retained identifiers with unknown cause, never inferred downtime. Missing
+tenure history cannot distinguish node deletion from never-recorded history.
+
+`source` contains `hostId`, `bootEpoch`, and **`sequenceSpaceId: null`**. A daemon
+boot epoch is not durable store identity. On a boot change or observed watermark
+regression, the API returns no old-window rows, a named unavailable-history gap,
+and (for ascending streams) a separate fresh `restartCursor`. Record that gap
+before explicitly adopting the fresh checkpoint. Tenures may be requested fresh
+without a cursor. Do not silently reset to zero or conflate existing collector
+source identity, native-tail cursors and these cursors. An arbitrary in-place
+database restore/copy without an observable regression is not detected.
+
+After **every daemon restart**, a following collector cannot continue its old
+cursor. To recover available retained history, record the boot gap and start a new
+read with `start=retained`, accepting possible overlap with previously read records.
+Alternatively, adopting `restartCursor` observes only new records after the fresh
+high watermark; it does not recover the missed interval. Neither choice proves
+continuity across the restart while `sequenceSpaceId` remains null.
+
+Malformed cursors/options return HTTP 400 `telemetry_invalid_request`.
+Schema/read/source failures return HTTP 503 `telemetry_read_unavailable`, never a
+successful empty history. The CLI preserves the error body in JSON mode and exits
+1 for request errors, 2 for unavailable reads. Existing SSE and usage APIs retain
+their behavior. Collector deployment, exporters and durable store epochs are
+separate work.

package/daemon/docs/reference/worktree-builds.md

@@ -6,12 +6,12 @@ consume ANOTHER tree's source — a false-green generator, not an inconvenience.
 
 ## What actually happens
 
-`npm install` in a worktree creates `node_modules/@openrig/<pkg>` as a RELATIVE symlink
+A per-worktree install creates `node_modules/@openrig/<pkg>` as a RELATIVE symlink
 (`-> ../../packages/<pkg>`). Relative links resolve against the directory they live in, so:
 
 | setup | `@openrig/daemon` resolves to | verdict |
 |---|---|---|
-| per-worktree `npm install` | that worktree's `packages/daemon` | correct |
+| per-worktree install (`npm ci`) | that worktree's `packages/daemon` | correct |
 | `ln -s <primary>/node_modules node_modules` | **the PRIMARY tree's** `packages/daemon` | **cross-tree** |
 
 Verified by discriminator, not by inference: with a symlinked `node_modules`, a deliberate type
@@ -21,18 +21,24 @@ A worktree can therefore report green against code it does not contain.
 
 ## Rules
 
-1. **Run `npm install` in each worktree** so workspace packages resolve to the
-   worktree's own source.
+1. **Run `npm ci` in each worktree** so workspace packages resolve to the
+   worktree's own source. It installs the locked versions without rewriting
+   `package-lock.json`. Then run `npm run build`, as CI does before the package suites.
 2. **Never symlink `node_modules` from the primary checkout.** It appears to work — builds pass,
    typechecks pass — which is exactly the danger.
 3. **`npx tsc` with no `node_modules` installs an unrelated `tsc` package** and prints
    "This is not the tsc command you are looking for". That message means *no install*, not a
    TypeScript error.
-4. **Build `@openrig/daemon` before typechecking `@openrig/cli`** in a fresh worktree: cli imports
-   `@openrig/daemon/crash-cart` etc., which resolve to daemon's `dist`. Absent dist reads as
+4. **Build `@openrig/daemon` before typechecking `@openrig/cli` or `@openrig/tui`** in a fresh worktree:
+   cli imports `@openrig/daemon/crash-cart` etc. and tui imports `@openrig/daemon/attention`, which resolve
+   to daemon's `dist`. `npm run lint` does this build first. Absent dist reads as
    TS2307 "Cannot find module" plus a cascade of implicit-any — a provisioning artifact, not a
    code defect.
 
+Some cli imports don't depend on `node_modules` at all: `packages/cli/tsconfig.json` maps a few daemon
+subpaths (`crash-cart` among them) straight to the worktree's own `../daemon/dist`. The others resolve through
+`node_modules`, so the rules above still hold.
+
 ## Self-check before trusting any worktree build
 
     [ "$(readlink -f packages/daemon)" = "$(readlink -f node_modules/@openrig/daemon)" ] \

package/daemon/policies/builtin/auto.policy.md

@@ -0,0 +1,24 @@
+---
+source: builtin
+name: auto
+surface: flag
+launch_posture: auto
+policy_schema_version: 1
+description: Claude runs with --permission-mode auto. Codex and Pi launch at the floor.
+---
+
+# Auto (built-in policy — flag surface)
+
+This built-in selects Claude `--permission-mode auto`. Codex and Pi do not have an
+auto mode and launch at their floor (Codex `-s workspace-write` or its named
+profile; Pi `--no-approve`).
+
+**APPLICATION is deterministic, NOT skill-translated.** Auto is a `surface: flag`
+policy: it resolves to a stable launch flag and is applied directly by the runtime
+flag-surface opt-in. The `applying-a-permission-policy` skill does **NOT** translate
+this policy.
+
+**Selection and native enforcement are separate.** A member policy overrides the
+rig policy. A resolved config-surface selection chooses OpenRig's normal launch
+mode and takes precedence over ambient YOLO. Native configuration and managed
+restrictions still matter; recording a policy does not translate config rules.

package/daemon/specs/agents/development/implementer/agent.yaml

@@ -1,6 +1,6 @@
 name: implementer
 version: "1.0"
-description: Implementation agent — writes code following TDD discipline
+description: Implementation agent — implements and verifies coherent changes
 
 defaults:
   runtime: claude-code
@@ -11,7 +11,7 @@ imports:
 profiles:
   default:
     uses:
-      skills: [development-team, test-driven-development, systematic-debugging, verification-before-completion]
+      skills: [development-team, systematic-debugging, verification-before-completion]
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]

package/daemon/specs/agents/development/qa/agent.yaml

@@ -11,7 +11,7 @@ imports:
 profiles:
   default:
     uses:
-      skills: [test-driven-development, development-team, systematic-debugging, verification-before-completion, agent-browser, dogfood]
+      skills: [development-team, systematic-debugging, verification-before-completion, agent-browser, dogfood]
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]

package/daemon/specs/agents/product-management/pm/agent.yaml

@@ -29,6 +29,16 @@ profiles:
         - shared:codex-default-config
         - shared:claude-activity-hooks
 
+  advisor:
+    uses:
+      skills: [shared:orchestration-team]
+      plugins: [shared:openrig-core]
+      runtime_resources:
+        - shared:claude-default-settings
+        - shared:claude-default-mcp
+        - shared:codex-default-config
+        - shared:claude-activity-hooks
+
 resources:
   guidance:
     - id: role

package/daemon/specs/agents/shared/agent.yaml

@@ -47,7 +47,7 @@ resources:
     - id: openrig-core
       source:
         kind: local
-        path: ~/.openrig/plugins/openrig-core
+        path: openrig-home:plugins/openrig-core
   runtime_resources:
     - id: claude-default-settings
       path: runtime/claude-settings.fragment.json

package/daemon/specs/agents/shared/skills/core/agent-starters/SKILL.md

@@ -6,15 +6,10 @@ metadata:
     stage: factory-approved
     sibling_skills:
       - claude-compaction-restore
-      - mental-model-ha
-      - scope-recovery
       - session-compaction-and-restore
       - agent-startup-and-context-ingestion
-      - composable-priming-packs
       - session-source-fork
       - seat-continuity-and-handover
-      - claude-compact-in-place
-      - pre-maintenance-agent-preservation
 ---
 
 # Agent Starters
@@ -131,4 +126,3 @@ included, and is that starter still recommended?"
 ## See also
 
 - `session-source-fork` skill — low-level fork primitive that makes native session-based starters possible
-- `composable-priming-packs` skill — manifest-driven layer for producing primed sessions starters reference

package/daemon/specs/agents/shared/skills/core/agent-startup-and-context-ingestion/SKILL.md

@@ -9,15 +9,10 @@ metadata:
     stage: factory-approved
     sibling_skills:
       - claude-compaction-restore
-      - mental-model-ha
-      - scope-recovery
       - session-compaction-and-restore
       - agent-starters
-      - composable-priming-packs
       - session-source-fork
       - seat-continuity-and-handover
-      - claude-compact-in-place
-      - pre-maintenance-agent-preservation
 ---
 
 # Agent Startup and Context Ingestion
@@ -48,7 +43,7 @@ is scattered or stale, agents execute the wrong thing very efficiently.
 
 - The agent is being created via Agent Starter — the starter's manifest carries startup context
 - The work is artifact-backed mental-model rebuild from a packet — that's `session-compaction-and-restore`
-- The intent is to ship reusable startup content as a skill — that's `writing-skills-for-openrig`
+- The intent is to ship reusable startup content as a skill
 
 ## Failure modes (4)
 
@@ -119,10 +114,8 @@ culture / pod / member / operator) handles the layering.
 ## See also
 
 - `mission-slice-sop` — load when starting assigned mission/slice work; the light artifact and handoff procedure for SPEC.md, NOTES.md, PROGRESS.md and proof. It does not choose the SDLC for the task.
-- `writing-skills-for-openrig` skill — authoring discipline for skill content (what doesn't belong in startup)
 - `forming-an-openrig-mental-model` skill — orientation for new agents
 - `session-compaction-and-restore` skill — restore-time startup ingestion
 - `agent-starters` skill — reusable starter manifests that compose startup context
-- `composable-priming-packs` skill — manifests that produce primed sessions
 - `openrig-operating-model` skill — placement and authority of durable context
 - `openrig/docs/reference/agent-startup-guide.md` (product reference doc; not a skill) — the 7-layer additive startup model + delivery hints