etymd 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # etymd
 
+## 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
+
+- 80db483: Gate integrity: detect scripts regardless of how the package manager is invoked.
+
+  Script expansion guessed the script name positionally — the token straight after the
+  manager. That only holds for `npm run x`, `yarn x` and `pnpm x`. Every other live shape
+  expanded to nothing, so the tool was never detected and the gate read as absent:
+
+  | invocation                           | captured as the script name |
+  | ------------------------------------ | --------------------------- |
+  | `pnpm run typecheck`                 | `run`                       |
+  | `pnpm -s typecheck`                  | `-s`                        |
+  | `pnpm -r --if-present run typecheck` | `-r`                        |
+  | `pnpm --filter @scope/pkg test`      | `--filter`                  |
+
+  A pre-push hook running `pnpm run typecheck` therefore reported as having no typecheck at
+  all, and `audit` said "type checking is enforced only in CI — no local hook runs it" while
+  the hook ran it on every push.
+
+  Expansion no longer guesses position — it cannot, since the position depends on each
+  manager's own flag grammar. It scans the invocation's tokens for a name that is a known
+  script, which needs no grammar at all. Package-manager built-ins are excluded so `npm ci`
+  is never read as "runs the `ci` script"; that direction matters, because expanding it would
+  claim a gate is covered by a line that only installs dependencies. `test` and `start` stay
+  recognised — those genuinely are script shortcuts. `exec`/`dlx` end the scan, since what
+  follows is a binary, and `npx` is only scanned for `run-s`/`run-p`/`npm-run-all`.
+
 ## 0.2.1
 
 ### Patch Changes
@@ -22,7 +91,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.
@@ -37,7 +106,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,54 +1,117 @@
-# 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.**
 
-Your `AGENTS.md` is the interface between your team and every coding agent — and it rots silently.
-Scripts get renamed, directories move, rules go stale, and the file keeps instructing agents with
-confidence. etymd continuously **verifies the agent context layer against the actual repo**:
+You wrote rules for your AI months ago. Since then a script got renamed, a folder moved, a habit
+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.
+
+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
+`npm run lint` and points at a `src/legacy/` folder — none of which exist any more:
 
 ```
-$ etymd audit
+$ npx etymd audit
+
+  RISK   AGENTS.md tells agents to run `start` — no such script exists
+         evidence  AGENTS.md: `npm run start` · package.json scripts (root + workspaces)
+         why       An agent following this instruction runs a command that fails — or silently skips the check it was meant to run.
+         action    Update the instruction to the current script name (or restore the script).
+         effort S · confidence high · instruction-truth · instruction-truth/stale-command:AGENTS.md:start
 
-  RISK   AGENTS.md tells agents to run `pnpm dev` — no such script exists
-         evidence  AGENTS.md: `pnpm dev` · package.json scripts
-         action    Update the instruction to the current script name.
+  ...
 
-  GAP    AGENTS.md references `src/legacy/` — it does not exist in the repo
-  GAP    Type checking is enforced only in CI — no local hook runs it
-  GAP    AGENTS.md loads 13,809 words (~18k tokens) into every session
+  GAP    AGENTS.md references `src/legacy` — it does not exist in the repo
+         evidence  AGENTS.md · missing: src/legacy
+         why       Agents navigate by these references; a dead path wastes a lookup and erodes trust in the rest of the file.
+         action    Fix or remove the reference.
+         effort S · confidence medium · instruction-truth · instruction-truth/stale-path:AGENTS.md:src/legacy
 
-  since last audit: 1 new · 3 still open · 1 resolved · 1 REGRESSED
+  since last audit: 3 still open
 ```
 
+Each entry names something that is no longer true, shows the evidence it found, and suggests the
+smallest fix. And it remembers between runs: a problem you fixed — or looked at and deliberately
+waved off — never nags you twice.
+
+That's the whole deal. It works with zero configuration and never rewrites your files — the
+memory it keeps between runs lives in one small folder of its own (`.etymd/`). Everything below
+the line is reference — read it when you need it.
+
 _From Greek **étymon** — a word's true, original sense (→ etymology) — clipped to **etym.** + the
 **.md** family it guards._
 
+---
+
 ## Why this exists
 
