@etiquekit/etq 0.0.1 → 1.0.1

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

@@ -0,0 +1,116 @@
+# ledger-entry.v0.1
+
+`ledger-entry.v0.1` is a narrow retrieval amendment over `ledger-entry.v0`.
+It adds advisory topic and status metadata for local retrieval only. It does
+not authorize work, attach grants, close tasks, or replace receipts.
+
+## Compatibility
+
+Existing `ledger-entry.v0` rows remain valid. Consumers must treat missing
+fields as:
+
+```yaml
+topic_hints: []
+status_effect: none
+```
+
+Writers may populate these fields only from explicit operator input, explicit
+agent input, or known command context. They must not infer topics or status
+effects from narrative prose.
+
+## Added Fields
+
+```yaml
+topic_hints:
+  type: string[]
+  default: []
+  format: kebab-case
+  max_items: 8
+  authority: advisory_hint_only
+
+status_effect:
+  type: enum
+  default: none
+  values:
+    - none
+    - observed
+    - changed
+    - gap_found
+    - reserved
+    - closed
+    - proved
+  authority: advisory_classification_only
+```
+
+## Compact Ledger Line
+
+`LEDGER.md` may include the added fields as compact key-value tokens:
+
+```text
+- 2026-05-20T09:30:00.000Z schema=ledger-entry.v0.1 entry_id=ledger-entry:topic-snapshot-example entry_type=review spine_eligible=true authority_class=advisory grants_execution=false export_class=workspace_shared refs=bus:events://1870,artifacts:docs/work/topic-snapshots/example.md topic_hints=ledger-retrieval,local-remote-sync status_effect=gap_found authority=advisory-only
+```
+
+Omitted `topic_hints` means no topic hints. Omitted `status_effect` means
+`none`.
+
+## Local Retrieval Index
+
+V0.1 permits a generated local SQLite/FTS5 cache at:
+
+```text
+.etiquette/state/ledger/index.db
+```
+
+The index is derived and uncommitted. It is not canonical. Search results from
+the index must carry literal authority-false flags:
+
+```yaml
+is_canonical: false
+regenerable: true
+can_authorize: false
+```
+
+Index regeneration policy:
+
+- rebuild from canonical docs and ledger files;
+- never write through from the index into `LEDGER.md`;
+- delete and recreate the generated cache on rebuild;
+- either rebuild explicitly or run a stale-check before using search results.
+
+V0.1 reserves vector search, `sqlite-vec`, Chroma, and Postgres adapters for a
+future lane. SQLite FTS5 is the only retrieval accelerator in this version.
+
+## Local-Private Verbatim Store
+
+V0.1 also reserves an opt-in local-only verbatim store at:
+
+```text
+.etiquette/state/ledger/private-verbatim.db
+```
+
+Rules:
+
+- disabled by default;
+- requires explicit operator opt-in;
+- never committed;
+- never exported to hosted or shared projection;
+- no automatic capture of session chat, bus packets, prompts, or tool output;
+- any stored chunks must carry `export_class: local_private`.
+
+Shared exports may include summaries and durable refs only.
+
+## Authority Boundary
+
+```yaml
+authority_boundary:
+  can_authorize_work: false
+  can_execute_work: false
+  can_attach_grant: false
+  can_close_task: false
+  can_replace_receipt: false
+  can_replace_audit_log: false
+```
+
+The ledger remains accountable truth. The index accelerates retrieval.
+Verbatim memory stays local-private. Snapshots and capsules interpret with
+citations. Receipts prove.

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

