@etiquekit/etq 0.0.1 → 1.0.4

package/docs/RELEASE_SURFACE_AUDIT.md

@@ -0,0 +1,156 @@
+# Release Surface Audit
+
+This audit keeps the all-developer default surface to the minimum needed to claim and validate a seat.
+
+## Result
+
+```yaml
+default_for_all_devs:
+  template: templates/etiquette-vanilla-v0
+  posture: keep
+  reason: minimal kernel plus one generic control seat
+
+optional_runtime_seat_packs:
+  template: templates/seat-packs-v0
+  posture: optional
+  reason: lets a control seat add Codex, Claude Code, Gemini, OpenRouter, or Ollama guidance after the base install
+
+advanced_internal_docs:
+  path: internal/docs
+  posture: advanced/internal
+  reason: source history and maintainer doctrine; not required for a new seat
+
+advanced_internal_templates:
+  path: internal/templates
+  posture: advanced/internal
+  reason: rehearsal and legacy workflow assets; not part of default onboarding
+```
+
+## Default Docs Allowlist
+
+```yaml
+docs_default:
+  - docs/README.md
+  - docs/ARCHITECTURE.md
+  - docs/CODEX_CLIENT_COMPATIBILITY.md
+  - docs/CONCEPTS.md
+  - docs/CONCEPT_STATUS.md
+  - docs/CORE_PROFILE.md
+  - docs/LANE_PROVISIONING.md
+  - docs/SEAT_DISCIPLINE.md
+  - docs/SEAT_PROVISIONING.md
+  - docs/TEAM_HANDOFF.md
+  - docs/WORKTREE_QOL.md
+  - docs/RELEASE_SURFACE_AUDIT.md
+```
+
+Any other default doc is a release-surface expansion and must be intentional.
+
+## Shipped Docs Decisions
+
+- `TEAM_HANDOFF.md` ships as the private team rollout guide; the old
+  maintainer-oriented title is not part of the package.
+- `CODEX_CLIENT_COMPATIBILITY.md` ships because Codex is a supported runner.
+- `RELEASE_SURFACE_AUDIT.md` ships as the visible package-surface control.
+- Maintainer history, hosted parity, and portal docs remain excluded.
+
+## Current Size Snapshot
+
+```yaml
+docs_default:
+  files: 12
+  posture: all-developer
+
+vanilla_template:
+  purpose: all-dev default
+  includes:
+    - etiquette-kernel
+    - control-seat
+  excludes:
+    - runtime-specific seat packs
+    - sample product
+    - backplane
+    - historical local workflow docs
+
+seat_packs_template:
+  purpose: optional runtime adapter templates
+  includes:
+    - Codex seat
+    - Claude Code seat
+    - Gemini seat
+    - OpenRouter seat
+    - Ollama seat
+  default_install: false
+
+internal_docs:
+  path: internal/docs
+  posture: excluded from new-seat onboarding
+
+internal_templates:
+  path: internal/templates
+  posture: excluded from new-seat onboarding
+
+package_surface:
+  npm_pack_entries: 182
+  max_budget: 190
+  posture: local devkit package plus signed user-local installer
+  distribution_origin: https://etiquette.example.com
+  excludes: workspace package metadata, workspace fixtures, internal, conformance, apps, site, dist, hosted parity docs, portal docs, root kernel manuals
+```
+
+## What Is Necessary For All Developers
+
+```yaml
+required:
+  - README.md + AGENTS.md
+  - the Default Docs Allowlist above (verbatim)
+  - templates/etiquette-vanilla-v0/README.md
+  - etiquette-kernel contracts
+  - control-seat handoff + doctor
+  - one starter ledger task
+```
+
+## What Is Not Necessary For All Developers
+
+Runtime seat packs, sample-product rehearsals, v3 workflow helper docs, satellite
+operator docs, supervision phase docs, advisory-signal experiments, and internal
+templates may remain in the repo for maintainers. The default onboarding path
+must not require them.
+
+## Release Hygiene Proof
+
+The release scan blocks:
+
+```yaml
+blocked:
+  - personal absolute paths
+  - local username markers
+  - old repo name
+  - shop-persona markers in the release rollout package
+  - prior-run markers in all-developer docs
+  - extra files under docs/
+  - unexpected public template directories
+  - unexpected public scripts
+  - unexpected public substrate files
+```
+
+Command:
+
+```sh
+npm run release:scan
+```
+
+## Package Readiness Check
+
+Use `etiquette release readiness --json` before changing distribution settings. It reports private-package, files allowlist, pack-canary, checksum/signature, shell-installer presence, pinned public-key bootstrap support, Codex compatibility, and wrapper gaps; it cannot publish, flip `private`, update Codex, or create a channel.
+Codex-backed remote-runtime, plugin-MCP, and hook/action-auth canaries require CLI `0.141.0`+ (`docs/CODEX_CLIENT_COMPATIBILITY.md`). GA additionally runs `etiquette release ga-readiness --channel shell-installer,npm --tag-free-confirmed --json`; it requires a non-prerelease version, final tarball checksums, trusted RSA signature, private-compatible channels, and explicit remote-tag uniqueness confirmation, while still unable to publish, sign, tag, or create a channel. Git source archives must exclude maintainer-only `internal/`, `conformance/`, `site/`, `fixtures/`, `apps/`, local state, and `dist/`.
+
+## Local-Thin Purge (v0.2.1)
+
+```yaml
+excluded_cli_commands: [remote, agent-plane, mcp, parity, linear, integration]  # guarded stubs explain absence
+excluded_source_dirs: [agent-plane/, integration/, linear/, mcp/]  # parity/ ships (console dependency)
+excluded_templates: [hosted-receiver/]
+removed_from_templates: [codex-seat etiquette-monitor-pull]  # use `etiquette notify poll`
+doctrine: local set stays thin and provider-neutral; remote/hosted surfaces are source-only until remote lanes open; zero coordination-bus coupling ships
+```

