@etiquekit/etq 1.0.13 → 1.0.14

package/README.md

@@ -1,78 +1,80 @@
 # Etiquette
 
-Etiquette is a governance and evidence CLI for agent-assisted engineering work.
+Etiquette is a local-first workflow and evidence CLI for teams that use coding
+agents. Each task gets a named seat, bounded write scope, validation contract,
+and receipt. Agents execute and report evidence; your human or Git gate still
+decides what becomes canonical.
 
-It answers the questions that matter when agents help write code: who acted,
-under which seat, inside what scope, with what evidence, and who accepted the
-result.
+## Install
 
-Default loop: `setup -> handoff -> bootstrap local -> whereami -> doctor -> join -> pickup -> receipt -> promotion gate`.
+Prerequisites: Git `>=2.40` and Bun `>=1.3`.
 
-Execution runtimes are optional; they return evidence and do not mint authority.
+```sh
+npm install --global @etiquekit/etq
+etq --version
+```
+
+`etq` and `etiquette` are aliases for the same CLI.
 
-## Start
+## Start A Governed Task
 
-Prereqs: Git and Bun `>=1.3.0`; the CLI shims require `bun` on `PATH`.
-For a clean repo or a new seat, read [QuickStart.md](QuickStart.md). For private team rollout, use [docs/TEAM_HANDOFF.md](docs/TEAM_HANDOFF.md), then:
+Run inside a Git repository:
 
 ```sh
-./bin/etiquette setup --target codex --project /tmp/etiquette-start
-./bin/etiquette handoff --project /tmp/etiquette-start --task-prefix APP
-./bin/etiquette bootstrap local --project /tmp/etiquette-start --task-prefix APP
-./bin/etiquette whereami --project /tmp/etiquette-start --seat impl-seat --task APP-001
-./bin/etiquette doctor --project /tmp/etiquette-start
-./bin/etiquette status --project /tmp/etiquette-start
-./bin/etiquette join --project /tmp/etiquette-start --seat impl-seat
-./bin/etiquette pickup --project /tmp/etiquette-start --seat impl-seat --task APP-001 --allow-current-project --text
-./bin/etiquette console board --project /tmp/etiquette-start --text
+etq bootstrap local --project . --task-prefix APP --ask
+etq doctor --project .
+etq whereami --project . --seat impl-seat --task APP-001
+etq join --project . --seat impl-seat
+etq pickup --project . --seat impl-seat --task APP-001 --allow-current-project --text
 ```
 
-`handoff` is a read-only guide: it prints install, bootstrap, and pickup commands without installing, bootstrapping, pushing, closing, or granting.
+The default is one implementation seat and one bounded task. Etiquette asks
+before adding review seats and remains non-interactive in CI. A seat is a
+durable role; Claude Code, Codex, Gemini, or another runtime is its temporary
+occupant.
 
-`bootstrap local` creates repo-local seats, task envelopes, bounded runbooks,
-local packet events, and pickup docs without global bus writes or authority.
-`whereami` is the context readback: runner resume restores conversation
-history; `whereami` tells the seat which project, worktree, task, and runbook it
-is actually operating in.
+## Daily Loop
 
-Use repo-local commands for now. The hosted public installer is parked.
+```text
+orient -> pick up bounded work -> implement -> validate -> return a receipt -> promote through the existing gate
+```
 
-## Core Concepts
+Use `whereami`, `status`, `console board`, and `return check` to inspect work.
+Read commands do not initialize directories or rewrite event streams. Explicit
+setup, bootstrap, post, and lifecycle commands own their writes.
 
-- Seat: durable work identity; the occupant or model can change.
-- Task envelope: scope, allowed writes, validation, and stop conditions.
-- Receipt: evidence of what happened; it proves but does not authorize.
-- Promotion gate: the human/Git gate where candidate work becomes truth.
-- Ledger: durable local record of sessions, receipts, and decisions.
+## Core Records
 