@@ -0,0 +1,90 @@
+# ledger-entry.v0.2
+
+`ledger-entry.v0.2` is a narrow bitemporal amendment over `ledger-entry.v0.1`.
+It separates when a covered piece of work happened from when the ledger
+learned about it, and it adds one entry type for honest late recording. It
+does not authorize work, attach grants, close tasks, or replace receipts.
+
+## The rule this encodes
+
+```text
+The leading timestamp (created_at) is the RECORDING time. It is never
+backdated. If work was done off the spine, it is reconciled with a late
+entry recorded at its true time, pointing at contemporaneous evidence.
+Synthesizing entries with past recording times is corruption, not repair:
+one plausible fake timestamp devalues every real one.
+```
+
+This mirrors standing practice elsewhere: accounting adjusting entries,
+clinical late entries, court orders entered nunc pro tunc, and compensating
+events in event-sourced systems. The formal model is bitemporal data:
+`valid_time` (when it happened) vs transaction time (`created_at`, when it
+was recorded).
+
+## Compatibility
+
+Existing `ledger-entry.v0` and `ledger-entry.v0.1` rows remain valid.
+Consumers must treat missing fields as:
+
+```yaml
+valid_time: (absent -> the covered work happened at recording time)
+valid_time_end: (absent -> point-in-time, not a span)
+```
+
+## Added Fields
+
+```yaml
+valid_time:
+  type: iso8601 timestamp
+  optional: true
+  meaning: when the covered work actually happened (span start if
+    valid_time_end is present)
+  constraint: must not be after created_at
+
+valid_time_end:
+  type: iso8601 timestamp
+  optional: true
+  requires: valid_time
+  constraint: valid_time <= valid_time_end <= created_at
+```
+
+## Added Entry Type
+
+`entry_type: retroactive_import` — a late reconciliation entry covering work
+that was executed without contemporaneous spine entries. Rules, enforced by
+the validator:
+
+- requires schema `ledger-entry.v0.2` (rejected on v0/v0.1);
+- must declare `valid_time` (what period it covers);
+- 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);
+- 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
+  preferred over many synthetic per-event entries.
+
+## Compact Ledger Line
+
+```text
+- 2026-07-02T11:00:00.000Z schema=ledger-entry.v0.2 entry_id=ledger-entry:recon-example entry_type=retroactive_import spine_eligible=true authority_class=audit grants_execution=false export_class=workspace_shared refs=commits:3919c0fa,artifacts:docs/work/huddle/recon-index.md valid_time=2026-07-02T00:40:00.000Z valid_time_end=2026-07-02T10:45:00.000Z
+```
+
+Omitted `valid_time` means the entry covers its own recording moment.
+
+## Consumers
+
+- The local ledger index (`ledger-query-cli.v0.1`) admits v0.2 lines; the
+  bitemporal tokens flow through the parsed `extra` map (no first-class
+  index columns in this amendment).
+- Marination/sabbatical record passes are the intended writer of
+  `retroactive_import` entries: they may reorganize projections and append
+  reconciliations; they must never rewrite or backdate sources (see
+  `internal/docs/operations/MARINATION_CHARTER.md`).
+
+## Boundary
+
+Advisory metadata only. No scoring engine, no automatic drift detection, no
+hosted sync changes, no authority semantics beyond the explicit restriction
+that retroactive entries cannot carry grant authority.

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