-- Instruction files are now load-bearing: 20+ agents (Claude Code, Codex, Cursor, Copilot,
-  Gemini, …) read `AGENTS.md` natively. A stale claim doesn't error — it silently misleads every
-  session.
-- Linters exist for these files, but they check **a point in time**. Truth is a property **over
-  time**: etymd measures drift against a **committed baseline**, remembers findings in a
-  **ledger** (fixed things stay fixed; a returning problem is named a _regression_, and a finding
-  you dismissed with a reason never resurfaces), and gates CI on it.
+- **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
+  _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.
 - **Honesty is structural.** Every report declares what it could NOT see — CI jobs inherited from
-  unreadable org templates, server-side quality-gate thresholds, skipped heuristics. No guess is
-  ever dressed as a fact.
+  unreadable org templates, server-side quality-gate thresholds, heuristics it skipped. No guess
+  is ever dressed as a fact.
+- **Precision over recall.** A false "your file is lying" costs more trust than a missed lie, so
+  the checks filter aggressively — and every class of claim they skip is counted and disclosed,
+  never silently dropped.
+
+## The words Etymd uses
+
+| The docs say          | It means                                                                                                                                                                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **finding**           | One verified problem, ranked **RISK** (an agent acting on this does the wrong thing) → **GAP** (a dead reference or missing safeguard) → **POLISH** (worth tidying). Within a tier, cheapest fix first.              |
+| **claim**             | Anything an instruction file asserts about the project that can be checked: a command it tells agents to run, a path it points at, a rule about tooling.                                                             |
+| **lens**              | One self-contained checker for one kind of truth (are the commands real? is the state doc current?). An audit is all lenses run together.                                                                            |
+| **baseline**          | A snapshot of the repo's checkable facts that you approved and committed. Drift is measured against this — not against whatever yesterday's cache happened to hold.                                                  |
+| **drift**             | The distance between the baseline and the repo today: what existed at approval and is now gone, renamed, or moved.                                                                                                   |
+| **ledger**            | The committed memory of findings — each one's status and history. A finding that was fixed and comes back is a **regression**, and the report names it as one rather than re-introducing it as new.                  |
+| **dismiss vs accept** | Two deliberate ways to close a finding. _Dismiss_ = "not a real problem, here's why" — it never resurfaces unless it regresses. _Accept_ = "true, and we're living with it" — kept in the ledger, out of the report. |
+| **gate**              | A check that can actually fail a change: a git hook, a CI job. A job marked `allow_failure` is advisory, not a gate — a check that cannot fail anything is an opinion.                                               |
+| **disclosure**        | The report's account of what it could not see or refused to guess about. Every report carries one; a clean result with no disclosures would be the exact dishonesty this tool exists to catch.                       |
+| **fleet**             | Your fleet of **repositories** — every repo you registered in one manifest, swept by one command. Not a fleet of AI agents.                                                                                          |
+| **context economy**   | The words your instruction files load into every single session, measured against a budget. Context is a cost you pay per conversation; leaner files are cheaper and better obeyed.                                  |
+
+### Things that surprise first-run users
+
+- **"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
+  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.
+- **`etymd init` never overwrites an existing `AGENTS.md`.** It scaffolds a minimal one only if
+  you have none. The feared overwrite path simply does not exist.
+
+---
 
 ## Quick start
 
 ```bash
 cd your-project
-npx etymd init          # approve the baseline (+ scaffold AGENTS.md only if you have none)
 npx etymd audit         # verify every instruction claim against the repo
+npx etymd init          # opt in to drift: approve the baseline (+ scaffold AGENTS.md only if you have none)
 npx etymd audit --fail-on risk   # the CI gate
 ```
 
