etymd 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # etymd
 
+## 0.3.1
+
+### Patch Changes
+
+- Regeneration keeps what a repo already had, and a fleet can declare a repo has no gates.
+
+  **Preservation moved into the generator.** `etymd gates` read the existing hook and kept a test
+  step it already ran; every other caller of `planWorkflow` did not — including the fleet gate-drift
+  check, which therefore compared each repo against a hook missing checks the repo really runs.
+  That reported permanent false drift, and anyone acting on it would have silently lost a check. A
+  guarantee that holds only on the path someone remembered to wire it into is not a guarantee.
+
+  **`gates: "none"` in a fleet manifest** declares that generated gates are deliberately absent — a
+  prose repo with nothing mechanically checkable, or one that gates itself by hand. Gate drift sits
+  among the wall checks, which are deliberately not ledger-quietable because a leak or a partition
+  breach has no honest resolution except a fix; that reasoning does not transfer to a settled
+  choice, and an un-silenceable finding for a decision already made is how a report teaches people
+  to stop reading it. The absence is disclosed rather than hidden, and an _undeclared_ absence still
+  reports — silence has to be earned by declaring it.
+
+  **A hand-written `.etymd/config.json` no longer crashes the generator.** Setting only
+  `gates.failOn` threw: the type declares `commands` as required, describing the shape etymd writes
+  rather than the shape a user writes.
+
+  **The publish gate points at the committed script.** `prepublishOnly` resolving a bare
+  `artifact-check` from `PATH` meant the door guarding what actually ships was silently absent for
+  every clone but one.
+
+## 0.3.0
+
+### Minor Changes
+
+- Content screening, a registration gate, and gates that can be regenerated without loss.
+
+  **`etymd screen` — a content screen with no opinions of its own.** Four scopes for the four ways
+  content leaves a repository: `--staged` (a commit), `--message` (the message, which the staged
+  scan cannot see), `--tree` (everything tracked), and `--dir` (an unpacked build artifact). The
+  last exists because the others share a blind spot — they answer "what is in the repository?",
+  while `npm` and `vsce` ignore `.gitignore`, so a local file can ship to users while every
+  git-scoped check passes forever.
+
+  It ships **no patterns and never will**: the strings worth screening for are themselves the
+  sensitive material. You supply a pattern file; without one the command is inert and says so,
+  rather than reporting clean for a check it did not run. A repository naming itself is exempt, and
+  a repo-level allow file covers lines that cannot carry an inline marker — a scanner's own source
+  necessarily contains the patterns it screens for.
+
+  **`etymd gates` generates all four doors**, including a `commit-msg` hook and a publish-time
+  screen wired to the key the project's publish route actually runs (`vsce` ignores
+  `prepublishOnly`). Generated hooks resolve the screener at run time and no-op when it is absent,
+  so the same file is safe to commit to a public repository.
+
+  **Your own checks live beside the generated ones.** Each hook calls `.githooks/<hook>.local` if it
+  exists — a file etymd never reads, writes, or regenerates. Regeneration no longer forces a choice
+  between accepting the pack and keeping your own guards, and it will not drop a test step an
+  existing hook already ran.
+
+  **Setup is one keystroke.** `gates` shows a plan with every derivation stated and asks once;
+  `customize` reaches each choice. Answers record to `.etymd/config.json`, where
+  `gates._why.<field>` can carry the reason a value is what it is — dropped automatically when the
+  value it explains changes, because a stale reason misleads exactly where it meant to inform.
+
+  **`etymd fleet add`** registers a project, prompting for what no scan can derive and refusing to
+  write an incomplete entry. Fleet manifests gain a mandatory `trust` level on non-corp entries —
+  absence is a finding, never a silent default — a manifest-level `orientation.root` replacing
+  per-entry links, and a gate-drift check that reports a repository missing a gate its siblings
+  install.
+
 ## 0.2.2
 
 ### Patch Changes
@@ -51,7 +119,7 @@
 
 ### Minor Changes
 
