@etiquekit/etq 1.0.12 → 1.0.13

package/docs/AGENT_SPAWNING.md

@@ -1,78 +0,0 @@
-# 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/INTEGRATION_UI.md

@@ -1,215 +0,0 @@
-# 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.

package/docs/OPERATOR_PLAYBOOK.md

@@ -1,77 +0,0 @@
-# Operator Playbook
-
-You are the principal. Agents execute; **you decide.** This is the when-X-do-Y
-card for running the workflow on the go. (`AGENTS.md` tells agents how to
-behave — this file tells *you* what move to make.)
-
-## Starting work
-
-- **Before dispatching, shape the task**: one agent or several? does review need
-  a separate mind? is checking cheap? If it's a judgment call — keep it yourself.
-- **Write the envelope, always**: `allowed_writes`, validation, stop conditions,
-  pinned base commit. The envelope *is* the speed — it's what lets an agent run
-  unattended and lets you trust the result.
-- **One task, one worktree, one branch.** Never work on a shared checkout.
-
-## While an agent works
-
-- **Don't add a second writer to the same scope.** Design can be parallel;
-  writing is single-writer. Resist "helping" in its files.
-- **Don't steer mid-run.** Post an amendment packet instead; the agent's
-  stop-conditions are your remote control.
-- Long silence ≠ progress. Check the session notes, not the vibe.
-
-## When a return arrives
-
-- **An agent STOPPED or COUNTERED? That is the system working.** Read its
-  evidence, then uphold or amend — never bulldoze past it. A lying green is
-  worse than an honest red.
-- **Self-reported evidence is a claim, not a proof.** Before landing anything
-  that matters, get a second party to re-run the checks — runtime proof beats
-  reading code beats trusting a summary.
-- **Review the diff against the envelope**: files outside `allowed_writes` are
-  red flags even when the code looks good.
-
-## The reviewer moment (the most-missed nudge)
-
-- **Branch ready → spin exactly one reviewer.** Read-only audit, a *different*
-  model/vendor than the implementer, returning evidence and proposed
-  amendments — never edits, never merges.
-- Never be shy to add **reviewers**; be very shy to add **writers**.
-- A good implementing agent will *ask* you for a reviewer at the right moment.
-  Honor the shape it proposes.
-
-## Gates (yours alone)
-
-- Merging, closing, promoting, granting scope, spending money, touching
-  credentials or production — these never delegate. An agent that "just did it"
-  is a defect, not initiative.
-- Before approving: read the evidence, not the summary line.
-- Anything needing secrets, network egress, or real user data is a *perimeter
-  decision*, not a task detail. Stop and decide it explicitly.
-
-## Hygiene, on the go
-
-- Lost? `etq whereami`. Broken? `etq doctor`.
-- Finish your posts: a half-committed event blocks every other seat.
-- Don't leave counters unanswered overnight — a stopped agent is parked
-  capacity waiting on *you*.
-- The urge to skip the envelope for "a quick fix" is how quick fixes become
-  incidents. Small task, small envelope — but an envelope.
-
-## The human gate ("what now?")
-
-- When an agent stops and waits, ask: **is this a stall or a gate?** A good
-  agent tells you; if it doesn't, ask "gate or stalled?" before nudging.
-- **"continue" / "proceed" are nudges, not authority.** Never let them double
-  as approval. A gated act needs its own *named phrase* — a good agent mints
-  one ("say 'accept and land' to merge"); echo it exactly or refuse it.
-- At a gate, demand the card: what's decided, the options, the evidence, the
-  phrase. Deciding from a summary line is how gates rubber-stamp themselves.
-
-## When you're the bottleneck
-
-- Triage by type: **decisions** (only you) → **reviews** (route one reviewer) →
-  **FYI** (skim). Work the decisions first.
-- If the same nudge keeps recurring, it belongs in a stop-condition or a
-  template — encode it once instead of remembering it nightly.

package/docs/TAG_ROUTE.md