-Read next: [docs/README.md](docs/README.md), [docs/CONCEPTS.md](docs/CONCEPTS.md), [docs/CORE_PROFILE.md](docs/CORE_PROFILE.md), [docs/SEAT_PROVISIONING.md](docs/SEAT_PROVISIONING.md), and [docs/WORKTREE_QOL.md](docs/WORKTREE_QOL.md).
+- **Seat:** durable work identity, independent of model or vendor.
+- **Task envelope:** allowed writes, required validation, and stop conditions.
+- **Receipt:** evidence of what ran and changed; evidence is not authority.
+- **Local ledger:** Git-readable events and packet references.
+- **Promotion gate:** the existing decision that accepts candidate work.
 
-Provision runtime seats only after assignment:
+Etiquette is not a hosted executor, transport service, portal, or replacement
+for source-control permissions. Consumers may bind packet profiles and their
+own transport; the package does not silently write a global ledger.
 
-```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
-```
-
-## Validate
+## Author A Draft Without Project State
 
 ```sh
-npm run release:scan
-bun test
-npm run typecheck
+etq post --profile ./packet-profile.yaml --draft \
+  --out /tmp/review-return.md --kind review-return --work-id APP-001 \
+  --author impl-seat --recipient review-seat \
+  --summary "Implementation complete." --evidence "Checks passed." \
+  --next-step "Review the candidate."
 ```
 
-## Release Status
+Draft mode writes only the requested output. It does not create `.etiquette`,
+emit an event, grant authority, merge, close, or publish.
 
-```yaml
-default_surface: templates/etiquette-vanilla-v0
-optional_runtime_surface: templates/seat-packs-v0
-public_installer: held
-```
+Optional runtime packs: `provision-seat claude-code`, `provision-seat codex`, `provision-seat gemini`, `provision-seat ollama`, `provision-seat openrouter`.
+## Documentation
+
+[Quick start](QuickStart.md) | [Concepts](docs/CONCEPTS.md) |
+[Core profile](docs/CORE_PROFILE.md) | [Seats](docs/SEAT_PROVISIONING.md) |
+[Worktrees](docs/WORKTREE_QOL.md)
 
 ## License
 
-Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/docs/RELEASE_SURFACE_AUDIT.md

@@ -94,7 +94,7 @@ package_surface:
   npm_pack_entries: 183
   max_budget: 190
   posture: local devkit package plus signed user-local installer