-- a58d3bd: Fleet mode — the truth guard across your repositories (design record `docs/design/004-fleet-truth-guard.md`; registry + fleet `--json` schemas EXPERIMENTAL through 0.2.x).
+- a58d3bd: Fleet mode — the truth guard across your repositories (design record `docs/decisions/004-fleet-truth-guard.md`; registry + fleet `--json` schemas EXPERIMENTAL through 0.2.x).
 
   - New `state-freshness` truth lens: state/decisions artifacts dated by git committer dates only (never mtime); staleness is relative, so a dormant repo's old state is current; state char budget against the ~10k session-hook truncation; marker-gated decisions format checks (`Scope:`, duplicate/out-of-order `D-NNN` ids, past `Revisit:` dates as due review debt); ADR conventions (`docs/adr/`, `docs/decisions/`, `NNNN-*.md`) recognized natively.
   - New `etymd fleet` command family. The sweep runs a read-only audit per registered repo (`--manifest` required unless the cwd holds `registry.json` — no env var, no global pointer) and renders one line per project with a delta against `last.fleet.json`; detail only for new or risk findings. `fleet check` validates the manifest pair alone (dangling mappings, duplicate names, privacy leaks, machine paths). `fleet dismiss`/`fleet accept` resolve a project's finding from any cwd.
@@ -66,7 +134,7 @@ First public release.
 
 The truth guard for agent instruction files — **keep your agent instructions true**. (Formerly
 prototyped as "clothaid", a broader workflow installer; the pivot and its state-of-the-field
-rationale are recorded in `docs/design/003-truth-guard-pivot.md`.)
+rationale are recorded in `docs/decisions/003-truth-guard-pivot.md`.)
 
 - `etymd audit` — verify every instruction claim against the actual repo, through three lenses:
   - **instruction-truth**: command claims vs `package.json` scripts, path claims vs the tree,

package/README.md

@@ -1,7 +1,13 @@
-# etymd
+# Etymd
 