-Requires Node ≥ 18.17. On npm since v0.1.0 — `npx etymd` just works.
+`audit` needs no setup — without `init` you get the full findings report and lose only drift
+measured against a committed baseline. `init` is that opt-in, not a prerequisite, and it never
+overwrites an existing `AGENTS.md`. On npm since v0.1.0 — `npx etymd` just works. To wire the
+gate into a pipeline, see [In CI](#in-ci).
 
 ## What it checks
 
@@ -90,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                                             |
 | ---------------------- | ------------- | ------------------------------------------------ |
@@ -122,6 +187,10 @@ personal and employer repos. See [the fleet manifest](#the-fleet-manifest-experi
 The committed files are written to be publishable: the baseline records `"."` as its scan root, never
 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
+noise (this repo does exactly that).
+
 ### `.etymd/config.json` (optional)
 
 Every key is optional; omit the file entirely and the defaults below apply.
@@ -130,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/**"],
@@ -139,23 +208,134 @@ 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: **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.
+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.
+
+## In CI
+
+The gate is one command:
+
+```bash
+npx etymd audit --no-ledger --fail-on risk
+```
+
+Exit-code contract: without `--fail-on`, `audit` reports and exits 0 no matter what it found.
+With `--fail-on <tier>` (`risk` | `gap` | `polish`) it exits non-zero when any finding at or
+above that tier exists — so `--fail-on risk` blocks on risks only, `--fail-on polish` blocks on
+everything. `--no-ledger` keeps the CI run read-only: the throwaway checkout is never written.
+
+The ledger and baseline are not CI by-products — they are **committed, reviewable state**,
+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)).
+
+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.
+
+### 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
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 20
+      cache: npm
+  - run: npm ci
+  - run: npx etymd audit --no-ledger --fail-on risk
+```
 
 ## The fleet manifest (EXPERIMENTAL)
 
 `etymd fleet` extends the one objective across every repository you work in — your fleet of
 **repositories**, not a fleet of agents. The manifest, `registry.json`, is itself an
-agent-context file: claims about your fleet (what exists, where, under which profile). 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
+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. 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:
@@ -166,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
     },
@@ -194,7 +382,7 @@ Two files beside each other — the split is the privacy model:
 
 ```jsonc
 {
-  "machineProfile": "corp", // "personal" resolves corp entries disclosed-absent
+  "machineProfile": "corp", // which profile this machine resolves; "personal" resolves corp entries disclosed-absent
   "root": "~/projects", // optional per-machine root override
   "dirs": { "c-one": "~/projects/real-corp-dir" },
   "labels": { "c-one": "real-corp-dir" },
@@ -202,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.
@@ -212,17 +420,24 @@ How the sweep behaves:
 - **Deltas.** Each sweep compares against `last.fleet.json` stored beside the manifest and
   renders `Δ +new −resolved` per project. Add `*.fleet.json` to the manifest repo's
   `.gitignore` — sweep output is local-only and never tracked.
+- **Recurring classes.** A finding class open in two or more projects renders as its own section
+  of class-fix candidates (worst tier first) — the sweep asking "repo bug or fleet bug?", a
+  fleet-level lesson no per-repo audit can see. The sweep only groups; the class vocabulary is
+  minted by the engine's lenses.
+- **Declared absence is honored.** An entry whose contract declares `"placement": "none"` states
+  that instruction files are legitimately absent in that project — the sweep drops its
+  missing-contract finding instead of re-reporting a decision every run. Absence disclosed on
+  purpose is a state, not a gap.
 - **Wall checks.** Corp contract files found inside a corp worktree, unregistered checkouts
   under the fleet root whose remotes match `corpHosts`, tracked `/Users/` paths in the manifest
-  repo, private needles (labels, dir names, hosts) inside `trust: "public-repo"` entries, and
-  corp-host commit emails on personal entries — each a risk finding; each check that cannot run
-  is disclosed.
+  repo, private **needles** — the identifiers the local file holds (labels, dir names, hosts) —
+  inside `trust: "public-repo"` entries, and corp-host commit emails on personal entries — each
+  a risk finding; each check that cannot run is disclosed.
 - **No global pointer.** `--manifest` is required unless the cwd holds `registry.json` — there
   is deliberately no env var and no home-directory pointer.
 
-Interop note: if a repo's Prettier (or similar formatter) checks JSON, add `.etymd` to its
-`.prettierignore` — etymd writes its own JSON style, and a format gate fighting the ledger is
-noise (this repo does exactly that).
+Formatter interop for the `.etymd` state the sweep resolves: same rule as everywhere — see
+[the files Etymd keeps](#the-files-etymd-keeps).
 
 ## Programmatic use
 
@@ -235,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.
@@ -248,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-X3AW7KLD.js → approve-JEOEC2MV.js}

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { scanProject, PACK_VERSION } from './chunk-E2Q7WFPN.js';
-import { VERSION } from './chunk-C4Z6NXDO.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 { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-R74SJ7HS.js';
+import { scanProject } from './chunk-MKYPLNLH.js';
+import { VERSION } from './chunk-NFENQ3IK.js';
+import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import './chunk-YLNQQZ5F.js';
 
 // src/commands/approve.ts
 async function run(opts) {

package/dist/audit-GYZ5YZ7U.js

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

package/dist/{brief-RT6KE4CN.js → brief-ZK7TXAC4.js}

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