package/docs/SEAT_DISCIPLINE.md

@@ -0,0 +1,116 @@
+# Seat Discipline
+
+Seat discipline keeps agent work useful, attributable, and portable across
+runtimes. Mechanics say what to do; discipline says when to distrust yourself.
+It is organized by moment of need, not by topic.
+
+## On Wake
+
+- Orient before acting: `whereami`, then the task envelope, then the runbook.
+- Read tiered: status line first, then the exact entry, then the full
+  artifact. Never bulk-load directories for "context" — load the specific
+  receipt you were pointed to.
+
+## Before Claiming Anything
+
+- Verify at claim time: re-read the source at the moment you assert it,
+  never from memory of an earlier read. A cited manifest or spec is read in
+  the same act as the claim.
+- Check the live tip, not your notes: logs and board notes lag integrations.
+- When another seat or a human holds the ground truth, ask — do not
+  solo-reconstruct their state.
+
+## Before Writing
+
+- Read the machine fields, not the title: the envelope's mode and allowed
+  writes decide what a task may do; prose is not authority.
+- Search the exact target surface before classifying work as new — most
+  "add X" tasks are "finish the X that half-exists."
+- One writer per canonical mutation. Design in parallel; mutate single-file.
+
+## While Working
+
+- Technical register on the record: schemas, fields, commands, refs.
+  Metaphor and personality stay in chat; the record is for the next reader.
+- No person or vendor names in artifacts. Attribute external material at the
+  moment of incorporation, with license.
+- One meaningful update per note, reader-resolvable without tooling. Write
+  runbook notes, not raw transcript dumps.
+
+## Before Returning
+
+- Receipt first: outcome, changed files, validation command and result,
+  blockers, next owner. No raw logs — cite paths to them.
+- Run validation before returning the receipt. A red validation is reported
+  red; "done" without proof is a defect, not a return.
+- If your change altered a source shape, refresh its recorded evidence in
+  the same commit.
+- Run post-commit hygiene (`git diff --check HEAD~..HEAD`) — pre-commit
+  checks miss freshly added files.
+
+## On Review
+
+- Verify the shipped artifact, not the branch state you remember.
+- Reviews return evidence, never authority: confirm, counter, or advise.
+  A reviewer packet does not mutate the lane it reviews.
+- Accepted review is different from integrated work.
+- Proposals carry their own counter-arguments and open questions — invite
+  the pressure test.
+
+## At Authority Edges
+
+- Stop when authority is unclear, validation cannot run, writes would exceed
+  the envelope, a secret appears, or the session is unbounded.
+- Never claim work was authorized without decision language from the
+  authority holder. Enthusiasm is not routing.
+- Risk-tier your own gates: proceed on cheap-and-reversible; insist on a
+  real decision for irreversible, authority-changing, or spend actions.
+  Gating everything trains the rubber-stamp.
+- Promote only through the policy-resolved gate.
+- Memory proposes. Ledgers authorize. Receipts prove. Audit accounts.
+
+## When Blocked
+
+- Use the diagnostics verbs before hand-debugging; walk the recovery path
+  from the user's seat before declaring a state recoverable.
+- Escalate with a concrete blocker, not a vibe. Quiet is not a finding.
+
+## Identity Split
+
+```yaml
+operator_principal: human accountable for intent or approval
+execution_seat: durable work identity or runtime capability
+runtime: tool or model that executed
+session: bounded run that produced evidence
+repo_substrate: source, ledger, receipts, validation, commits
+```
+
+## Work Boundaries
+
+A seat should know: allowed writes; forbidden writes; validation commands;
+stop conditions; expected receipt; next owner. If any are missing, ask for a
+sharper task. Sessions are for bounded work; restoring a session restores
+context, not authority.
+
+## Tool Discipline
+
+Chat is conversation, planning tools are intent, code review tools are diffs
+and CI, incident tools are runtime evidence, identity providers are
+authentication. None of them are acceptance.
+
+## Failure Signals
+
+Open a follow-up or stop the run when a seat edits outside allowed writes,
+validation repeatedly fails, the runbook grows without a receipt, a task
+spans unrelated repos, a runtime claims success without evidence, a
+projection disagrees with git, a grant owner is unclear, or an integration
+tries to close or promote work.
+
+## Growing Local Discipline
+
+This document ships the judgment that is true everywhere. Your team's own
+calibration — which seats are strong where, which tools misbehave, which
+routes need a second look — is grown locally: when a correction lands, record
+it as one small note with why and how-to-apply, index it, and re-read it at
+the moment you would otherwise repeat the mistake. Corrections that are never
+recorded are corrections you will pay for twice.