@@ -0,0 +1,123 @@
+# ledger-entry.v0
+
+`ledger-entry.v0` is the typed local ledger record used by the reflex spine.
+It makes compact ledger lines structurally queryable without promoting the
+ledger into an authority source.
+
+## Required Shape
+
+```yaml
+schema: ledger-entry.v0
+entry_id: ledger-entry:dispatch-record-example
+created_at: 2026-05-19T09:30:00.000Z
+entry_type: decision
+spine_eligible: true
+authority:
+  class: advisory
+  grants_execution: false
+refs:
+  lanes: []
+  commits: []
+  prs: []
+  bus: []
+  artifacts: []
+  receipts:
+    - docs/work/receipts/example.yaml
+export_class: workspace_shared
+summary: compact operator-readable statement
+legacy:
+  pre_v0: false
+  low_authority: false
+```
+
+## Field Rules
+
+`entry_type` must be one of:
+
+- `decision`
+- `review`
+- `receipt`
+- `audit`
+- `event`
+- `heartbeat`
+- `capability`
+- `incident`
+- `doctrine`
+- `task`
+- `closeout`
+
+`authority.class` must be one of:
+
+- `advisory`
+- `grant`
+- `receipt`
+- `audit`
+- `status`
+
+`authority.grants_execution` defaults to `false`. Only entries with
+`authority.class: grant` may set it to `true`, and only when the entry carries
+the durable grant reference required by the local workflow.
+
+`spine_eligible` is explicit. A reflex index must not infer it from
+`entry_type`. Entries that are useful for current-state routing should set it to
+`true`; archival, noisy, or unreviewed entries should set it to `false`.
+
+`export_class` must be one of:
+
+- `local_private`
+- `workspace_shared`
+- `org_projected`
+- `public_safe`
+
+For entries where `authority.class != advisory`, at least one durable `refs`
+item is required. If evidence is unavailable, the entry must set
+`legacy.low_authority: true` and must not be exported beyond local scope.
+
+## Compact Ledger Line
+
+`LEDGER.md` may store the same object as one compact key-value line:
+
+```text
+- 2026-05-19T09:30:00.000Z schema=ledger-entry.v0 entry_id=ledger-entry:dispatch-record-example entry_type=decision spine_eligible=true authority_class=advisory grants_execution=false export_class=workspace_shared refs=receipts:docs/work/receipts/example.yaml authority=advisory-only
+```
+
+Consumers must tolerate earlier compact lines without `schema=ledger-entry.v0`
+by treating them as:
+
+```yaml
+schema: ledger-entry.v0
+legacy:
+  pre_v0: true
+  low_authority: true
+spine_eligible: false
+```
+
+## Spine And Brain Boundary
+
+```text
+Reflex routes the present.
+Sabbatical understands the arc.
+Capsules compress the arc back into reflex context.
+```
+
+The reflex spine reads typed ledger entries. The sabbatical brain may produce a
+capsule or dossier, but it cannot write back into the spine directly. Promotion
+from capsule to spine requires an explicit operator gate.
+
+## Authority Boundary
+
+Ledger entries may record a grant reference, receipt, review, or status. They do
+not independently authorize, execute, attach grants, close work, replace
+receipts, or replace audit logs.
+
+```yaml
+authority_boundary:
+  can_authorize_work: false
+  can_execute_work: false
+  can_attach_grant: false
+  can_replace_receipt: false
+  can_replace_audit_log: false
+```
+
+The ledger is a durable operational record. It is not a scheduler, worker queue,
+approval engine, or hosted source of truth.

package/docs/contracts/ledger-entry/ledger-query-cli.v0.1.md

@@ -0,0 +1,64 @@
+# ledger-query-cli.v0.1
+
+`ledger-query-cli.v0.1` is the compact-first local reader over the generated
+ledger retrieval index. It does not replace `LEDGER.md`, receipts, grants, or
+audit logs.
+
+## Commands
+
+```text
+etiquette ledger index [--project <path>] [--db <path>] [--json]
+etiquette ledger search <query> [--project <path>] [--db <path>] [--limit <n>] [--json]
+etiquette ledger search --topic <slug> [--project <path>] [--db <path>] [--limit <n>] [--json]
+etiquette ledger show <entry-or-ref-id> [--project <path>] [--db <path>]
+```
+
+## Behavior
+
+- `index` rebuilds the generated SQLite/FTS5 cache from canonical local docs.
+- `search` returns compact metadata only.
+- `show` exact-fetches one ledger entry by entry id or durable ref.
+- `search` and `show` fail if the cache is missing or stale.
+- `--limit` is capped at 50.
+
+## Compact Search Result
+
+```yaml
+entry_id: ledger-entry:topic-snapshot:example
+title: ledger-entry:topic-snapshot:example
+type: review
+topic_hints:
+  - ledger-retrieval
+status_effect: proved
+refs:
+  - bus:events://1890
+confidence: metadata
+is_canonical: false
+regenerable: true
+can_authorize: false
+```
+
+## Exact Fetch Result
+
+`show` returns the compact fields plus the canonical source pointer:
+
+```yaml
+source_path: docs/work/ledger/LEDGER.md
+line_no: 3
+```
+
+It does not bulk dump historical documents.
+
+## Authority Boundary
+
+```yaml
+authority_boundary:
+  can_authorize_work: false
+  can_execute_work: false
+  can_attach_grant: false
+  can_close_task: false
+  can_replace_receipt: false
+  can_replace_audit_log: false
+```
+
+The CLI accelerates retrieval. It does not make decisions.