-[![npm version](https://img.shields.io/npm/v/etymd.svg)](https://www.npmjs.com/package/etymd)
-[![CI](https://img.shields.io/github/actions/workflow/status/triartleet/etymd/ci.yml?branch=main&label=CI)](https://github.com/triartleet/etymd/actions/workflows/ci.yml)
+<div align="center">
+  <img src="media/etymd-logo.png" width="520" alt="Etymd — a papyrus of written instructions, each line checked against the repository it describes">
+  <p>
+    <a href="https://www.npmjs.com/package/etymd"><img src="https://img.shields.io/npm/v/etymd.svg?label=npm&color=cb3837" alt="npm version"></a>
+    <a href="https://github.com/triartleet/etymd/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/triartleet/etymd/ci.yml?branch=main&label=CI" alt="CI"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
+  </p>
+</div>
 
 **Keep your agent instructions true.**
 
@@ -9,7 +15,7 @@ You wrote rules for your AI months ago. Since then a script got renamed, a folde
 changed — and the AI still trusts every word. The file never complains when it goes stale; it just
 keeps instructing, confidently, and you live with the results.
 
-etymd reads those instruction files and checks every claim in them against your actual project.
+Etymd reads those instruction files and checks every claim in them against your actual project.
 
 One command, run in your project's folder (needs Node ≥ 18.17, nothing else): `npx etymd audit`.
 Here it is on a small demo project whose AGENTS.md still tells the AI to run `npm run start` and
@@ -53,7 +59,7 @@ _From Greek **étymon** — a word's true, original sense (→ etymology) — cl
 - **Truth is a property over time, not a point in time.** Instruction files are load-bearing now —
   coding agents (Claude Code, Codex, Cursor, Copilot, Gemini, …) read `AGENTS.md` natively, and a
   stale claim doesn't error, it silently misleads every session. Linters for these files check a
-  moment; etymd measures _drift_ against a committed _baseline_ and remembers findings in a
+  moment; Etymd measures _drift_ against a committed _baseline_ and remembers findings in a
   _ledger_, so fixed things stay fixed and a returning problem is named a _regression_ (all four
   words defined just below). It runs when you invoke it — or when a hook or CI job you wire up
   does.
@@ -64,7 +70,7 @@ _From Greek **étymon** — a word's true, original sense (→ etymology) — cl
   the checks filter aggressively — and every class of claim they skip is counted and disclosed,
   never silently dropped.
 
-## The words etymd uses
+## The words Etymd uses
 
 | The docs say          | It means                                                                                                                                                                                                             |
 | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -84,7 +90,7 @@ _From Greek **étymon** — a word's true, original sense (→ etymology) — cl
 
 - **"It missed an obvious stale command."** Without `node_modules` installed, command claims are
   skipped — and the skip is disclosed in the report. A command might resolve to an installed
-  binary, and etymd would rather say "couldn't check" than accuse an honest file. Install
+  binary, and Etymd would rather say "couldn't check" than accuse an honest file. Install
   dependencies and run again.
 - **`etymd audit` works without `etymd init`.** You only lose drift-over-time measurement — with
   no committed baseline, there is nothing to measure drift against. Everything else runs.
@@ -147,27 +153,29 @@ personal and employer repos. See [the fleet manifest](#the-fleet-manifest-experi
 
 ## Commands
 
-| Command                          | What it does                                                                                                                                                                           |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `etymd audit`                    | Verify every claim; ranked findings (risk → gap → polish) + ledger diff. `--lens`, `--truth`, `--json`, `--no-ledger`, `--fail-on <tier>`.                                             |
-| `etymd init`                     | Onboard: approve the committed baseline; scaffold a minimal AGENTS.md **only if missing**. Never overwrites.                                                                           |
-| `etymd doctor`                   | Alias for `audit --truth`.                                                                                                                                                             |
-| `etymd context`                  | The economy view: per-file always-loaded footprint + extraction candidates.                                                                                                            |
-| `etymd gates`                    | Install local git-hook gates (pre-commit / pre-push) built from your own check scripts.                                                                                                |
-| `etymd scan`                     | The deterministic reckoning behind everything. `--json`.                                                                                                                               |
-| `etymd brief`                    | A grounded briefing your in-repo agent completes to author the semantic layer.                                                                                                         |
-| `etymd approve`                  | Refresh the committed baseline non-interactively after intentional structural changes.                                                                                                 |
-| `etymd ledger`                   | The findings memory: every tracked finding with status and history.                                                                                                                    |
-| `etymd dismiss`                  | `dismiss <id> --reason <text>` — a dismissed finding never resurfaces without regressing.                                                                                              |
-| `etymd accept`                   | `accept <id>` — record a finding as accepted reality; visible in the ledger, out of the report.                                                                                        |
-| `etymd fleet`                    | Sweep every project in a fleet manifest: read-only per-repo audits + manifest/wall checks. `--manifest`, `--only`, `--profile`, `--truth`, `--persist-ledgers`, `--json`, `--fail-on`. |
-| `etymd fleet check`              | Validate the manifest pair alone (no lenses): dangling mappings, duplicate names, privacy leaks, machine paths. Non-zero exit on any finding.                                          |
-| `etymd fleet dismiss` / `accept` | `<name> <id>` — resolve a project's finding from any cwd; corp findings persist beside the manifest, never in the corp worktree.                                                       |
+| Command                          | What it does                                                                                                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `etymd audit`                    | Verify every claim; ranked findings (risk → gap → polish) + ledger diff. `--lens`, `--truth`, `--json`, `--no-ledger`, `--fail-on <tier>`.                                               |
+| `etymd init`                     | Onboard: approve the committed baseline; scaffold a minimal AGENTS.md **only if missing**. Never overwrites.                                                                             |
+| `etymd doctor`                   | Alias for `audit --truth`.                                                                                                                                                               |
+| `etymd context`                  | The economy view: per-file always-loaded footprint + extraction candidates.                                                                                                              |
+| `etymd gates`                    | Install local git-hook gates (pre-commit / commit-msg / pre-push, plus a publish screen where something ships) built from your own check scripts.                                        |
+| `etymd screen`                   | Content screen: find text that must never be published. Four scopes — `--staged`, `--message`, `--tree`, `--dir`. Bring your own patterns; etymd ships none.                             |
+| `etymd scan`                     | The deterministic reckoning behind everything. `--json`.                                                                                                                                 |
+| `etymd brief`                    | A grounded briefing your in-repo agent completes to author the semantic layer.                                                                                                           |
+| `etymd approve`                  | Refresh the committed baseline non-interactively after intentional structural changes.                                                                                                   |
+| `etymd ledger`                   | The findings memory: every tracked finding with status and history.                                                                                                                      |
+| `etymd dismiss`                  | `dismiss <id> --reason <text>` — a dismissed finding never resurfaces without regressing.                                                                                                |
+| `etymd accept`                   | `accept <id>` — record a finding as accepted reality; visible in the ledger, out of the report.                                                                                          |
+| `etymd fleet`                    | Sweep every project in a fleet manifest: read-only per-repo audits + manifest/wall checks. `--manifest`, `--only`, `--profile`, `--truth`, `--persist-ledgers`, `--json`, `--fail-on`.   |
+| `etymd fleet check`              | Validate the manifest pair alone (no lenses): dangling mappings, duplicate names, privacy leaks, undeclared trust, machine paths. Non-zero exit on any finding.                          |
+| `etymd fleet add`                | `add <dir>` — register a project: scans it, asks for what no scan can derive, and refuses to write an entry missing a mandatory field. `--name`, `--kind`, `--profile`, `--trust`, `-y`. |
+| `etymd fleet dismiss` / `accept` | `<name> <id>` — resolve a project's finding from any cwd; corp findings persist beside the manifest, never in the corp worktree.                                                         |
 
 `--cwd <dir>` targets another directory. Read-only probing of any repo leaves **zero trace**
 (`audit --no-ledger` writes nothing).
 
-## The files etymd keeps
+## The files Etymd keeps
 
 | Path                   | Lifecycle     | Role                                             |
 | ---------------------- | ------------- | ------------------------------------------------ |
@@ -180,7 +188,7 @@ The committed files are written to be publishable: the baseline records `"."` as
 your absolute machine path. Only the gitignored cache keeps the real one.
 
 Formatter interop: if your Prettier (or similar formatter) checks JSON, add `.etymd` to
-`.prettierignore` — etymd writes its own JSON style, and a format gate fighting the ledger is
+`.prettierignore` — Etymd writes its own JSON style, and a format gate fighting the ledger is
 noise (this repo does exactly that).
 
 ### `.etymd/config.json` (optional)
@@ -191,7 +199,7 @@ Every key is optional; omit the file entirely and the defaults below apply.
 {
   "instructions": {
     // Audit these too — files detection would not find on its own.
-    "include": ["design/**/*.md"],
+    "include": ["docs/handbook/**/*.md"],
     // Leave these out. The classic case: a fork that inherits upstream's skills
     // and will never fix them, but must keep its OWN instruction layer honest.
     "exclude": [".claude/skills/**"],
@@ -200,13 +208,27 @@ Every key is optional; omit the file entirely and the defaults below apply.
     "perFileWords": 4000, // extraction candidate above this
     "totalWords": 8000, // always-loaded footprint budget
   },
+  "gates": {
+    // What `etymd gates` generates. Written for you on first run from what the scan
+    // finds — edit it here rather than editing the generated hook, so the next run
+    // agrees with you instead of arguing.
+    "commands": ["typecheck", "lint"], // pre-push steps, in order
+    "failOn": "risk", // audit tier that fails the push: risk | gap | polish
+    "publishGate": true, // screen the published artifact
+    "allowWriting": [], // commands allowed into a gate despite writing
+    // Why a value here is what it is. Each key mirrors the field it explains, so the
+    // note says what it refers to instead of sitting near it and hoping. Etymd keeps
+    // these, and DROPS one whose field it changes — a reason attached to a value it no
+    // longer explains is worse than no reason at all.
+    "_why": { "failOn": "no build and no tests here; only docs drift can fire" },
+  },
 }
 ```
 
 Globs are repo-relative: `*` within a path segment, `**` across segments, `?` one character. A
 pattern with no wildcard is a **path prefix**, so `.claude/skills` covers everything beneath it.
 
-Narrowing an audit can hide findings, so etymd never lets it happen quietly. Honesty is
+Narrowing an audit can hide findings, so Etymd never lets it happen quietly. Honesty is
 structural: **every excluded file is counted and named in the lens disclosures**, and a config
 that fails to parse is reported as a disclosure rather than silently falling back to defaults.
 
@@ -227,13 +249,71 @@ The ledger and baseline are not CI by-products — they are **committed, reviewa
 updated locally and read in CI. A dismissal (with its reason), an accepted finding, a baseline
 refresh after an intentional restructure: each lands in `.etymd/` and shows up in the pull
 request diff like any other change. Keep `.etymd` out of your formatter's reach (see
-[the files etymd keeps](#the-files-etymd-keeps)).
+[the files Etymd keeps](#the-files-etymd-keeps)).
 
 A check that runs only in CI is itself a finding: the failure surfaces after the agent finished.
 `etymd gates` installs the local pre-commit / pre-push mirror built from your own check scripts,
 and the `gate-integrity` lens flags whatever still runs in CI alone.
 
-Modeled on this repo's own workflow (etymd guards its own instructions with etymd — its CI runs
+### Your own checks, beside the generated ones
+
+Generated hooks are overwritten on every `etymd gates` run, so nothing hand-written belongs in
+them. Each one calls a companion instead — `.githooks/pre-commit.local`, `commit-msg.local`,
+`pre-push.local` — that etymd **never reads, writes, or regenerates**. Make it executable and it
+runs; a non-zero exit stops the commit or push exactly as the generated checks do.
+
+> **Commit the companion, and check your `.gitignore` first.** A `*.local` rule — common for env
+> files, and shipped by some framework templates — silently swallows these too. The guard then
+> works on the machine that wrote it and is absent for everyone who clones, which looks identical
+> to having no guard at all. Add `!.githooks/*.local` if that rule exists.
+
+```sh
+cat > .githooks/pre-commit.local <<'EOF'
+#!/usr/bin/env sh
+# Whatever this project needs — etymd will not touch this file.
+./scripts/check-changelog.sh || exit 1
+EOF
+chmod +x .githooks/pre-commit.local
+```
+
+Two files, two owners. The generated half stays byte-identical to what the pack produces, which
+is what lets drift detection say something precise: a difference there means the _managed_ part
+was edited or went stale, never that you added a check of your own. Delete the companion and its
+checks stop running — that is what deleting a file means, and etymd does not police a file it
+does not own.
+
+### The content screen (`etymd screen`)
+
+A separate question from "are the instructions true?": **does this repo carry text that must
+never be published?** Absolute home paths, an employer's name, an internal hostname, an account
+identifier — permanent the moment they are committed, because publishing exposes all history,
+not the current tree.
+
+Etymd ships the mechanism and **no patterns, ever**. The strings worth screening for are
+themselves the sensitive material, so a built-in list would be useless to everyone else and a
+leak for whoever wrote it. You supply a pattern file (one regex or literal per line, `#` for
+comments) at `~/.config/etymd/screen-patterns` or via `--patterns`. Without one the command is
+inert and says so — it never reports "clean" for a check it did not run.
+
+`etymd gates` wires it into four doors, because a leak walks through whichever is unguarded:
+
+| door             | scope               | what only it can catch                                        |
+| ---------------- | ------------------- | ------------------------------------------------------------- |
+| `pre-commit`     | staged file bytes   | the ordinary case, at the cheapest moment to fix              |
+| `commit-msg`     | the message itself  | the staged scan reads file bytes and never sees the message   |
+| `pre-push`       | every tracked file  | anything committed with `--no-verify`, or merged in from else |
+| `prepublishOnly` | the packed artifact | **a gitignored file that still ships** — see below            |
+
+That last door exists because the first three share a blind spot: they all answer "what is in
+the repository?". `npm` and `vsce` do not honour `.gitignore`, so a local cache file can be
+packaged into a published release while every git-scoped check passes forever.
+
+Every generated hook resolves the screener at run time and **no-ops when it is absent**, so the
+same hook file is safe to commit to a public repo: it carries no patterns and imposes no policy
+on anyone who clones it. A deliberate exception is marked inline with `allow-published-string`,
+visible in the diff rather than hidden in an allowlist.
+
+Modeled on this repo's own workflow (Etymd guards its own instructions with Etymd — its CI runs
 the same gate against its own freshly built CLI):
 
 ```yaml
@@ -254,8 +334,8 @@ steps:
 agent-context file: claims about your fleet (what exists, where, under which **profile** — the
 side of the wall an entry belongs to, `personal` or `corp`; the **wall** is the placement
 boundary between personal and employer content that the sweep polices). It rots like any
-AGENTS.md does, and `etymd fleet` keeps it true. Design record:
-[`docs/design/004-fleet-truth-guard.md`](docs/design/004-fleet-truth-guard.md). Both the
+AGENTS.md does, and `etymd fleet` keeps it true. Decision record:
+[`docs/decisions/004-fleet-truth-guard.md`](docs/decisions/004-fleet-truth-guard.md). Both the
 registry schema and the fleet `--json` schema are **experimental through 0.2.x**.
 
 Two files beside each other — the split is the privacy model:
@@ -266,13 +346,21 @@ Two files beside each other — the split is the privacy model:
 {
   "registryVersion": 1,
   "root": "~/projects", // ~ expands on the consumer side — never a machine home
+  "orientation": { "root": "north" }, // optional: the entry every other entry is guided by
   "projects": [
-    { "name": "web-app", "kind": "repo", "profile": "personal", "path": "web-app" },
+    {
+      "name": "web-app",
+      "kind": "repo",
+      "profile": "personal",
+      "path": "web-app",
+      "trust": "private",
+    },
     {
       "name": "notes",
       "kind": "docs",
       "profile": "personal",
       "path": "notes",
+      "trust": "private", // mandatory on every non-corp entry — see below
       "staleAfterDays": 45, // per-entry freshness window
       "contract": { "state": "STATUS.md" }, // native conventions register, never migrate
     },
@@ -302,6 +390,26 @@ Two files beside each other — the split is the privacy model:
 }
 ```
 
+Two fields the scan can never derive, so the manifest must declare them:
+
+- **`trust` — mandatory on every non-corp entry** (`public-repo` | `public-bound` | `private`).
+  It is a _safety predicate_, not a label: it decides whether content screening applies, so an
+  absent value is reported (`fleet check` flags it), never read as a silent `private`.
+  `public-bound` means private today, plausibly public later — screened exactly as hard as
+  public, because publishing exposes _all_ history: the scrub has to precede the first commit,
+  not the visibility flip. A value outside the vocabulary is flagged rather than coerced, so a
+  typo can never quietly disable screening. Corp entries omit it — `profile: "corp"` already
+  implies the answer.
+- **`orientation.root` — optional, declared once.** Names the one entry every other entry is
+  guided by. Declared at the manifest level rather than repeated per entry, because a per-entry
+  link carries no information and can be forgotten: hoisting it makes an unoriented project
+  unrepresentable instead of merely detectable. Fleets without an orientation root omit the
+  block — etymd never assumes one.
+
+`etymd fleet add <dir>` is the gate that keeps both true: it scans the project, prompts for what
+no scan can derive, and **refuses to write an incomplete entry**. Non-interactive runs (`--yes`,
+CI) must pass every mandatory value as a flag — there is deliberately no default.
+
 How the sweep behaves:
 
 - **Read-only by default, everywhere.** The sweep never creates `.etymd` anywhere.
@@ -329,7 +437,7 @@ How the sweep behaves:
   is deliberately no env var and no home-directory pointer.
 
 Formatter interop for the `.etymd` state the sweep resolves: same rule as everywhere — see
-[the files etymd keeps](#the-files-etymd-keeps).
+[the files Etymd keeps](#the-files-etymd-keeps).
 
 ## Programmatic use
 
@@ -342,7 +450,7 @@ console.log(audit.findings) // one schema: claim · evidence · why · action ·
 
 ## The corpus (how this is validated)
 
-etymd is developed against a corpus of real sibling repos rather than fixtures alone —
+Etymd is developed against a corpus of real sibling repos rather than fixtures alone —
 [`sources.json`](sources.json) lists them by shape. Every heuristic here exists because a real
 repo proved the previous one wrong, and each skip class in the truth lens is a false positive that
 a corpus run caught.
@@ -355,13 +463,13 @@ mapping each name to its sibling directory:
 { "dirs": { "nx-monorepo": "my-monorepo-checkout" } }
 ```
 
-Each value is resolved as a sibling of the etymd checkout.
+Each value is resolved as a sibling of the Etymd checkout.
 
 Without it — on a fresh clone or in CI — those suites skip cleanly and the rest still run.
 
-## Design record & roadmap
+## Decision record & roadmap
 
-[`docs/design/`](docs/design/) — 001 founding · 002 foundation re-lock · **003 the truth-guard
+[`docs/decisions/`](docs/decisions/) — 001 founding · 002 foundation re-lock · **003 the truth-guard
 pivot** (the current identity; includes the state-of-the-field investigation it rests on) ·
 **004 fleet mode** (the truth guard across your repositories).
 [`ROADMAP.md`](ROADMAP.md) — what's now / next / later, the pre-publish checklist, and the

package/dist/{approve-VC4V3OPW.js → approve-3B2UL7LG.js}

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { scanProject, PACK_VERSION } from './chunk-BH37LELV.js';
-import { VERSION } from './chunk-LVLZLCND.js';
-import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-FZSIOCOZ.js';
-import { section, theme, print, renderBaselineDrift, glyph } from './chunk-LBRNZZZF.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-TADKOW6P.js';
+import { scanProject } from './chunk-HOLFW5QY.js';
+import { VERSION } from './chunk-DKC7MLWG.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-R74SJ7HS.js';
+import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import './chunk-YLNQQZ5F.js';
 
 // src/commands/approve.ts
 async function run(opts) {

package/dist/audit-4YB3K62W.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export { run } from './chunk-MEJ4MBVL.js';
+import './chunk-V6NZEIHF.js';
+import './chunk-LT67FU2Y.js';
+import './chunk-WWBF4Y7K.js';
+import './chunk-NMZ3RHWW.js';
+import './chunk-TADKOW6P.js';
+import './chunk-HOLFW5QY.js';
+import './chunk-DKC7MLWG.js';
+import './chunk-R74SJ7HS.js';
+import './chunk-CRJHIXJH.js';
+import './chunk-YLNQQZ5F.js';

package/dist/{brief-TZ45MNHD.js → brief-6EEXGQUW.js}

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { scanProject } from './chunk-BH37LELV.js';
-import './chunk-LVLZLCND.js';
-import { ETYMD_DIR } from './chunk-FZSIOCOZ.js';
-import { print, theme } from './chunk-LBRNZZZF.js';
+import { print, theme } from './chunk-TADKOW6P.js';
+import { scanProject } from './chunk-HOLFW5QY.js';
+import './chunk-DKC7MLWG.js';
+import { ETYMD_DIR } from './chunk-R74SJ7HS.js';
+import './chunk-CRJHIXJH.js';
+import './chunk-YLNQQZ5F.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 

package/dist/chunk-CRJHIXJH.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// src/pack/version.ts
+var PACK_VERSION = "3";
+
+export { PACK_VERSION };

package/dist/{chunk-LVLZLCND.js → chunk-DKC7MLWG.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // package.json
 var package_default = {
-  version: "0.2.2"};
+  version: "0.3.1"};
 
 // src/version.ts
 var VERSION = package_default.version;

package/dist/chunk-EF6BPBG6.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+async function applyFiles(root, files, overwrite = /* @__PURE__ */ new Set()) {
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    if (file.exists && !overwrite.has(file.path)) {
+      skipped.push(file.path);
+      continue;
+    }
+    const abs = path.join(root, file.path);
+    await promises.mkdir(path.dirname(abs), { recursive: true });
+    await promises.writeFile(abs, file.contents, "utf8");
+    if (file.executable) await promises.chmod(abs, 493);
+    written.push(file.path);
+  }
+  return { written, skipped };
+}
+
+export { applyFiles };

package/dist/{chunk-BH37LELV.js → chunk-HOLFW5QY.js}

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-LVLZLCND.js';
-import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-LBRNZZZF.js';
+import { VERSION } from './chunk-DKC7MLWG.js';
+import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-YLNQQZ5F.js';
 import path from 'node:path';
 import { promises } from 'node:fs';
 
-// src/pack/version.ts
-var PACK_VERSION = "2";
 var IGNORED_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -564,10 +563,14 @@ async function scanProject(root, opts = {}) {
     commands: classifyCommands(rootPkg?.scripts),
     ci,
     hooks,
+    publishable: Boolean(rootPkg) && rootPkg?.private !== true,
+    // `engines.vscode` is what makes a package an extension, and extensions publish through
+    // vsce — which never runs prepublishOnly.
+    publishRoute: !rootPkg ? "none" : rootPkg.engines?.vscode ? "vscode" : "npm",
     artifacts,
     freshness,
     tree
   };
 }
 
-export { PACK_VERSION, expandFileGlobs, scanProject };
+export { expandFileGlobs, scanProject };

package/dist/chunk-LT67FU2Y.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { DEFAULT_CONFIG } from './chunk-NMZ3RHWW.js';
+import { readText, wordCount, approxTokens, pathExists } from './chunk-YLNQQZ5F.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+var ALWAYS_LOADED = [
+  { path: "AGENTS.md", role: "operating contract" },
+  { path: "PROJECT_CONTEXT.md", role: "ground-truth state" },
+  { path: "CLAUDE.md", role: "Claude Code pointer" },
+  { path: "GEMINI.md", role: "Gemini pointer" },
+  { path: ".github/copilot-instructions.md", role: "Copilot instructions" },
+  { path: ".cursorrules", role: "Cursor rules (legacy)" }
+];
+var EXTRACTION_THRESHOLD = DEFAULT_CONFIG.context.perFileWords;
+function isAlwaysAppliedCursorRule(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return true;
+  const frontmatter = fm[1] ?? "";
+  return /^\s*alwaysApply\s*:\s*true\s*$/m.test(frontmatter);
+}
+async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
+  const files = [];
+  for (const spec of ALWAYS_LOADED) {
+    const abs = path.join(root, spec.path);
+    const text = await readText(abs);
+    if (text === null) continue;
+    const words = wordCount(text);
+    files.push({ path: spec.path, role: spec.role, words, approxTokens: approxTokens(words) });
+  }
+  const rulesDir = path.join(root, ".cursor", "rules");
+  if (await pathExists(rulesDir)) {
+    try {
+      for (const entry of await promises.readdir(rulesDir)) {
+        if (!entry.endsWith(".mdc") && !entry.endsWith(".md")) continue;
+        const text = await readText(path.join(rulesDir, entry));
+        if (text === null || !isAlwaysAppliedCursorRule(text)) continue;
+        const words = wordCount(text);
+        files.push({
+          path: `.cursor/rules/${entry}`,
+          role: "Cursor rule (always applied)",
+          words,
+          approxTokens: approxTokens(words)
+        });
+      }
+    } catch {
+    }
+  }
+  const totalWords = files.reduce((s, f) => s + f.words, 0);
+  return {
+    files: files.sort((a, b) => b.words - a.words),
+    totalWords,
+    totalApproxTokens: approxTokens(totalWords),
+    perFileWords,
+    extractionCandidates: files.filter((f) => f.words >= perFileWords)
+  };
+}
+
+export { measureContext };

package/dist/{chunk-IW6K5HLV.js → chunk-MEJ4MBVL.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-KMAJIQHC.js';
-import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-LBRNZZZF.js';
+import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-V6NZEIHF.js';
+import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-TADKOW6P.js';
 
 // src/commands/audit.ts
 async function run(opts) {

package/dist/{chunk-EUIHYD6F.js → chunk-MMPV67FW.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readLedger, resolveEntry, writeLedger } from './chunk-KBF3SW3N.js';
-import { print, renderLedger, glyph, theme } from './chunk-LBRNZZZF.js';
+import { readLedger, resolveEntry, writeLedger } from './chunk-WWBF4Y7K.js';
+import { print, renderLedger, glyph, theme } from './chunk-TADKOW6P.js';
 
 // src/commands/ledger.ts
 async function list(opts) {