etymd 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # etymd
 
+## 0.15.0
+
+### Minor Changes
+
+- 6f40a7d: `etymd premise "<task>"` — the task you hand an agent is an instruction too. Every path, script,
+  well-known doc and decision id the task names is verified against the repo (a missing thing the
+  task is _about_ ranks as risk), and a brief hands the agent the premises only it can verify.
+  `--file <path>` (`-` reads stdin), `--json` (schema `premise/1`), `--no-brief`, `--fail-on <tier>`.
+  Zero trace in a repo that never opted in; no ledger. Prose is read with stricter rules than a code
+  span (a script needs the `run` form, a directory claim needs a first segment that exists, a host
+  name is a URL) and every class left as prose is disclosed. The command/path/doc-reference/
+  decision-reference truth checks are now one shared implementation used by `instruction-truth` and
+  `premise` alike — ids, tiers and disclosures of existing findings are unchanged.
+
+## 0.14.0
+
+Knowledge pack **v8 → v12**: every generated hook and script is regenerated by `etymd gates`.
+Versions 9, 10 and 11 were claimed by work that was reworked before release and stay retired,
+so a pack number cited in a baseline always means exactly one pack.
+
+### Minor Changes
+
+- 3056213: Three fixes to the generated gates and the onboarding flow:
+
+  - **zsh is out of the shellcheck scan.** The generated pre-push discovered shell
+    scripts by a shebang pattern that included zsh, but shellcheck cannot parse zsh — SC1071 is a
+    parser-level error no inline directive silences — so a repo whose executable surface is zsh
+    could never push. zsh shebangs are now excluded from the checked set and the hook prints the
+    exclusion (count + reason) at run time instead of going quiet about coverage.
+  - **`~/` home paths are no longer repo file references.** Prose like "global rules in
+    `~/.claude/CLAUDE.md` apply on top" made the audit demand a repo-root CLAUDE.md that was
+    never meant to exist — the sentence points at the reader's machine. Home-path mentions of
+    well-known docs are now skipped and disclosed, like absolute tokens; one ordinary mention
+    still makes the doc a live claim.
+  - **`init` no longer scaffolds AGENTS.md unasked.** `init -y` in a repo without a contract used
+    to write template prose nobody reviewed (and baseline it, making later deletion read as
+    drift). The scaffold is now opt-in via `--with-agents`; interactive runs still ask first.
+
+- aab88c5: A content gate that cannot run is now caught, and says why.
+
+  The screen doors resolve their checker at run time, from outside the repo — so whether the gate
+  will actually run is the one thing reading the hook cannot tell you. When the resolved checker
+  turns out not to be a screener, the commit door failed closed on that program's own bare error
+  and the push door, advisory by design, skipped its whole-tree pass in silence. A repo could read
+  as screened for months while nothing screened it.
+
+  Two changes, one class:
+
+  - **The hooks explain themselves.** After a failed screen — and only then, so a clean run pays
+    nothing — the hook asks the checker whether it understands `screen` at all. If it does not, it
+    prints a line naming the version floor (`screen` needs etymd 0.11+) and the override, instead of
+    leaving the checker's unexplained "unknown command" as the last word. A screener reporting a
+    real finding is left to speak for itself.
+  - **`etymd audit` and `etymd doctor` check reachability.** Gate integrity now resolves the screen
+    runner exactly as the hook would and asks it the same question, reporting a risk-tier finding
+    when a checker resolves but cannot screen. No checker installed stays the designed no-op —
+    disclosed, never a finding — and a probe that could not be carried out claims nothing.
+
+- 6536081: Generated hooks no longer guess at the content screener by path.
+
+  The emitted content-screen resolution used to include a bare `[ -x ./dist/cli.js ]` check ahead
+  of the `etymd` on PATH. That path is simply where a great many CLI projects build, so any repo
+  that builds its own binary there had the hook invoke THAT binary as the screener: it does not
+  know `screen`, so the commit door failed closed on every commit, while the push door — which
+  ignores the screen's exit status by design — skipped the whole-tree pass in silence. The trap
+  armed itself on a plain dependency install, since that runs the repo's build.
+
+  Resolution is now `CONTENT_GATE`, then whatever `etymd` is on PATH. The dev-build arm remains
+  for the repo that develops the screener itself, where gating on an unreleased build is the point,
+  but it is decided at generation time from the manifest name and emitted nowhere else.
+
+  Regenerate with `etymd gates` to pick this up; a repo needing a different runner for one
+  invocation still has `CONTENT_GATE`.
+
+- 0c0bcc6: gates: generated pre-push steps run scrubbed of git's exported GIT\_\* environment
+
+  Git exports `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE` / … to every hook it
+  runs, and a child `git` that inherits them ignores its cwd. A test suite that
+  builds fixture repositories by shelling out to `git` therefore operates on the
+  REAL repository — committing into it, moving its refs — while the same suite
+  outside a hook is harmless, which is exactly why the defect hides: nothing run
+  from CI ever reproduces it. This changes the generated pre-push (`etymd gates`):
+
+  - **Every gate step runs through a `run_gate()` helper** that strips every
+    exported `GIT_*` name before the command runs — each name found in the
+    environment, not a fixed list, because git adds variables over time. A step
+    that genuinely means the repository finds it again from its working
+    directory, which for a hook is the repo root.
+  - **The audit and shellcheck steps stay unscrubbed**, deliberately: audit
+    operates on the repo it is invoked in and never descends into fixtures, and
+    shellcheck's `git ls-files` must see the real repo.
+  - **The `.local` companion note documents the wrap**, so a hand-written guard
+    that runs tests can scrub the same way — the companion is where repo-owned
+    suites live.
+
+  Existing hooks pick this up on the next `etymd gates` run.
+
+### Patch Changes
+
+- 1cae71b: Context economy counts a file once when two instruction names are the same file.
+
+  `AGENTS.md` symlinked to `CLAUDE.md` is the ordinary way to serve harnesses that read different
+  names. Both names were measured separately, which doubled the reported always-loaded footprint —
+  enough to manufacture an over-budget finding out of nothing — and fired the heavy-file finding
+  twice for one file. Candidates resolving to the same inode (symlink or hardlink) are now counted
+  once and reported under every name they answer to, in `etymd audit` and `etymd context` alike,
+  with the merge stated in the lens disclosures.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -15,7 +15,8 @@ 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, when you ask, the task you are about to hand an agent —
+and checks every claim 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
@@ -110,6 +111,7 @@ cd your-project
 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