package/package.json

@@ -1,17 +1,48 @@
 {
   "name": "@etiquekit/etq",
-  "version": "0.0.1",
-  "description": "Reserved: Etiquette \u2014 govern agent-assisted engineering work with seats, evidence, and promotion gates. Local-first CLI. Releases begin at https://etiquekit.com",
-  "homepage": "https://etiquekit.com",
+  "version": "1.0.1",
+  "description": "Governance and evidence CLI for AI-assisted engineering seats.",
+  "private": false,
+  "type": "module",
   "bin": {
-    "etq": "bin/etq"
+    "etq": "bin/etiquette",
+    "etiquette": "bin/etiquette",
+    "etiquette-core": "bin/etiquette-core"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "git": ">=2.40.0"
   },
   "files": [
-    "bin",
-    "README.md"
+    "AGENTS.md",
+    "QuickStart.md",
+    "README.md",
+    "bin/",
+    "docs/",
+    "scripts/install.sh",
+    "scripts/uninstall.sh",
+    "templates/",
+    "!docs/work/"
   ],
-  "license": "SEE LICENSE AT https://etiquekit.com",
-  "engines": {
-    "node": ">=18"
-  }
-}
+  "scripts": {
+    "test": "bun test contracts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "cli": "bun packages/control/src/cli.ts",
+    "core:cli": "bun packages/control/src/core-cli.ts",
+    "release:scan": "sh scripts/release-scan.sh",
+    "release:pack": "sh scripts/release-pack-canary.sh",
+    "release:checksum": "sh scripts/release-checksum.sh",
+    "release:sign": "sh scripts/release-sign.sh",
+    "release:build": "sh scripts/release-build.sh",
+    "prepack": "sh scripts/release-build.sh"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.17",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "yaml": "2.8.3",
+    "zod": "4.3.6"
+  },
+  "homepage": "https://etiquekit.com"
+}

package/scripts/install.sh

