etymd 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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
@@ -51,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.
@@ -66,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,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-JEOEC2MV.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 { 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-TZ45MNHD.js → brief-ZK7TXAC4.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 { 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';
 

package/dist/{chunk-MWIK6ML3.js → chunk-3NYDVB4Z.js}

@@ -1,26 +1,8 @@
 #!/usr/bin/env node
-import { PACK_VERSION } from './chunk-BH37LELV.js';
-import { pathExists, readText } from './chunk-LBRNZZZF.js';
-import { promises } from 'node:fs';
+import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { pathExists, readText } from './chunk-YLNQQZ5F.js';
 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 };
-}
-
 // src/pack/templates.ts
 function runPrefix(pm) {
   switch (pm) {
@@ -128,22 +110,119 @@ ${[
 <!-- etymd pack v${PACK_VERSION} -->
 `;
 }
+var CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(command -v etymd || true)}"`;
+function localHookCall(hook) {
+  return `# Repo-owned checks. This file is generated and will be overwritten; \`.githooks/${hook}.local\`
+# is yours \u2014 etymd never reads, writes, or regenerates it. Put project-specific guards there.
+LOCAL="$(dirname "$0")/${hook}.local"
+if [ -x "$LOCAL" ]; then
+  "$LOCAL" "$@" || exit 1
+fi`;
+}
 function generatePreCommitHook() {
   return `#!/usr/bin/env sh
 # etymd: process gate. Cheap, locally-knowable checks belong here (fast, blocks the commit).
+
+${localHookCall("pre-commit")}
+
+# Content screen \u2014 staged file bytes. Refuses to commit environment, employer or identity
+# detail into a repo whose history is (or could become) public. The checker and its patterns
+# are machine-local by design, so this is a NO-OP wherever no checker is installed: safe to
+# commit anywhere, active only where you opted in.
+#
+# Bypass, with a reason: git commit --no-verify
+${CONTENT_GATE_RESOLUTION}
+if [ -x "$GATE" ]; then
+  "$GATE" screen --staged || exit 1
+fi
+
+exit 0
+`;
+}
+function generateCommitMsgHook() {
+  return `#!/usr/bin/env sh
+# etymd: content screen \u2014 the commit message itself.
+#
+# The staged-content gate reads file bytes and never sees the message, yet a message is as
+# permanently published as any file. No-op where no checker is installed.
+#
+# Bypass, with a reason: git commit --no-verify
+GATE="\${COMMIT_MSG_GATE:-$(command -v etymd || true)}"
+if [ -x "$GATE" ]; then
+  "$GATE" screen --message "$1" || exit 1
+fi
+
+${localHookCall("commit-msg")}
+
 exit 0
 `;
 }
-function generatePrePushHook(facts) {
+function generatePrePushHook(facts, gates) {
   const run = runPrefix(facts.packageManager);
   const c = facts.commands;
-  const candidates = [c.formatCheck, c.typecheck, c.lint];
-  const steps = candidates.filter((key) => Boolean(key) && isSafeGateCommand(c.raw[key])).map((key) => `${run} ${key}`);
+  const candidates = gates?.commands.length ? gates.commands : [c.formatCheck, c.typecheck, c.lint];
+  const allowed = new Set(gates?.allowWriting ?? []);
+  const steps = candidates.filter(
+    (key) => Boolean(key) && (allowed.has(key) || isSafeGateCommand(c.raw[key]))
+  ).map((key) => `${run} ${key}`);
   const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
 ${s} || exit 1`).join("\n") : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
+  const failOn = gates?.failOn ?? "risk";
+  const auditStep = `
+if command -v etymd >/dev/null 2>&1; then
+  echo "\u203A etymd audit --fail-on ${failOn}"
+  etymd audit --no-ledger --fail-on ${failOn} || exit 1
+else
+  echo "\u203A etymd audit skipped (not on PATH)"
+fi`;
   return `#!/usr/bin/env sh
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
+
+${localHookCall("pre-push")}
 ${body}
+${auditStep}
+
+# Content screen, second pass \u2014 the WHOLE TREE rather than one diff. Catches anything committed
+# with --no-verify and anything a rebase or merge brought in from elsewhere. Advisory here (it
+# never blocks the push): the blocking decision belongs at commit time, where the fix is cheap.
+${CONTENT_GATE_RESOLUTION}
+if [ -x "$GATE" ] && [ "\${CONTENT_GATE_PREPUSH:-1}" = "1" ]; then
+  "$GATE" screen --tree --advisory || true
+fi
+
+exit 0
+`;
+}
+function generateArtifactCheckScript() {
+  return `#!/usr/bin/env sh
+# etymd: content screen \u2014 the published ARTIFACT, not the repository.
+#
+# Wire it into the irreversible moment:
+#   package.json \u2192 "prepublishOnly": "./scripts/artifact-check.sh"
+#
+# No-op where no checker is installed. Bypass is deliberate and loud: ARTIFACT_CHECK_SKIP=1.
+set -eu
+
+if [ "\${ARTIFACT_CHECK_SKIP:-0}" = "1" ]; then
+  echo "\u203A artifact-check: SKIPPED by ARTIFACT_CHECK_SKIP=1"
+  exit 0
+fi
+
+${CONTENT_GATE_RESOLUTION}
+[ -x "$GATE" ] || { echo "\u203A artifact-check: no checker installed \u2014 skipping."; exit 0; }
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT INT TERM
+
+# Pack exactly what would ship, then screen the unpacked bytes.
+if [ -f package.json ]; then
+  npm pack --pack-destination "$WORK" >/dev/null 2>&1 || {
+    echo "\u203A artifact-check: npm pack failed \u2014 cannot verify what would ship" >&2; exit 1; }
+  tar -xzf "$WORK"/*.tgz -C "$WORK" 2>/dev/null || true
+fi
+
+"$GATE" screen --dir "$WORK" || exit 1
+exit 0
 `;
 }
 
@@ -168,9 +247,28 @@ async function planWorkflow(root, facts, opts) {
   }
   if (opts.gates) {
     await add(".githooks/pre-commit", generatePreCommitHook(), "Process gate (pre-commit)", true);
-    await add(".githooks/pre-push", generatePrePushHook(facts), "Correctness gate (pre-push)", true);
+    await add(
+      ".githooks/commit-msg",
+      generateCommitMsgHook(),
+      "Content screen (commit message)",
+      true
+    );
+    await add(
+      ".githooks/pre-push",
+      generatePrePushHook(facts, opts.gateConfig),
+      "Correctness gate (pre-push)",
+      true
+    );
+    if (opts.gateConfig?.publishGate ?? opts.publishGate ?? facts.publishable) {
+      await add(
+        "scripts/artifact-check.sh",
+        generateArtifactCheckScript(),
+        "Content screen (published artifact)",
+        true
+      );
+    }
   }
   return out;
 }
 
-export { applyFiles, planWorkflow };
+export { isSafeGateCommand, planWorkflow, runPrefix };

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-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 };