@@ -1,95 +0,0 @@
-# Tag-Route v0 — paste a thread, get a bounded draft card
-
-Tag-Route turns a pasted chat thread into a **draft task-bundle.v1 card**.
-It is an entry door into the existing card lifecycle, not a new lifecycle:
-drafts are non-canonical until promoted through normal pickup/return
-discipline, and nothing in this path grants authority.
-
-## Vocabulary: card vs bundle
-
-- **Task card** (`task-envelope.v0`) — the local work envelope under
-  `docs/work/tasks/`. Pickup, allowed writes, validation, receipts.
-- **Task bundle** (`task-bundle.v1`) — the same envelope lineage, extended
-  with namespaced interop fields (`strategy_policy`, `execution_hints`,
-  `requirements`, `preflight_refs`, `budgets`, `provenance_window`,
-  `requested_by`). Every shipped task card already validates as a bundle.
-- Bundles are **strictly declarative**. Script-bearing fields
-  (`pre_execute`, `run`, `shell`, `script`, `hooks`, ...) are rejected.
-  Bundles may only *reference* preflights the executor already holds
-  (`etq://preflights/<id>`); unknown refs refuse pickup.
-
-## Registries (declared, admin-signed, verified-never-authored)
-
-- `.etiquette/bindings.yaml` — `channel-binding-registry.v1`. Each
-  `channel-binding.v1` entry binds a chat channel to one repository, the
-  write envelope compiled cards may declare, and the seat to notify.
-- `.etiquette/roster/mappings.yaml` — `roster-mapping-registry.v1`. Each
-  `roster-mapping.v1` entry maps a chat user id to a seat card ref.
-
-Unknown channel and unknown requesting user are refusals, not fallbacks.
-
-## Walkthrough: paste a thread
-
-1. Declare the registries once (admin act):
-
-   ```yaml
-   # .etiquette/bindings.yaml
-   schema: channel-binding-registry.v1
-   bindings:
-     - schema: channel-binding.v1
-       channel_id: team-help
-       repository_ref: github.example/org/demo-app
-       allowed_writes: [src/checkout/**]
-       notify_ref: impl-seat
-       admin_signature: sha256:<hex>
-   ```
-
-2. Verify them any time:
-
-   ```sh
-   etiquette tag bindings verify --project .
-   etiquette tag roster resolve U12345 --project .
-   ```
-
-3. Save the chat thread as plain text, one `<user>: <message>` per line,
-   then compile (or pipe it via `-`):
-
-   ```sh
-   etiquette tag compile thread.txt --channel team-help --project .
-   ```
-
-4. The compiled draft lands under `docs/work/drafts/<task-id>.yaml` with
-   `content_class: draft` and `authority: "false"`. Compile is the
-   canonicalization moment: the card cites its `provenance_window`
-   (line range + sha256 of the transcript slice) so chat-sourced context
-   stays auditable without ever becoming a startup doc.
-
-5. The bound seat gets a wake notice on the existing notify queue
-   (`etiquette notify poll --seat impl-seat`). Promotion of the draft into
-   a real task card remains a separate, gated act by an authorized seat.
-
-## Refusals (machine-checked)
-
-- Channel not in `bindings.yaml` -> `unknown channel`.
-- Requesting user (first speaker, or `--user`) not in the roster ->
-  `unknown requesting user` plus an enrollment hint.
-- Execution content in the window (script-bearing directives, fenced
-  shell blocks) -> `execution content rejected`. The final card is also
-  re-validated against the bundle schema, which rejects script-bearing
-  fields wherever they nest.
-
-## Security contract: executor inertness
-
-The pickup/return executor treats the envelope as data. The only executable
-surfaces are `validation` (sanctioned gate commands) and executor-held
-`preflight_refs`. Every other field — `execution_strategy`, `rig_conductor`,
-`topology_constraints`, `expected_return`, and any nested script-bearing key —
-is inert: read, projected, printed, never executed. The executor spawns only
-hard-coded programs; no shell interprets a bundle string. Pinned by
-`contracts/tag-route-inertness.test.ts` (behavioral trap + static pin).
-
-## Out of scope in v0
-
-The always-on chat listener is a hosted-plane concern and ships
-separately. It will call this same compile path; nothing in v0 assumes it
-exists. A pasted transcript keeps the whole flow local and testable.