@@ -0,0 +1,144 @@
+#!/bin/sh
+# Install Etiquette from a signed release tarball into a user-local prefix.
+set -eu
+
+BASE_URL=${ETIQUETTE_INSTALL_BASE_URL:-https://etiquette.example.com/releases}
+VERSION=${ETIQUETTE_INSTALL_VERSION:-latest}
+INSTALL_ROOT=${ETIQUETTE_INSTALL_ROOT:-"$HOME/.etiquette"}
+PUBLIC_KEY=${ETIQUETTE_RELEASE_PUBLIC_KEY:-}
+PUBLIC_KEY_URL=${ETIQUETTE_RELEASE_PUBLIC_KEY_URL:-}
+PUBLIC_KEY_SHA256=${ETIQUETTE_RELEASE_PUBLIC_KEY_SHA256:-}
+MODIFY_PROFILE=0
+
+usage() {
+  cat <<'USAGE'
+usage: install.sh [--version <version>] [--base-url <url>] [--install-root <path>] [--public-key <path>] [--public-key-url <url>] [--public-key-sha256 <hex>] [--modify-profile]
+
+Environment:
+  ETIQUETTE_INSTALL_BASE_URL      release base URL, default https://etiquette.example.com/releases
+  ETIQUETTE_INSTALL_VERSION       release version or latest
+  ETIQUETTE_INSTALL_ROOT          install root, default ~/.etiquette
+  ETIQUETTE_RELEASE_PUBLIC_KEY    RSA public key used to verify SHA256SUMS.sig
+  ETIQUETTE_RELEASE_PUBLIC_KEY_URL
+                                  HTTPS or file URL for the RSA public key
+  ETIQUETTE_RELEASE_PUBLIC_KEY_SHA256
+                                  expected SHA-256 hex for a downloaded public key
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --version) VERSION=${2:?missing version}; shift 2 ;;
+    --base-url) BASE_URL=${2:?missing base URL}; shift 2 ;;
+    --install-root) INSTALL_ROOT=${2:?missing install root}; shift 2 ;;
+    --public-key) PUBLIC_KEY=${2:?missing public key}; shift 2 ;;
+    --public-key-url) PUBLIC_KEY_URL=${2:?missing public key URL}; shift 2 ;;
+    --public-key-sha256) PUBLIC_KEY_SHA256=${2:?missing public key SHA-256}; shift 2 ;;
+    --modify-profile) MODIFY_PROFILE=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "install.sh: unknown argument: $1" >&2; usage >&2; exit 64 ;;
+  esac
+done
+
+need() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "install.sh: missing required command: $1" >&2
+    exit 127
+  fi
+}
+
+need curl
+need bun
+need openssl
+need shasum
+need tar
+
+TMPDIR_ROOT=${TMPDIR:-/tmp}
+TMP=$(mktemp -d "$TMPDIR_ROOT/etiquette-install.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT INT TERM
+
+if [ -n "$PUBLIC_KEY" ] && [ -n "$PUBLIC_KEY_URL" ]; then
+  echo "install.sh: use either --public-key or --public-key-url, not both" >&2
+  exit 64
+fi
+
+if [ -n "$PUBLIC_KEY" ]; then
+  if [ ! -f "$PUBLIC_KEY" ]; then
+    echo "install.sh: public key path does not exist: $PUBLIC_KEY" >&2
+    exit 1
+  fi
+elif [ -n "$PUBLIC_KEY_URL" ]; then
+  if [ -z "$PUBLIC_KEY_SHA256" ]; then
+    echo "install.sh: --public-key-url requires --public-key-sha256" >&2
+    exit 1
+  fi
+  PUBLIC_KEY="$TMP/etiquette-release.pub"
+  curl -fsSL "$PUBLIC_KEY_URL" -o "$PUBLIC_KEY"
+  ACTUAL_KEY_SHA=$(shasum -a 256 "$PUBLIC_KEY" | awk '{ print $1 }')
+  if [ "$PUBLIC_KEY_SHA256" != "$ACTUAL_KEY_SHA" ]; then
+    echo "install.sh: public key SHA-256 mismatch" >&2
+    exit 1
+  fi
+else
+  echo "install.sh: provide --public-key, or --public-key-url with --public-key-sha256" >&2
+  exit 1
+fi
+
+RELEASE_URL="${BASE_URL%/}/$VERSION"
+cd "$TMP"
+curl -fsSLO "$RELEASE_URL/SHA256SUMS"
+curl -fsSLO "$RELEASE_URL/SHA256SUMS.sig"
+TARBALL=$(awk '/etiquette-[0-9][^ ]*\.tgz$/ { print $2; exit }' SHA256SUMS)
+if [ -z "$TARBALL" ]; then
+  echo "install.sh: SHA256SUMS does not name an etiquette release tarball" >&2
+  exit 1
+fi
+curl -fsSLO "$RELEASE_URL/$TARBALL"
+
+EXPECTED=$(awk -v file="$TARBALL" '$2 == file { print $1; exit }' SHA256SUMS)
+ACTUAL=$(shasum -a 256 "$TARBALL" | awk '{ print $1 }')
+if [ "$EXPECTED" != "$ACTUAL" ]; then
+  echo "install.sh: checksum mismatch for $TARBALL" >&2
+  exit 1
+fi
+
+openssl dgst -sha256 -verify "$PUBLIC_KEY" -signature SHA256SUMS.sig SHA256SUMS >/dev/null
+
+VERSION_DIR=$(basename "$TARBALL" .tgz)
+LIB_DIR="$INSTALL_ROOT/lib/$VERSION_DIR"
+BIN_DIR="$INSTALL_ROOT/bin"
+mkdir -p "$LIB_DIR" "$BIN_DIR"
+tar -xzf "$TARBALL"
+rm -rf "$LIB_DIR"
+mkdir -p "$LIB_DIR"
+cp -R package/. "$LIB_DIR/"
+if [ -f "$LIB_DIR/package.json" ]; then
+  (
+    cd "$LIB_DIR"
+    bun install --production >/dev/null
+  )
+fi
+ln -sfn "$LIB_DIR/bin/etiquette" "$BIN_DIR/etiquette"
+ln -sfn "$LIB_DIR/bin/etiquette-core" "$BIN_DIR/etiquette-core"
+
+if [ "$MODIFY_PROFILE" -eq 1 ]; then
+  PROFILE=${SHELL##*/}
+  case "$PROFILE" in
+    zsh) PROFILE_FILE="$HOME/.zshrc" ;;
+    bash) PROFILE_FILE="$HOME/.bashrc" ;;
+    *) PROFILE_FILE="$HOME/.profile" ;;
+  esac
+  LINE="export PATH=\"$BIN_DIR:\$PATH\""
+  touch "$PROFILE_FILE"
+  if ! grep -Fqx "$LINE" "$PROFILE_FILE"; then
+    printf '\n# Etiquette CLI\n%s\n' "$LINE" >> "$PROFILE_FILE"
+  fi
+  echo "install.sh: updated $PROFILE_FILE"
+else
+  echo "install.sh: add $BIN_DIR to PATH, or rerun with --modify-profile"
+fi
+
+echo "install.sh: installed etiquette into $INSTALL_ROOT"
+echo "install.sh: docs: https://etiquette.example.com"
+echo "install.sh: run: $BIN_DIR/etiquette doctor --project <workspace>"
+echo "install.sh: agent skill integrations are explicit; no Claude/Codex/Gemini config was modified"