package/docs/SEAT_PROVISIONING.md

@@ -0,0 +1,100 @@
+# Seat Provisioning
+
+Start with one project owner and one review seat. Add runtime-specific seats only when a concrete task needs them. Use [LANE_PROVISIONING.md](LANE_PROVISIONING.md) when a manager needs to route active work, park future work, or give a new agent a complete pickup bulletin.
+
+## Minimal Flow
+
+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`.
+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.
+8. Add extra sessions only when starter sessions are not enough.
+9. Give each seat its allowed writes and validation.
+10. Record a receipt before asking for promotion.
+
+```sh
+etiquette setup --target codex --project "$PWD"
+etiquette bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etiquette whereami --project "$PWD" --seat codex-seat --task APP-001
+etiquette doctor --project "$PWD"
+etiquette status --project "$PWD"
+etiquette join --project "$PWD" --seat codex-seat
+etiquette pickup --project "$PWD" --seat codex-seat --task APP-001 --text
+etiquette console board --project "$PWD" --text
+```
+
+## Seat Types
+
+Use `control_seat` for local workflow ownership, `execution_seat` for bounded implementation, `review_seat` for pressure testing, and `seat_maintainer` for runtime-specific guidance. Seats are roles. People and model sessions occupy them.
+
+## Greenfield Setup
+
+```sh
+etiquette bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix FOOD \
+  --lead-seat impl-seat --lead-principal developer-1 --review-seat review-seat --review-principal reviewer-1
+```
+
+```sh
+etiquette whereami --project "$PWD" --seat impl-seat --task FOOD-001
+etiquette join --project "$PWD" --seat impl-seat
+etiquette pickup --project "$PWD" --seat impl-seat --task FOOD-001 --text
+```
+
+The starter runbook is enough for normal pickup. Use `session create` only when an extra ad hoc session needs a different scope.
+
+The lead seat coordinates. The review seat pressure-tests. Neither gets merge or promotion authority unless policy grants it.
+
+Hooks, readiness, and lifecycle preflight are evidence only. The task envelope and allowed writes remain the active work authority.
+
+## Child Runners
+
+Use node delegation when a lead seat or runner needs bounded child work without creating a new durable seat.
+
+The parent issues an explicit child lease. The child lease must be a subset of the parent lease: same workflow and lane, shorter or equal TTL, narrower or equal authority scope, subset tools, subset write paths, inherited forbidden actions, reduced child budget, and reduced depth.
+
+Child runners return to their immediate parent. The parent synthesizes one upstream receipt and owns cleanup. A child or headless node is disposable by default; durable seat status still requires enrollment and readiness.
+
+## Runtime Seats
+Runtime-specific seats are optional adapters. Add them after task assignment:
+
+```sh
+sh templates/seat-packs-v0/bin/provision-seat codex /tmp/dev-codex-seat
+sh templates/seat-packs-v0/bin/provision-seat claude-code /tmp/dev-claude-code-seat
+sh templates/seat-packs-v0/bin/provision-seat gemini /tmp/dev-gemini-seat
+sh templates/seat-packs-v0/bin/provision-seat ollama /tmp/dev-ollama-seat
+sh templates/seat-packs-v0/bin/provision-seat openrouter /tmp/dev-openrouter-seat
+```
+
+Use `auto` only when exactly one runtime is obvious; use `seat-session-bootstrap` inside a live agent session.
+
+For bounded, cursor-based wake checks on any seat, use the portable core command: `etiquette notify poll --seat <id> --after-seq <n>`. It is read-only and does not grant authority. Seat packs do not bundle coordination-bus monitor skills; monitoring stays operator-armed.
+
+## Readiness
+
+```sh
+etiquette seat readiness \
+  --project "$PWD" \
+  --seat codex-seat \
+  --seat-type execution_seat \
+  --execution-surface codex \
+  --capability-source local_validation \
+  --operational-status operational \
+  --model-tier frontier_high_reasoning
+
+etiquette seat status --project "$PWD"
+```
+
+Agent confidence is not readiness. Readiness is declared capability plus local evidence.
+
+## Managed Runtime Infrastructure
+Remote execution is a later layer. Plane provisioning is infra-admin scoped. Workspace provisioning is bounded to the verified initiator and owner. Neither grants workflow authority by itself.
+
+## Rules
+- 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.

package/docs/TEAM_HANDOFF.md

@@ -0,0 +1,190 @@
+# Team Handoff
+
+Use this when a manager gives Etiquette to developers from a private release
+asset before public hosted distribution is approved.
+
+Target loop:
+
+```text
+install once -> clone or create repo -> bootstrap local -> seat pickup -> receipt
+```
+
+Prereqs: Git and Bun `>=1.3.0`; installer use also needs curl, openssl,
+shasum, and tar. The project repo should not depend on Etiquette as an npm
+package. The CLI lives in the developer's user-local install root.
+
+## Inputs
+
+The manager provides release version, installer URL or path, release base URL
+or local release directory, release public key, project repo or greenfield
+name, lead seat, review seat, and first task prefix.
+
+Default starter profile: lead `codex-seat`, review `cc-seat`, bootstrap
+`manager-seat`, task prefix `APP`.
+
+## Install CLI
+
+Public hosted install is parked. Use a private release asset or signed team
+bundle. Required bundle files:
+
+```text
+install.sh
+releases/<version>/etiquette-<version>.tgz
+releases/<version>/SHA256SUMS
+releases/<version>/SHA256SUMS.sig
+```
+
+The manager may also provide `releases/<version>/etiquette-release.pub` and its
+SHA-256. The private signing key is never distributed.
+
+Remote private asset:
+
+```sh
+curl -fsSL "$ETQ_INSTALLER_URL" -o "${TMPDIR:-.}/etiquette-install.sh"
+sh "${TMPDIR:-.}/etiquette-install.sh" \
+  --version "$ETQ_VERSION" \
+  --base-url "$ETQ_RELEASES_URL" \
+  --public-key "$ETQ_PUBLIC_KEY" \
+  --install-root "$HOME/.etiquette" \
+  --modify-profile
+```
+
+Local signed bundle:
+
+```sh
+ETQ_RELEASES_DIR=/path/to/dist/releases
+ETQ_PUBLIC_KEY=/path/to/dist/releases/1.0.0/etiquette-release.pub
+
+sh /path/to/dist/install.sh \
+  --version 1.0.0 \
+  --base-url "file://$ETQ_RELEASES_DIR" \
+  --public-key "$ETQ_PUBLIC_KEY" \
+  --install-root "$HOME/.etiquette" \
+  --modify-profile
+```
+
+If needed:
+
+```sh
+export PATH="$HOME/.etiquette/bin:$PATH"
+etiquette help
+etiquette-core help
+```
+
+Uninstall: run `sh scripts/uninstall.sh --dry-run`, then `--yes`; project `.etiquette` and `docs/work` stay.
+
+This is still a private team canary. Do not upload the bundle, create a public
+tag, publish to npm, or replace the public placeholder installer until the
+release owner explicitly grants that distribution step.
+
+## Prepare Repo
+
+Existing repo:
+
+```sh
+git clone "$PROJECT_REPO" app
+cd app
+```
+
+Greenfield repo:
+
+```sh
+mkdir app
+cd app
+git init -b main
+printf 'node_modules/\n.DS_Store\nnpm-debug.log*\n' > .gitignore
+git add .gitignore
+git commit -m "chore: baseline empty workspace"
+```
+
+## Bootstrap Local Etiquette
+
+```sh
+etiquette handoff --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etiquette bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etiquette doctor --project "$PWD"
+etiquette console board --project "$PWD" --text
+```
+
+`handoff` executes nothing. `bootstrap local` creates repo-local `.etiquette`
+state, `docs/work` task envelopes, seat cards, bounded session runbooks, local
+packet events, and pickup docs. It does not write a global bus, publish, push,
+merge, close, promote, or grant authority.
+
+Commit the bootstrap baseline when the project owner is ready:
+
+```sh
+git add .etiquette docs/work AGENTS.md
+git commit -m "chore: bootstrap etiquette workspace"
+```
+
+## Seat Pickup
+
+Lead seat:
+
+```sh
+etiquette whereami --project "$PWD" --seat codex-seat --task APP-001
+etiquette join --project "$PWD" --seat codex-seat
+etiquette pickup --project "$PWD" --seat codex-seat --task APP-001 --text
+```
+
+Review seat:
+
+```sh
+etiquette whereami --project "$PWD" --seat cc-seat --task APP-002
+etiquette join --project "$PWD" --seat cc-seat
+etiquette pickup --project "$PWD" --seat cc-seat --task APP-002 --text
+```
+
+Inside Codex sessions that have the pickup skill installed:
+
+```sh
+~/.codex/skills/etiquette-seat-pickup/scripts/seat-pickup.sh \
+  --project "$PWD" \
+  --seat codex-seat \
+  --task APP-001 \
+  --etq "$(command -v etiquette)"
+```
+
+The wrapper prints board, feed, inbox, task envelope, and session runbook. It is
+a convenience reader, not authority.
+
+## Local Wake
+
+Seats can refresh their repo-local queue before pickup or review:
+
+```sh
+etiquette notify poll --project "$PWD" --seat codex-seat --text
+```
+
+The queue is a local pointer cache over `.etiquette/events/local.ndjson`. It is
+not a webhook, hosted relay, external bus, workflow ack, or authority source.
+
+## Boundaries
+
+- Use the project repo's `.etiquette` and `docs/work` for routine execution.
+- Keep detailed attempts in `docs/work/sessions/session-<task>/RUNBOOK.md`.
+- Write receipts under `docs/work/receipts/`.
+- Do not use an external global ledger for routine local work.
+- Do not merge, push, close, promote, sign, or grant authority from readiness or
+  pickup alone.
+- Stop when the task needs writes outside its envelope, a secret appears,
+  validation cannot run, or authority is unclear.
+
+## Runtime And Hosted Surfaces
+
+The local devkit intentionally omits infra/runtime commands. If a developer
+runs `etiquette runtime`, the expected result is:
+
+```text
+runtime commands are not included in the local devkit package; use an infra/runtime source workspace.
+```
+
+Remote execution, webhooks, Slack/Teams bots, EKS/Kube, and hosted projection
+are later layers. They must not be treated as part of the local handoff.
+
+## Proven Canary
+
+The native-install canary verified this flow with a signed local release
+fixture, fake `HOME`, user-local install root, clean repo, bootstrap, lead-seat
+pickup, review-seat pickup, runtime quarantine, and clean baseline commit.

package/docs/WORKTREE_QOL.md

@@ -0,0 +1,92 @@
+# Worktree QoL
+
+Use this when a seat works in a branch, a detached worktree, or a resumed agent
+session. The goal is to avoid losing work to ephemeral directories and to keep
+project context separate from runner chat history.
+
+## Stable Lane Worktrees
+
+Prefer durable worktrees for lane work:
+
+```sh
+mkdir -p ../_worktrees
+git worktree add ../_worktrees/APP-001-impl-seat lane/APP-001-domain-foundation
+cd ../_worktrees/APP-001-impl-seat
+```
+
+Use `/tmp` only for disposable experiments. If a task needs review, return, or
+resumption, put the worktree under a predictable project-owned or sibling
+directory such as `_worktrees/`.
+
+Recommended naming:
+
+```text
+_worktrees/<task-id>-<seat-id>
+_worktrees/APP-001-impl-seat
+_worktrees/APP-002-review-seat
+```
+
+## Resume Discipline
+
+Agent resume restores conversation context. It does not prove repo context.
+
+After any resume, run:
+
+```sh
+etiquette whereami --project "$PWD" --seat <seat> --task <task>
+git status -sb
+git branch --show-current
+```
+
+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
+coordination repo or unrelated workspace.
+
+## If A Worktree Is Gone
+
+Do not reconstruct from chat. Recreate from Git:
+
+```sh
+git worktree list
+git branch --list 'lane/*'
+mkdir -p ../_worktrees
+git worktree add ../_worktrees/APP-001-impl-seat lane/APP-001-domain-foundation
+cd ../_worktrees/APP-001-impl-seat
+etiquette whereami --project "$PWD" --seat impl-seat --task APP-001
+```
+
+If the branch was never committed or pushed, treat the lost worktree as lost
+work unless there is a durable receipt, patch, or runbook artifact. Do not claim
+completion from memory.
+
+## Evidence And Return
+
+Keep detailed execution notes in the session runbook:
+
+```text
+docs/work/sessions/session-<task>/RUNBOOK.md
+```
+
+Return through the repo-local packet/event flow. Before asking a reviewer to
+pick up the task, verify:
+
+```sh
+etiquette return check --project "$PWD" --task <task> --seat <seat>
+etiquette diagnostics no-return --project "$PWD" --task <task> --seat <seat>
+```
+
+For remote/headless runners, use the hard gate:
+
+```sh
+etiquette return check --project "$PWD" --task <task> --seat <seat> --remote-runner
+```
+
+## Forbidden Shortcuts
+
+- Do not treat an agent transcript as the branch, task, or receipt.
+- Do not use a global handshake bus for routine repo-local execution.
+- Do not keep long-running implementation work only in `/tmp`.
+- Do not ask a reviewer to act until the branch and repo-local return are
+  visible.
+- Do not merge, close, publish, or promote because a worktree exists.