@etiquekit/etq 1.0.9 → 1.0.11

package/docs/OPERATOR_PLAYBOOK.md

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

@@ -11,6 +11,7 @@ References:
 
 - [CODEX_CLIENT_COMPATIBILITY.md](CODEX_CLIENT_COMPATIBILITY.md)
 - [RELEASE_SURFACE_AUDIT.md](RELEASE_SURFACE_AUDIT.md)
+- [INTEGRATION_UI.md](INTEGRATION_UI.md) — building a UI/consumer over the event log and packets
 
 Source checkouts also keep hosted parity, portal, managed-runtime parity, and root kernel notes for
 maintainers. They are not part of the local devkit tarball.

package/docs/SEAT_PROVISIONING.md

@@ -7,7 +7,7 @@ Start with one project owner and one review seat. Add runtime-specific seats onl
 1. Install project-local agent guidance with `setup`.
 2. Initialize the project with `bootstrap local`.
 3. Read `AGENTS.md`, `BOARD.md`, `SESSION_PICKUP.md`, and `SEAT_OPERATING_MANUAL.md`.
-4. Run `whereami`, `doctor`, and `status`.
+4. After resume or runner/model swaps, run `resume check`; otherwise run `whereami`, `doctor`, and `status`.
 5. Confirm the lead and review seats.
 6. Use `$etiquette-seat-lifecycle` before pickup after stale context, resume, runner/model/profile swaps, or workflow migration.
 7. Have the lead seat `join` and `pickup` the first generated task.
@@ -18,6 +18,7 @@ Start with one project owner and one review seat. Add runtime-specific seats onl
 ```sh
 etiquette setup --target codex --project "$PWD"
 etiquette bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etiquette resume check --project "$PWD" --seat codex-seat --task APP-001 --json
 etiquette whereami --project "$PWD" --seat codex-seat --task APP-001
 etiquette doctor --project "$PWD"
 etiquette status --project "$PWD"
@@ -96,5 +97,4 @@ Remote execution is a later layer. Plane provisioning is infra-admin scoped. Wor
 - Start with the smallest useful topology.
 - Add seats because work requires them.
 - Product-write authority requires a task, allowed writes, validation, and the right promotion gate.
-- Chat is not canonical record.
-- Runtime packs are adapters, not doctrine.
+- Chat is not canonical record; runtime packs are adapters, not doctrine.

package/docs/TAG_ROUTE.md

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

package/docs/WORKTREE_QOL.md

@@ -33,11 +33,17 @@ Agent resume restores conversation context. It does not prove repo context.
 After any resume, run:
 
 ```sh
+etiquette resume check --project "$PWD" --seat <seat> --task <task> --json
 etiquette whereami --project "$PWD" --seat <seat> --task <task>
 git status -sb
 git branch --show-current
 ```
 
+`resume check` is read-only and fail-closed. It treats the runner resume hash as
+conversation context only, then verifies project, seat, task, lifecycle, and
+session bindings before pickup. If it reports `rebind_required`, use the seat
+rebind and lifecycle skills before reading old session runbooks as assignment.
+
 If the runner asks whether to resume in the old session directory or the
 current directory, choose the current directory only when it is the intended
 project worktree for the task. Do not resume a repo-local task inside a global

package/docs/contracts/ledger-entry/ledger-entry.v0.2.md

@@ -59,7 +59,7 @@ the validator:
 - must carry at least one contemporaneous evidence ref among
   `refs.commits`, `refs.receipts`, or `refs.artifacts` — evidence that
   carries its own independent timestamps (git commits are the canonical
-  witness);
+  evidence anchor);
 - authority class must be `advisory` or `audit` — a late entry never mints
   grants or execution authority;
 - one reconciliation entry covering a span with an index artifact is