+npx etymd premise "fix the flaky test in src/legacy/foo.test.ts"   # is this the right task?
 ```
 
 `audit` needs no setup — without `init` you get the full findings report and lose only drift
@@ -132,6 +134,14 @@ gate into a pipeline, see [In CI](#in-ci).
 - **Drift vs baseline** — documented commands/artifacts/layout that existed at approval and are
   now gone.
 
+**`premise`** (via `etymd premise`) — the task itself is an instruction. Before an agent acts on
+it, every path, script, well-known doc and decision id the task names is checked with the same
+rules instruction files get. A path the task is _about_ and that does not exist ranks as **risk**:
+the task would solve the wrong problem precisely. What cannot be read from files — that the named
+things are the ones meant, that the mechanism the task assumes actually runs, that the state it
+assumes holds — is handed to the agent in a brief, never guessed at. Nothing is remembered between
+runs.
+
 **`gate-integrity`** — a CI config is a claim too: checks enforced only in CI (failures surface a
 slow pipeline after the agent finished — `etymd gates` generates the local mirror), checks only in
 skippable local hooks, latent gaps (coverage collected but nothing gates on it; commitlint
@@ -161,24 +171,25 @@ 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 / commit-msg / pre-push, plus a publish screen where something ships) built from your own check scripts — and from the repo's shell surface, where it has one. |
-| `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.                                                                        |
+| 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 — and from the repo's shell surface, where it has one.           |
+| `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 premise`                  | `premise "<task>"` — is this the right task? What it names, verified against the repo; a brief for what only the agent can verify. `--file` (`-` = stdin), `--json`, `--no-brief`, `--fail-on <tier>`. No ledger. |
+| `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).

package/dist/{approve-YUT43YLC.js → approve-MA4Z3TBT.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { section, theme, print, renderBaselineDrift, glyph } from './chunk-5BVKFJWM.js';
-import { scanProject } from './chunk-YXOAPMQH.js';
-import { VERSION } from './chunk-D3R74TJ2.js';
-import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-JHZ2BN4U.js';
-import { PACK_VERSION } from './chunk-LSZGCKIQ.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-HI7NWPRA.js';
+import { scanProject } from './chunk-Y6RZRED3.js';
+import { VERSION } from './chunk-DBWDMIYO.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-P6ATKV2R.js';
+import { PACK_VERSION } from './chunk-YQZDYDAK.js';
 import './chunk-4VPBP6K6.js';
 
 // src/commands/approve.ts

package/dist/audit-YSALDC2L.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export { run } from './chunk-CEO3BXQB.js';
+import './chunk-2RNQ6OLV.js';
+import './chunk-IWG77WV3.js';
+import './chunk-3E2IPCRY.js';
+import './chunk-HI7NWPRA.js';
+import './chunk-Y6RZRED3.js';
+import './chunk-DBWDMIYO.js';
+import './chunk-P6ATKV2R.js';
+import './chunk-YQZDYDAK.js';
+import './chunk-4VPBP6K6.js';

package/dist/{brief-Z5S6OY2M.js → brief-DPZYSAMC.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { print, theme } from './chunk-5BVKFJWM.js';
-import { scanProject } from './chunk-YXOAPMQH.js';
-import './chunk-D3R74TJ2.js';
-import { ETYMD_DIR } from './chunk-JHZ2BN4U.js';
-import './chunk-LSZGCKIQ.js';
+import { print, theme } from './chunk-HI7NWPRA.js';
+import { scanProject } from './chunk-Y6RZRED3.js';
+import './chunk-DBWDMIYO.js';
+import { ETYMD_DIR } from './chunk-P6ATKV2R.js';
+import './chunk-YQZDYDAK.js';
 import './chunk-4VPBP6K6.js';
 import { promises } from 'fs';
 import path from 'path';