package/scripts/uninstall.sh

@@ -0,0 +1,58 @@
+#!/bin/sh
+# Remove a user-local Etiquette CLI install without touching project ledgers.
+set -eu
+
+INSTALL_ROOT=${ETIQUETTE_INSTALL_ROOT:-"$HOME/.etiquette"}
+DRY_RUN=0
+YES=0
+
+usage() {
+  cat <<'USAGE'
+usage: uninstall.sh [--install-root <path>] [--dry-run] [--yes]
+
+Removes user-local CLI links and installed release directories under the install
+root. It never removes project-local .etiquette state, docs/work, receipts, or
+ledgers from application repositories.
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --install-root) INSTALL_ROOT=${2:?missing install root}; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --yes) YES=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "uninstall.sh: unknown argument: $1" >&2; usage >&2; exit 64 ;;
+  esac
+done
+
+case "$INSTALL_ROOT" in
+  ""|"/"|"$HOME"|"$HOME/") echo "uninstall.sh: refusing unsafe install root: $INSTALL_ROOT" >&2; exit 64 ;;
+esac
+
+run() {
+  if [ "$DRY_RUN" -eq 1 ]; then
+    printf 'dry-run: %s\n' "$*"
+  else
+    "$@"
+  fi
+}
+
+if [ "$YES" -ne 1 ] && [ "$DRY_RUN" -ne 1 ]; then
+  echo "uninstall.sh: refusing without --yes (use --dry-run to preview)" >&2
+  exit 64
+fi
+
+run rm -f "$INSTALL_ROOT/bin/etiquette"
+run rm -f "$INSTALL_ROOT/bin/etiquette-core"
+if [ -d "$INSTALL_ROOT/lib" ]; then
+  for path in "$INSTALL_ROOT"/lib/etiquette-*; do
+    [ -e "$path" ] || continue
+    run rm -rf "$path"
+  done
+fi
+run rmdir "$INSTALL_ROOT/bin" 2>/dev/null || true
+run rmdir "$INSTALL_ROOT/lib" 2>/dev/null || true
+run rmdir "$INSTALL_ROOT" 2>/dev/null || true
+
+echo "uninstall.sh: project .etiquette and docs/work directories were not touched"