@etiquekit/etq 1.0.9 → 1.0.11

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Etiquette (etq)
+Copyright 2026 The Etiquekit Authors
+
+Local-first, git-backed agent-workflow governance toolkit.
+Distributed under the Apache License, Version 2.0.

package/QuickStart.md

@@ -64,7 +64,7 @@ envelope, and runbook. For branch hygiene, read [docs/WORKTREE_QOL.md](docs/WORK
 
 ## 4. Check And Record Evidence
 
-Completion gate: write the receipt at the path `pickup` names, post it
+Completion gate: write the receipt at the path `pickup` names (`etq receipt scaffold --task <ref> --seat <id>` writes a starter stub), post it
 (`etq post --role implementation-return --lane <task> --from <seat> --to <seat>`),
 then `etq return check`. Separately, `dispatch check` gates ROUTING before
 work begins — create checkable dispatch examples, then run the generated
@@ -91,4 +91,5 @@ Per-runtime integrations are explicit, never automatic: `provision-seat claude-c
 Stop when authority is unclear, validation cannot run, writes exceed the
 envelope, a secret appears, or the session is unbounded.
 
+Going further: `etq help advanced` catalogs the advanced subsystems — the memory journal, supervision sessions, release gates, sync outbox, and webhooks.
 Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt

package/README.md

@@ -10,7 +10,7 @@ and what proved it worked**. Etiquette gives each participant a *seat*, each
 unit of work a *task envelope*, each completion a *receipt*, and each merge a
 *promotion gate* — recorded as plain files and git history you can audit.
 
-Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt · Going further (memory journal, supervision, release gates): `etq help advanced`
 
 ## Install
 

package/docs/AGENT_SPAWNING.md

@@ -0,0 +1,78 @@
+# Agent Spawning: inline runners vs provisioned seats
+
+Guidance for **implementing agents** (the seat doing the work): when to spawn a
+helper yourself, when to ask the operator to provision a durable seat, and how
+to bind either one to the workflow. (`OPERATOR_PLAYBOOK.md` is the operator's
+side of this; this file is yours.)
+
+## The two axes — never conflate them
+
+- **Seat** = durable identity + evidence trail. It survives processes, carries
+  the receipts, and owns tasks. Seats are cheap to keep and expensive to blur.
+- **Runner** = an execution process occupying a seat. Disposable by default.
+
+The default pattern is the **hybrid**: bind a *disposable runner* to a
+*durable seat*. The trail persists; the process is throwaway. Discard the
+runner after its return — the seat keeps everything that matters.
+
+## Spawn inline yourself (no operator needed) when ALL hold
+
+- The work is **bounded and one-off**: a single review, an audit, a read-only
+  probe, a parallel fan-out of readers.
+- It's **read-only toward your scope** — a spawned helper must never become a
+  second writer in your own `allowed_writes` (single-writer applies to your
+  spawns too).
+- It can **finish inside your session**: if your process dies, nothing of value
+  dies with it beyond a re-run.
+- You can bind it properly: seat + task + envelope + the same pickup/receipt
+  workflow you follow. An unbound helper produces unaccountable output.
+
+## Ask the operator to provision instead when ANY hold
+
+- The helper will own **repeated lanes over days** — recurring review, a
+  standing monitor, a specialist surface. Durable work deserves a durable
+  session the operator can see, resume, and audit.
+- It needs its **own vendor/model/credentials** (a different provider is often
+  *desirable* for review — and it's the operator's call to provision).
+- It must **outlive you**: long-running watches, anything that should survive
+  your session ending.
+- It would **write product code** anywhere. New writers are an operator
+  decision, always.
+
+Never be shy to ask. A well-formed ask is a sign of a healthy loop, not a
+failure. But ask with a complete provisioning card, not a vibe:
+
+```
+Requesting a provisioned seat:
+  seat:        <id> (new or existing)
+  why durable: <recurring lanes / credentials / outlives-me>
+  first task:  <ref> — envelope ready at <path>
+  worktree:    <prepared path + pinned base>
+  entry:       <the exact join/pickup commands>
+  boundaries:  <read-only? allowed_writes? never merge/push?>
+  vendor hint: <same or deliberately different model — and why>
+```
+
+## Binding rules (both kinds)
+
+- One seat, one active runner per task. If a second runner must take over,
+  it claims *explicitly* (exclusive claim, runner id recorded) — two runners
+  silently emitting as one seat corrupts the trail.
+- Every spawned runner follows the full loop: join → pickup → work → receipt →
+  return. No side-channel results; if it didn't post, it didn't happen.
+- Record provenance: the return should show which runner executed, especially
+  when it isn't the seat's usual occupant.
+- Reviewers return **evidence and proposed amendments — never edits, never
+  merges**. Your spawns inherit your boundaries; they do not inherit your
+  write scope.
+- Disposable means disposable: after the return is posted and verified, the
+  runner is gone. Anything worth keeping is in the receipt, not the process.
+
+## The sequencing instinct (learned from real runs)
+
+- **During implementation**: zero extra writers. Resist "help."
+- **Branch ready**: exactly one reviewer — read-only, ideally a different
+  model/vendor than you.
+- **Recurring specialization emerges** (per-provider adapters, standing
+  audits): *that* is the moment to request provisioned specialist seats —
+  not before.

package/docs/ARCHITECTURE.md

@@ -22,9 +22,9 @@ Execution returns evidence; it never mints authority.
 ```
 
 Execution is a substrate, not an authority layer. In Core it is the local shell,
-worktree, or runner. In Full it may be a runtime cell, EKS/kind sandbox, or
-managed runner. In every profile, execution remains authority-false until the
-promotion gate accepts evidence.
+worktree, or runner. In Full it may be a managed execution container,
+EKS/kind sandbox, or managed runner. In every profile, execution remains
+authority-false until the promotion gate accepts evidence.
 
 ## Authority
 
@@ -52,11 +52,11 @@ role occupants or composite gates and fails closed.
 
 ## Consumers
 
-Consumers may read, render, route bounded work, spawn bounded runners, and return
+Consumers may read, render, route bounded work, start bounded runners, and return
 receipts. They must not grant, close, merge, rewrite ledgers, or become the bus.
 
 Good first consumers are verification-first managed runners, local coding seats,
-context workbenches, dashboards, and MCP readers. Start remote as witness-only.
+context workbenches, dashboards, and MCP readers. Start remote as evidence-only.
 
 ## Package Boundary
 

package/docs/CODEX_CLIENT_COMPATIBILITY.md

@@ -23,7 +23,7 @@ Source: https://developers.openai.com/codex/changelog
 | Remote-runtime app-server/exec-server canaries | `0.141.0` required | Block that canary until upgraded. |
 | Plugin-scoped MCP adapter canaries | `0.141.0` required | Block that canary until upgraded. |
 | Hook/action-auth resume canaries | `0.141.0` required | Block that canary until upgraded. |
-| Usage-budget hygiene before long swarms | `0.140.0` minimum for `/usage` | Advisory only. |
+| Usage-budget hygiene before long multi-runner windows | `0.140.0` minimum for `/usage` | Advisory only. |
 
 ## Operator Check
 

package/docs/CONCEPTS.md

@@ -38,8 +38,8 @@ autonomous execution.
 ## Session
 
 A session is a bounded run inside one repo. Use one for a bug fix, feature
-slice, review, release canary, or short swarm; not for a product, quarter, or
-org.
+slice, review, release canary, or short parallel review window; not for a
+product, quarter, or org.
 
 ## Receipt
 
@@ -52,6 +52,23 @@ A ledger is the durable work record for a repo or workspace: decisions,
 receipts, state changes, and refs. Raw execution chatter belongs in session
 runbooks and scratch space.
 
+### Durable Record vs Query Index
+
+Two surfaces share the ledger name. They are different systems:
+
+| Surface | Path | When it populates |
+| --- | --- | --- |
+| Durable record | `docs/work/ledger/LEDGER.md` | Automatically, as the workflow appends event lines |
+| Query index | `.etiquette/state/ledger/index.db` | Only when you run `etiquette ledger index` |
+
+The durable record is canonical and append-only. The query index is a
+generated, regenerable SQLite cache read by `ledger search` and `ledger show`.
+It ingests typed `schema=ledger-entry.v0*` lines and scanned documents, not
+routine workflow event lines. `ledger_entries: 0` after a full workflow cycle
+means no typed entries exist yet; the durable record is intact. Deleting the
+index loses nothing. See
+`docs/contracts/ledger-entry/ledger-query-cli.v0.1.md`.
+
 ## Promotion Gate
 
 The promotion gate is where candidate work becomes accepted truth.
@@ -82,7 +99,8 @@ runner only through an explicit lease.
 
 A child lease must be a strict subset of the parent lease. The subset covers
 shorter or equal TTL, narrower or equal authority scope, subset write paths,
-subset tools, inherited prohibitions, reduced spawn budget, and reduced depth.
+subset tools, inherited prohibitions, reduced child-runner budget, and reduced
+depth.
 
 Children return to their immediate parent. The parent synthesizes one upstream
 receipt and remains accountable for child cleanup. A child or headless node is
@@ -91,7 +109,7 @@ not a durable seat unless it is separately enrolled and passes readiness.
 ## Exec
 
 Exec is any runtime that does work: a local shell, Codex, Claude Code, Gemini,
-Ollama, a script, a container, or a remote runtime cell.
+Ollama, a script, a container, or a managed execution container.
 
 Exec may run, observe, retry safe work, and return evidence. Exec must not
 grant, merge, close, promote, or mutate canonical truth.
@@ -126,4 +144,3 @@ Portals display and coordinate.
 Integrations project refs.
 Execution returns evidence; it never mints authority.
 ```
-

package/docs/CORE_PROFILE.md

@@ -37,7 +37,8 @@ Core records, validates, gates, and dispatches:
 
 Full remembers, consolidates, marinates, and projects. Memory stores,
 consolidation rollups, marination modules, hosted portals, secure screening,
-remote runtime cells, and sharded drains belong there unless explicitly enabled.
+managed execution containers, and sharded drains belong there unless explicitly
+enabled.
 
 Use:
 
@@ -63,7 +64,8 @@ The Core promotion path is:
 5. The ledger records the promoted result.
 
 At Core scale, Git is the promotion mechanism. Drains, sharded import, hosted
-planes, and runtime cells belong to the Full profile unless explicitly enabled.
+planes, and managed execution containers belong to the Full profile unless
+explicitly enabled.
 
 Core commands may advise, check, and record evidence. They do not authorize
 work, attach grants, merge, close lanes, or promote candidates without the

package/docs/INTEGRATION_UI.md

@@ -0,0 +1,215 @@
+# Integrating a UI/Consumer with the Event Log and Packets
+
+How to build a read-model or composer UI (inbox, thread view, approvals queue,
+seat roster) over an Etiquette project. Three file surfaces, all in one git
+repo. The consumer is a read-model plus composer over them, never a writer of
+record.
+
+```text
+<project>/
+├── .etiquette/events/local.ndjson   # the EVENT LOG (append-only, seq-ordered)
+├── docs/work/packets/*.json         # the PACKETS (one file per message)
+├── docs/work/ledger/LEDGER.md       # the durable record (see CONCEPTS.md)
+└── (ordinary git)                   # commits are durability; push is visibility
+```
+
+## 1. Event Schema (`local-event.v0`)
+
+Every emitted packet post appends exactly one event line (ndjson, one JSON
+object per line). Events are the index; packets are the content.
+
+| field | type | notes |
+| --- | --- | --- |
+| `seq` | int | global monotonic sequence. THE ordering key. Never reuse, never renumber. |
+| `schema` | string | `local-event.v0` |
+| `event_ref` | string | `local://event/<seq>` — the durable ref other records cite |
+| `created_at` | ISO8601 UTC | emit time |
+| `type` | string | event kind, e.g. `packet_posted` |
+| payload | spread | packet fields are spread into the event: `role`, `lane`, `from`, `to`, `next_owner`, `verdict`, `mode`, `packet_tier`, `packet_ref`, `changes_state`, and optionally `requires_ack`, `in_reply_to` |
+
+Reader rules (learned the hard way):
+
+- Track position by `seq` cursor, never by byte offset or `tail -F`. Git
+  operations can rewrite the file and replay it from line 1.
+- Read through the CLI where possible: `etiquette notify poll --seat <id>
+  --after-seq <n>`, `etiquette bus view`, `etiquette timeline view`,
+  `etiquette status`. The write side must go through `etiquette post` — it
+  owns field validation, the event append lock, and the ledger mirror.
+- Badge authority acts (decisions, grants) differently from routine traffic.
+  Key on the packet `role` and `verdict`, not on `changes_state` (see drift
+  note D5).
+
+## 2. Packet Spec (`local-packet.v0`)
+
+One JSON file per message, written by `etiquette post` to
+`docs/work/packets/<created_at>-<lane>-<role>.json`. With `--emit` (implied
+for return roles) the post also appends a `packet_posted` event and mirrors a
+line into the durable ledger record.
+
+```json
+{
+  "schema": "local-packet.v0",
+  "role": "dispatch",
+  "lane": "wire-real-search-01",
+  "from": "team-orchestrator",
+  "to": "team-implementer-1",
+  "verdict": "routed",
+  "packet_tier": "3",
+  "mode": "product-implementation",
+  "next_owner": "team-implementer-1",
+  "created_at": "2026-07-11T09:00:12.000Z",
+  "changes_state": true,
+  "authority_boundary": {
+    "packet_authorizes_work": false,
+    "can_merge": false,
+    "can_close": false,
+    "can_grant": false
+  }
+}
+```
+
+Field notes:
+
+- `role` — the message class. Conventional values: `dispatch`, `task-bundle`,
+  `implementation-return`, `review-return`, `counter`, `advisory`, `decision`,
+  `acknowledge`. Return roles always emit an event.
+- `mode` — the authority class of the referenced work (see section 5).
+- `next_owner` — who acts next; load-bearing for routing and wake queues.
+- `packet_tier` — a string (`"2"` or `"3"`); governs how much body discipline
+  the packet's narrative carries (section 3).
+- `authority_boundary` — always present, always false-by-default. A packet
+  never authorizes work by itself.
+
+The write-scope envelope (what a task may touch) does not live in the packet.
+It lives in the task bundle (`task-bundle.v1`): `allowed_writes` (required),
+`validation` (required), `stop_conditions`, `forbidden_sources`,
+`expected_return`, `evidence_sink`, `authority_boundary`. Packets reference
+the lane/task; the bundle carries the envelope.
+
+## 3. Body Discipline by Tier
+
+Packets shipped by this CLI are compact JSON. When a deployment pairs packets
+with markdown narrative bodies (correspondence artifacts), the tier rules
+below are the required section headings. Composers should emit them exactly;
+a suffix on a heading (`## Evidence Cited from X`) is the classic papercut.
+
+| tier | required `##` headings | extra rule |
+| --- | --- | --- |
+| 2 | `## Verdict` (or `## Disposition`) + `## Evidence` + `## Next owner` | body <= 50 lines |
+| 3 | tier-2 set plus `## Failure modes` + `## Confidence calibration` | — |
+
+Note: this package does not lint markdown bodies today (drift note D4). Treat
+the table as the portable packet-body convention a composer should enforce
+client-side.
+
+## 4. Sample Thread
+
+A synthetic six-event thread covering every UI moment (dispatch, ack with a
+runner swap, a stop-condition counter, an amended scope, a verified return,
+and a human decision) ships in source checkouts as
+`fixtures/ui-thread-example.json`. Fixtures are excluded from the published
+package; use a source checkout. The fixture carries a `summary` convenience
+field (extra payload, drift note D8) so list views have something to render.
+
+Render test for a consumer:
+
+- The thread reads as a conversation (`in_reply_to` chains to `event_ref`).
+- The runner-swap badge shows where `execution_seat` differs from
+  `durable_owner`.
+- The counter (a guardrail firing) is visually distinct — celebrate it, do
+  not bury it.
+- Exactly one event is an authority act (the `decision` role).
+
+## 5. The Envelope Model (what an approval UI must understand)
+
+Four separate axes — never collapse them into one "agent type":
+
+| axis | values | meaning |
+| --- | --- | --- |
+| coordination shape | `solo` \| `tango` \| `rig` \| `shadow` | one runner / pair-with-reviewer / fan-out / observe-only |
+| `mode` (authority class) | `read-only-audit` \| `docs-only` \| `product-implementation` | what the seat may WRITE |
+| perimeter | local \| sandboxed \| managed | WHERE it executes (never a topology) |
+| risk posture | derived | from mode + write breadth + irreversibility + credentials/network + data sensitivity |
+
+Authority doctrine the UI must encode, not just display:
+
+- Agent-produced artifacts are authority-false. They cross into effect only
+  via a human decision. An approval screen renders the authority-false
+  artifact plus its evidence and captures the human decision as a new packet.
+- Single-writer: one routed owner mutates a canonical surface at a time;
+  reviewers contribute evidence packets, never competing mutations.
+- Dynamic execution, static authority: automation may advance work; only the
+  principal crosses merge/promote/ratify/spend gates. No auto-approval, ever.
+  An adapter or app synthesizing a decision is the named number-one failure
+  mode.
+- Landing/merging is always the principal's act; seats hand branches back.
+
+## 6. Composer Requirements (where a consumer earns its keep)
+
+1. Emit valid packets: real `role`, valid `mode`, `next_owner` always set,
+   envelope present in the task bundle for `product-implementation` work.
+2. Post through the CLI. `etiquette post --emit` performs the packet write,
+   event append (under the event lock), and ledger mirror as one act. The git
+   commit remains the operator's act — surface uncommitted
+   `.etiquette/events/` and `docs/work/` state prominently; a dirty canonical
+   surface blocks other seats' workflow steps.
+3. Thread rendering: chain packets by `in_reply_to` / `event_ref` into a
+   conversation view (dispatch, counter, amend, return, confirm, decision).
+4. Badges: model/provider identity, runner-vs-seat occupancy, authority
+   (`role`, `mode`), and verification level (self-reported vs
+   second-party-verified — a return another seat re-ran is gold).
+5. Envelope-aware diff review: when reviewing a branch, show the diff against
+   the bundle's `allowed_writes` — out-of-scope files are instant red flags.
+6. Never write canon autonomously. The app composes; the human sends.
+
+## 7. Format Drift Notes
+
+This document descends from a spec written against a markdown-packet bus.
+Where that ancestor and this package disagree, this package's shipped formats
+win. Known drift, kept honest rather than papered over:
+
+- D1. Ancestor events carried `at`/`actor`/`action`/`packet_id`/`message`;
+  shipped `local-event.v0` uses `created_at`/`from`/`type` plus packet fields,
+  and has no self-contained `message` summary field.
+- D2. Ancestor refs used a bus URI scheme keyed by bare seq; shipped refs are
+  `local://event/<seq>` in `event_ref` and `in_reply_to`.
+- D3. Ancestor packets were markdown with YAML frontmatter named
+  `<timestamp>-<actor>-<slug>.md`; shipped packets are JSON
+  `local-packet.v0` files named `<created_at>-<lane>-<role>.json`.
+- D4. Ancestor tier headings were lint-enforced at post time; this package
+  does not lint markdown bodies. `packet_tier` is also a string here, not an
+  int.
+- D5. Ancestor `changes_state` meant "authority act". The shipped `post`
+  command sets `changes_state` to whether the packet was emitted to the event
+  log, so every `packet_posted` event carries `changes_state: true`. Until
+  this is reconciled, consumers must badge authority from `role`/`verdict`,
+  not `changes_state`.
+- D6. Ancestor `mode` enum had a fourth value, `dirty-tree-extraction`; this
+  package ships three modes.
+- D7. Ancestor envelopes (`repo`, `base_commit`, `branch`, `worktree_path`)
+  rode in packet frontmatter; the shipped envelope lives in `task-bundle.v1`
+  and does not include those four fields — base pinning and worktree layout
+  are handled at the git/CLI layer.
+- D8. `cc`, `workflow_id`, `slice_id`, `content_class` (on packets), `summary`,
+  and the provenance fields `durable_owner`, `execution_seat`, `executed_by`,
+  `actual_model`, `operator_principal` have no shipped writer in `post`.
+  Events tolerate them as extra payload; projections surface only some. Treat
+  them as optional until promoted.
+
+## 8. Glossary
+
+- **seat** — durable agent identity plus authority envelope; provider-agnostic.
+- **packet** — one message on the log; the unit of coordination.
+- **lane / slice** — a thread of work / one bounded task within it.
+- **envelope** — the write-scope + validation + stop-condition contract a task
+  runs under (carried by the task bundle).
+- **harvest** — a defect found out of scope: recorded and routed, never fixed
+  inline.
+- **receipt** — evidence attached to a return (commands run, output tails,
+  SHAs).
+- **landing** — principal-gated merge to the default branch.
+- **lease** — a seat's time-bounded authority to occupy a task.
+- **promotion gate** — the human decision point where an authority-false
+  artifact becomes effective.
+
+See `docs/CONCEPTS.md` for the core vocabulary these one-liners compress.