-  distribution_origin: https://etiquette.example.com
+  distribution_origin: https://etiquekit.com
   excludes: workspace package metadata, workspace fixtures, internal, conformance, apps, site, dist, hosted parity docs, portal docs, root kernel manuals
 ```
 
@@ -142,7 +142,7 @@ npm run release:scan
 
 ## Package Readiness Check
 
-Use `etiquette release readiness --json` before changing distribution settings. It also binds the canonical package identity, version floor, source-shipping mode, required bins, source ancestry, and candidate verifier to `release/lineage.v0.json`; `release:candidate` preserves the exact verified tarball and checksum under ignored `dist/` for later signing without rebuilding.
+Use `etiquette release readiness --json` before changing distribution settings. It also binds the canonical package identity, version floor, source-shipping mode, required bins, source ancestry, public distribution repository, and candidate verifier to `release/lineage.v0.json`; the source-of-record and public package home remain separate, explicit lineage fields. `release:candidate` preserves the exact verified tarball and checksum under ignored `dist/` for later signing without rebuilding.
 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etiquekit/etq",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Governance and evidence CLI for AI-assisted engineering seats.",
   "private": false,
   "type": "module",
@@ -51,9 +51,9 @@
   "homepage": "https://etiquekit.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/leepickdev/etq-devkit.git"
+    "url": "git+https://github.com/leepickdev/etq.git"
   },
   "bugs": {
-    "url": "https://github.com/leepickdev/etq-devkit/issues"
+    "url": "https://github.com/leepickdev/etq/issues"
   }
 }

package/packages/control/src/cli/commands/local-workflow.ts

@@ -550,6 +550,14 @@ function isInitializedLocalProject(root: string): boolean {
   return existsSync(projectBindingPath(root)) && existsSync(eventPath(root));
 }
 
+async function requireInitializedProjectBinding(root: string, command: string): Promise<NonNullable<Awaited<ReturnType<typeof readProjectBinding>>>> {
+  const project = await readProjectBinding(root);
+  if (!project || !isInitializedLocalProject(root)) {
+    throw new Error(`${command} requires an initialized local Etiquette project; run etiquette init --project <path> first`);
+  }
+  return project;
+}
+
 function relativeRef(root: string, path: string): string {
   const rel = relative(root, resolve(path));
   if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
@@ -1368,8 +1376,8 @@ async function ensureLocalProject(root: string): Promise<void> {
 }
 
 async function readEvents(root: string): Promise<LocalEvent[]> {
-  await ensureLocalProject(root);
-  const raw = await readFile(eventPath(root), 'utf-8');
+  const raw = await readTextIfExists(eventPath(root));
+  if (!raw) return [];
   return raw
     .split('\n')
     .map((line) => line.trim())
@@ -1844,17 +1852,14 @@ async function validateSeatCard(path: string): Promise<string> {
 }
 
 async function enrollmentPath(root: string, seat: string): Promise<string> {
-  await ensureLocalProject(root);
   return join(root, '.etiquette', 'roster', 'enrollments', `${safeName(seat)}.json`);
 }
 
 async function subscriptionPath(root: string, seat: string): Promise<string> {
-  await ensureLocalProject(root);
   return join(root, '.etiquette', 'notify', 'subscriptions', `${safeName(seat)}.json`);
 }
 
 async function wakeQueuePath(root: string, seat: string): Promise<string> {
-  await ensureLocalProject(root);
   return join(root, '.etiquette', 'notify', 'queues', `${safeName(seat)}.json`);
 }
 
@@ -2492,7 +2497,6 @@ async function retirePath(
 async function dispatchTrash(positionals: string[], flags: Record<string, string | boolean>): Promise<void> {
   const verb = positionals[1];
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
 
   if (verb === 'retire') {
     await retirePath(requirePositional(positionals, 2, 'path'), flags);
@@ -2521,6 +2525,7 @@ async function dispatchTrash(positionals: string[], flags: Record<string, string
   }
 
   if (verb === 'restore') {
+    await ensureLocalProject(root);
     const trashId = requirePositional(positionals, 2, 'trash-id');
     const entries = await readTrashEntries(root);
     const entry = entries.find((candidate) => candidate.trash_id === trashId);
@@ -2550,6 +2555,7 @@ async function dispatchTrash(positionals: string[], flags: Record<string, string
   }
 
   if (verb === 'rebuild') {
+    await ensureLocalProject(root);
     const events = await readEvents(root);
     const entries = events
       .map((event) => asRecord(event, 'local event').trash_entry)
@@ -3041,8 +3047,7 @@ async function dispatchHandoff(flags: Record<string, string | boolean>): Promise
 
 async function dispatchJoin(flags: Record<string, string | boolean>): Promise<void> {
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
-  const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
+  const project = await requireInitializedProjectBinding(root, 'join');
   assertEngagementProject(project.project_id, optionalString(flags, 'expect-project-id'), 'current project');
   const seatInput = requireString(flags, 'seat');
   const resolvedSeat = resolveSeatFromEnrollments(await listEnrollments(root), seatInput);
@@ -3519,8 +3524,7 @@ async function dispatchWhereami(flags: Record<string, string | boolean>): Promis
 
 async function dispatchPickup(flags: Record<string, string | boolean>): Promise<void> {
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
-  const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
+  const project = await requireInitializedProjectBinding(root, 'pickup');
   assertPickupProjectExpectation(project.project_id, flags);
   const seatInput = requireString(flags, 'seat');
   const task = requireString(flags, 'task');
@@ -3624,7 +3628,6 @@ async function dispatchAudit(positionals: string[], flags: Record<string, string
 async function dispatchRoster(positionals: string[], flags: Record<string, string | boolean>): Promise<void> {
   const verb = positionals[1];
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
 
   if (verb === 'card') {
     const cardVerb = positionals[2];
@@ -3636,6 +3639,7 @@ async function dispatchRoster(positionals: string[], flags: Record<string, strin
   }
 
   if (verb === 'enroll') {
+    await ensureLocalProject(root);
     const seat = requirePositional(positionals, 2, 'seat');
     const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
     const card = requireString(flags, 'card');
@@ -3687,6 +3691,7 @@ async function dispatchRoster(positionals: string[], flags: Record<string, strin
   }
 
   if (verb === 'ready') {
+    await ensureLocalProject(root);
     const seat = requirePositional(positionals, 2, 'seat');
     const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
     const path = await enrollmentPath(root, seat);
@@ -3732,6 +3737,7 @@ async function dispatchRoster(positionals: string[], flags: Record<string, strin
   }
 
   if (verb === 'lifecycle') {
+    await ensureLocalProject(root);
     const seat = requirePositional(positionals, 2, 'seat');
     const rawState = requireString(flags, 'state');
     assertLifecycleState(rawState, '--state');
@@ -3963,9 +3969,8 @@ async function dispatchNotify(positionals: string[], flags: Record<string, strin
     return;
   }
 
-  await ensureLocalProject(root);
-
   if (verb === 'subscribe') {
+    await ensureLocalProject(root);
     const seatInput = requireString(flags, 'seat');
     const resolvedSeat = resolveSeatFromEnrollments(await listEnrollments(root), seatInput);
     const seat = resolvedSeat.seat;
@@ -4004,6 +4009,7 @@ async function dispatchNotify(positionals: string[], flags: Record<string, strin
   }
 
   if (verb === 'poll') {
+    await ensureLocalProject(root);
     const seatInput = requireString(flags, 'seat');
     const resolvedSeat = resolveSeatFromEnrollments(await listEnrollments(root), seatInput);
     const seat = resolvedSeat.seat;
@@ -4121,7 +4127,6 @@ async function dispatchRig(positionals: string[], flags: Record<string, string |
   const verb = positionals[1];
   if (verb !== 'doctor') throw new Error('rig verb must be: doctor');
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
   const required = [
     projectBindingPath(root),
     eventPath(root),
@@ -4130,7 +4135,8 @@ async function dispatchRig(positionals: string[], flags: Record<string, string |
   ];
   const missing = required.filter((path) => !existsSync(path));
   if (missing.length > 0) throw new Error(`rig doctor failed; missing: ${missing.map((path) => relativeRef(root, path)).join(', ')}`);
-  const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
+  const project = await readProjectBinding(root);
+  if (!project) throw new Error('rig doctor failed; project binding is missing');
   const sessions = await listSessions(root);
   const mismatched = sessions.filter((session) => session.project_id !== project.project_id);
   if (mismatched.length > 0) {
@@ -4236,7 +4242,6 @@ async function dispatchBus(positionals: string[], flags: Record<string, string |
     console.log(format === 'markdown' ? renderLocalLedgerViewMarkdown(view) : renderLocalLedgerViewText(view));
     return;
   }
-  await ensureLocalProject(root);
   const events = await readEvents(root);
 
   if (verb === 'status') {
@@ -4263,14 +4268,14 @@ async function dispatchBus(positionals: string[], flags: Record<string, string |
 
 async function dispatchStatus(flags: Record<string, string | boolean>): Promise<void> {
   const root = projectRoot(flags);
-  await ensureLocalProject(root);
-  const project = await ensureProjectBinding(root, optionalString(flags, 'at'));
+  const project = await readProjectBinding(root);
   const events = await readEvents(root);
   const enrollments = await listJsonFiles(join(root, '.etiquette', 'roster', 'enrollments'));
   console.log([
     'workspace_status:',
     `  project: ${root}`,
-    `  project_id: ${project.project_id}`,
+    `  project_id: ${project?.project_id ?? 'none'}`,
+    `  initialized: ${String(isInitializedLocalProject(root))}`,
     `  events: ${events.length}`,
     `  enrolled_seats: ${enrollments.length}`,
     '  authority_boundary: read_only_without_grant',
@@ -4666,7 +4671,6 @@ export async function dispatchLocalWorkflow(
 
 export async function renderLocalBoard(projectRoot: string, seat?: string): Promise<string> {
   const root = resolve(projectRoot);
-  await ensureLocalProject(root);
   const resolvedSeat = seat ? resolveSeatFromEnrollments(await listEnrollments(root), seat) : null;
   const boardSeat = resolvedSeat?.seat ?? null;
   const board = await readTextIfExists(join(root, 'docs', 'work', 'BOARD.md'));

package/packages/control/src/release/readiness.ts

@@ -452,6 +452,7 @@ async function appendReleaseLineageChecks(
   const registryFloor = asString(lineage.registry_floor);
   const distributionMode = asString(lineage.distribution_mode);
   const sourceRepository = asString(lineage.source_repository);
+  const distributionRepository = asString(lineage.distribution_repository);
   const sourceBaseCommit = asString(lineage.source_base_commit);
   const requiredBins = asStringArray(lineage.required_bins);
   const packageRepository = repositoryUrl(packageJson.repository);
@@ -491,14 +492,24 @@ async function appendReleaseLineageChecks(
       'restore all reviewed CLI aliases before building the candidate',
     ));
 
-  checks.push(sourceRepository && packageRepository === sourceRepository
-    ? check('pass', 'release_source_repository', `package repository matches lineage: ${sourceRepository}`, RELEASE_LINEAGE_REF)
+  checks.push(sourceRepository
+    ? check('pass', 'release_source_repository', `source repository is declared: ${sourceRepository}`, RELEASE_LINEAGE_REF)
     : check(
       'block',
       'release_source_repository',
-      `package repository does not match lineage: package=${packageRepository ?? 'unknown'} lineage=${sourceRepository ?? 'unknown'}`,
+      'source repository is missing from release lineage',
       RELEASE_LINEAGE_REF,
-      'point package metadata at the reviewed public source repository',
+      'declare the reviewed source-of-record repository',
+    ));
+
+  checks.push(distributionRepository && packageRepository === distributionRepository
+    ? check('pass', 'release_distribution_repository', `package repository matches public distribution home: ${distributionRepository}`, RELEASE_LINEAGE_REF)
+    : check(
+      'block',
+      'release_distribution_repository',
+      `package repository does not match public distribution home: package=${packageRepository ?? 'unknown'} lineage=${distributionRepository ?? 'unknown'}`,
+      RELEASE_LINEAGE_REF,
+      'point package metadata at the reviewed public distribution repository',
     ));
 
   const shipsSource = packageInfo.files.includes('packages/control/src/')

package/release/lineage.v0.json

@@ -1,11 +1,12 @@
 {
   "schema": "etq-release-lineage.v0",
   "package_name": "@etiquekit/etq",
-  "candidate_version": "1.0.13",
+  "candidate_version": "1.0.14",
   "distribution_mode": "bun-typescript-source",
   "source_repository": "git+https://github.com/leepickdev/etq-devkit.git",
-  "source_base_commit": "7096242dcc47a3edbf87b9b61720b92cb01ba3aa",
-  "registry_floor": "1.0.12",
+  "distribution_repository": "git+https://github.com/leepickdev/etq.git",
+  "source_base_commit": "b2384dc782548ce0d712da3bd33e108d977adb44",
+  "registry_floor": "1.0.13",
   "required_bins": [
     "etq",
     "etiquette",