etymd 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # etymd
 
+## 0.6.0
+
+### Minor Changes
+
+- b02943b: Local gates: the tool now reads and rewrites what it generated, instead of guessing about it.
+
+  Two defects in the local-gate machinery, both silent, both affecting every project using
+  `etymd gates`. Decision record:
+  [`docs/decisions/006-local-gate-provenance.md`](docs/decisions/006-local-gate-provenance.md).
+
+  **`gate-integrity` follows the `<hook>.local` include.** Every generated hook opens by sourcing a
+  sibling companion — the sanctioned place for project-specific guards, which etymd never reads,
+  writes or regenerates. The lens stopped at the hook file, so a check placed in the companion ran
+  on every push, blocked it, and was still reported as enforced only in CI. The only way to silence
+  that was a dismissal, which is meant for a false positive or an accepted trade-off, not for a
+  blind spot. The lens now resolves the companion for `pre-commit`, `pre-push` and `commit-msg` and
+  counts what it enforces.
+
+  Two conditions keep it honest, both mirroring what the shell actually does: the hook must
+  genuinely reference the companion, and the companion must pass the same `[ -x ]` test the hook
+  applies before running it. A present-but-not-executable companion is reported as inert — named,
+  with the `chmod +x` that would make it run — rather than credited with checks that never fire.
+  Both outcomes are disclosed in the lens report.
+
+  **A stale generated hook is no longer indistinguishable from a hand-edited one.** `etymd gates`
+  refused to overwrite any hook whose content differed from what it would generate, printing
+  `kept (hand-edited)`. That protection is right for a customised hook and wrong for a merely stale
+  one — generated by an older etymd, or before the repo's package manager or scripts changed. In
+  that case the refusal preserved a gate that had stopped matching the repo, while `etymd audit`
+  went on reporting the gaps the refused rewrite would have closed; the only escape was deleting the
+  file, which nobody would think to try.
+
+  Generated shell files now carry a stamp as their last line, whose digest covers the file minus
+  that line. A file that still hashes to its own stamp is byte-for-byte what etymd wrote and cannot
+  contain anyone's work, so it is regenerated freely; any edit breaks the match and the file is
+  kept. `[differs]` is no longer one bucket — the plan tags a stale file `[stale]` and says it is
+  regenerating, and says why it is keeping the others.
+
+  A hook generated before the stamp existed carries no stamp and cannot be proven untouched, so it
+  is kept — now with the reason and the way out stated, instead of a dead end. One regeneration
+  makes it provable from then on.
+
+  **Provenance applies to everything the pack generates, not just hooks.** The `AGENTS.md` scaffold
+  is stamped too, in an HTML comment so it stays invisible in the rendered document; its stamp
+  replaces the bare `<!-- etymd pack vN -->` line, carrying the same version plus the provenance.
+  `.etymd/config.json` is excluded — it holds the user's recorded decisions, is merged into rather
+  than generated, and JSON has nowhere to hide a stamp.
+
+  **New finding: a companion that cannot run.** `gate-integrity/companion-not-executable` reports a
+  `<hook>.local` that a hook calls, that exists, and that provably lacks the execute bit — the check
+  inside is skipped silently on every run, and git tracks exactly one permission bit, so the dead
+  gate reaches every clone. Emitted at `gap` rather than `risk`: risk is reserved for what makes an
+  agent do the wrong thing (`hooks-not-wired` earns it because every gate is dead there), and it
+  also means an upgrade cannot fail the `--fail-on risk` gate in a repo whose code did not change.
+  The action names both halves of the fix, since `chmod +x` alone does not survive a fresh clone.
+
+  The accusation is guarded: "not executable" is trusted only where the hook beside it HAS the bit,
+  which is what proves the bit means anything on that filesystem. Where it cannot be established the
+  checks are counted and the uncertainty is disclosed, so a checkout without POSIX mode bits is
+  never told its working gate is dead.
+
+  **The fleet sweep stops recommending a command that would refuse.** `fleet` reported every
+  differing gate under one finding whose action was "re-run `etymd gates`" — advice that does not
+  work for a hand-edited hook. A provably-edited gate is now disclosed as a customisation rather
+  than reported as drift; stale and unstamped gates stay in the finding, since being unable to prove
+  a file was touched is not evidence that it was.
+
+  `PACK_VERSION` moves to 6: the generated files change meaning.
+
+### Patch Changes
+
+- `yaml` moves from 2.7.0 to 2.9.0, clearing GHSA-48c2-rrv3-qjmp (stack overflow on deeply nested
+  collections) from the dependency tree of everyone who installs etymd. The lens that parses CI
+  files already wrapped every `YAML.parse` in a try/catch, so a hostile `.gitlab-ci.yml` was
+  caught and disclosed as a parse error rather than crashing anything — verified against a
+  200,000-level nested file before and after. The bump is about not shipping a known-vulnerable
+  dependency, not about a reachable exploit.
+
+## 0.5.0
+
+### Minor Changes
+
+- e199ccc: `fleet add --profile corp` now records the alias-to-directory mapping too, not just the entry.
+
+  A corp entry in the tracked manifest is deliberately alias-only — no path, no remote — which is
+  what keeps employer names out of a file that gets pushed. It also means the entry resolves to
+  nothing on its own. Registering wrote only that half, so every corp registration ended as a
+  dangling entry that `fleet check` reported immediately and the user had to fix by hand, in the
+  one file the tool otherwise never asks anyone to hand-edit.
+
+  The mapping is written `~`-relative, so the local manifest stays portable between machines, and
+  merged into the existing document so hand-maintained entries survive.
+
+  Two refusals guard it, because this file is the one place real employer directory names are
+  written down. If the local manifest is not gitignored, registration refuses rather than creating
+  a file git would track — a leak the tool creates is worse than a registration it declines to
+  finish. If the file exists but is not valid JSON, it refuses rather than overwriting mappings
+  that cannot be re-derived.
+
+  The mapping is written before the tracked entry. The failure modes are not symmetric: a mapping
+  without an entry is inert, while an entry without a mapping is a broken registration sitting in
+  the file that gets committed.
+
+- 9546979: `fleet add` no longer records a remote URL in the manifest.
+
+  The field was write-only: nothing in the tool ever read it back. It was persisted because it
+  happened to be derivable at registration time, and it stayed because no one asked what consumed
+  it.
+
+  It is also the field that turned a mis-profiled entry into a real disclosure. A raw remote URL
+  carries the host and the internal group path; `path` carries a bare directory name. Removing a
+  field no consumer reads retires that class outright, with no host-matching heuristic, and unlike
+  the corp-host guard it keeps working on a machine that has no local manifest to read corp hosts
+  from. The remote stays derivable from the checkout at any time, which is where it came from.
+
+  Existing entries that already carry a remote are left alone — nothing reads them, and rewriting
+  a hand-maintained manifest to remove inert keys would be a worse trade than leaving them.
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -96,6 +96,10 @@ _From Greek **étymon** — a word's true, original sense (→ etymology) — cl
   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.
+- **"The shellcheck step announced that it skipped."** That is the intended behaviour, not a
+  misconfiguration: where the binary is absent the hook says so and names the install command,
+  because a check that goes quiet when its tool is missing looks installed everywhere and is
+  installed nowhere.
 
 ---
 
@@ -153,24 +157,24 @@ 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.                                        |
-| `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 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).
@@ -252,8 +256,9 @@ request diff like any other change. Keep `.etymd` out of your formatter's reach
 [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.
+`etymd gates` installs the local pre-commit / pre-push mirror built from your own check scripts —
+and from the repo's shell scripts, which usually have no check of their own — while the
+`gate-integrity` lens flags whatever still runs in CI alone.
 
 ### Your own checks, beside the generated ones
 
@@ -282,6 +287,24 @@ was edited or went stale, never that you added a check of your own. Delete the c
 checks stop running — that is what deleting a file means, and etymd does not police a file it
 does not own.
 
+### The shell surface
+
+Package scripts are not the only executable surface a repo has, and in some repos they are not
+the main one — a tools or infra repo can be entirely `bootstrap/*.sh` plus `.githooks/*` with no
+`package.json` at all. Those repos were told "no correctness commands detected", which reads as
+"nothing to check" when it means "nothing was looked at". Where a repo has tracked shell scripts,
+the generated pre-push now carries a `shellcheck` step. Three properties are deliberate:
+
+- **Scripts are re-discovered by shebang at push time**, never baked into the hook as a list. A
+  generated list is correct the day it is written and silently wrong the first time someone adds
+  a script.
+- **A missing `shellcheck` binary is a loud skip that names the install command**, never a quiet
+  pass. A check that goes silent when its tool is absent looks installed on every machine and is
+  installed on one.
+- **Only `warning` severity and above blocks**; style and info print as advice afterwards. A gate
+  with a high false-positive rate does not make a repo careful — it teaches everyone the bypass
+  flag, and that flag is shared with the checks that must never be bypassed.
+
 ### The content screen (`etymd screen`)
 
 A separate question from "are the instructions true?": **does this repo carry text that must
@@ -471,9 +494,10 @@ Without it — on a fresh clone or in CI — those suites skip cleanly and the r
 
 [`docs/decisions/`](https://github.com/triartleet/etymd/tree/main/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`](https://github.com/triartleet/etymd/blob/main/ROADMAP.md) — what's now / next / later, the pre-publish checklist, and the
-accepted heuristic trade-offs.
+**004 fleet mode** (the truth guard across your repositories) · 005 declared rules (design only) ·
+**006 local gate provenance** (what the tool may read, and what it may rewrite).
+[`ROADMAP.md`](https://github.com/triartleet/etymd/blob/main/ROADMAP.md) — what's now / next / later, and the accepted heuristic
+trade-offs.
 
 ## License
 

package/dist/{approve-FISVPFL2.js → approve-ZLOW4A7R.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { section, theme, print, renderBaselineDrift, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HX5IYDCU.js';
-import { VERSION } from './chunk-WWV5W2MM.js';
-import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-5BVKFJWM.js';
+import { scanProject } from './chunk-ULEWJ3ZK.js';
+import { VERSION } from './chunk-HLWCODYX.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-C7LBUFNU.js';
+import { PACK_VERSION } from './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';
 
 // src/commands/approve.ts
 async function run(opts) {

package/dist/audit-ICT2JK7A.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export { run } from './chunk-BQGCLPHS.js';
+import './chunk-OESQNO2J.js';
+import './chunk-OKU3HXIH.js';
+import './chunk-OAFYLBVG.js';
+import './chunk-K7QBTANO.js';
+import './chunk-5BVKFJWM.js';
+import './chunk-ULEWJ3ZK.js';
+import './chunk-HLWCODYX.js';
+import './chunk-C7LBUFNU.js';
+import './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';

package/dist/{brief-UF6KV7SG.js → brief-PDUGGMLI.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { print, theme } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HX5IYDCU.js';
-import './chunk-WWV5W2MM.js';
-import { ETYMD_DIR } from './chunk-R74SJ7HS.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';
+import { print, theme } from './chunk-5BVKFJWM.js';
+import { scanProject } from './chunk-ULEWJ3ZK.js';
+import './chunk-HLWCODYX.js';
+import { ETYMD_DIR } from './chunk-C7LBUFNU.js';
+import './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 

package/dist/{chunk-TADKOW6P.js → chunk-5BVKFJWM.js}

@@ -128,11 +128,15 @@ function renderContext(budget, threshold) {
     print(`  ${glyph.ok} ${theme.dim("lean \u2014 no single file is heavy enough to extract yet")}`);
   }
 }
-function renderPlan(files) {
+function renderPlan(files, opts = {}) {
   section("Plan");
   for (const f of files) {
-    const tag = !f.exists ? theme.ok("create") : f.differs ? theme.warn("differs") : theme.dim("same");
-    print(`  ${pc.dim("[")}${tag}${pc.dim("]")} ${theme.info(f.path)}  ${theme.dim(f.label)}`);
+    const stale = f.differs && f.drift === "stale";
+    const tag = !f.exists ? theme.ok("create") : stale ? theme.warn("stale") : f.differs ? theme.warn("differs") : theme.dim("same");
+    const note = !f.differs ? "" : stale ? opts.regeneratesStale ? " \u2014 unedited since etymd generated it; regenerating" : " \u2014 unedited since etymd generated it" : f.drift === "edited" ? " \u2014 hand-edited since etymd generated it; keeping" : " \u2014 no etymd generation stamp; keeping";
+    print(
+      `  ${pc.dim("[")}${tag}${pc.dim("]")} ${theme.info(f.path)}  ${theme.dim(f.label)}${theme.dim(note)}`
+    );
   }
 }
 var TIER_BADGE = {

package/dist/{chunk-IGHES6AK.js → chunk-6DUDIVIC.js}

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

package/dist/{chunk-4AEYMVZK.js → chunk-BQGCLPHS.js}

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

package/dist/{chunk-R74SJ7HS.js → chunk-C7LBUFNU.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readJson } from './chunk-YLNQQZ5F.js';
+import { readJson } from './chunk-IV3FYVTS.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 

package/dist/{chunk-WWV5W2MM.js → chunk-HLWCODYX.js}

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

package/dist/{chunk-YLNQQZ5F.js → chunk-IV3FYVTS.js}

@@ -34,6 +34,16 @@ async function isDirectory(p) {
     return false;
   }
 }
+async function isExecutable(p) {
+  try {
+    const stat = await promises.stat(p);
+    if (!stat.isFile()) return false;
+    if (process.platform === "win32") return null;
+    return (stat.mode & 73) !== 0;
+  } catch {
+    return false;
+  }
+}
 async function git(root, args) {
   try {
     const { stdout } = await pExecFile("git", args, { cwd: root, timeout: 4e3 });
@@ -99,4 +109,4 @@ function matchesAnyGlob(p, globs) {
   return globs.some((g) => matchesGlob(p, g));
 }
 
-export { approxTokens, git, isCiEnvironment, isDirectory, matchesAnyGlob, normalizeRelPath, pathExists, readJson, readText, wordCount };
+export { approxTokens, git, isCiEnvironment, isDirectory, isExecutable, matchesAnyGlob, normalizeRelPath, pathExists, readJson, readText, wordCount };

package/dist/{chunk-NMZ3RHWW.js → chunk-K7QBTANO.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { ETYMD_DIR } from './chunk-R74SJ7HS.js';
-import { pathExists, readText } from './chunk-YLNQQZ5F.js';
+import { ETYMD_DIR } from './chunk-C7LBUFNU.js';
+import { pathExists, readText } from './chunk-IV3FYVTS.js';
 import path from 'node:path';
 
 var CONFIG_FILE = path.join(ETYMD_DIR, "config.json");

package/dist/{chunk-OX3LUOZR.js → chunk-KTIEYKFK.js}

@@ -1,10 +1,29 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG } from './chunk-NMZ3RHWW.js';
-import { PACK_VERSION } from './chunk-IGHES6AK.js';
-import { readText, pathExists } from './chunk-YLNQQZ5F.js';
+import { DEFAULT_CONFIG } from './chunk-K7QBTANO.js';
+import { PACK_VERSION } from './chunk-6DUDIVIC.js';
+import { readText, pathExists } from './chunk-IV3FYVTS.js';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
-// src/pack/templates.ts
+var GENERATION_MARKER_RE = /^(?:# |<!-- )etymd:generated pack-v\S+ ([0-9a-f]{16})(?: -->)?$/;
+function digestOf(body) {
+  return createHash("sha256").update(body).digest("hex").slice(0, 16);
+}
+function stampGenerated(body, comment = "sh") {
+  const marker = `etymd:generated pack-v${PACK_VERSION} ${digestOf(body)}`;
+  return `${body}${comment === "md" ? `<!-- ${marker} -->` : `# ${marker}`}
+`;
+}
+function fileOrigin(text) {
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const match = GENERATION_MARKER_RE.exec(lines[i]);
+    if (!match) continue;
+    const body = [...lines.slice(0, i), ...lines.slice(i + 1)].join("\n");
+    return digestOf(body) === match[1] ? "pack" : "edited";
+  }
+  return "unstamped";
+}
 function runPrefix(pm) {
   switch (pm) {
     case "pnpm":
@@ -57,7 +76,8 @@ function generateAgentsMd(facts) {
   const frameworks = facts.frameworks.length ? facts.frameworks.join(", ") : "none detected";
   const workspace = facts.workspace.kind === "none" ? "single package" : `${facts.workspace.kind} workspace`;
   const topDirs = facts.tree.dirs.slice(0, 14);
-  return `# AGENTS.md
+  return stampGenerated(
+    `# AGENTS.md
 
 Operating contract for AI agents working in **${facts.name}**. One source of truth \u2014 most agents
 (Claude Code, Codex, Cursor, Copilot, Gemini, \u2026) read this file natively. Kept true by
@@ -100,16 +120,17 @@ ${done.map((d) => `- ${d}`).join("\n")}` : `Define the check commands that gate
 
 \`\`\`bash
 ${[
-    facts.commands.dev && `${run} ${facts.commands.dev}`,
-    facts.commands.build && `${run} ${facts.commands.build}`,
-    facts.commands.test && `${run} ${facts.commands.test}`,
-    facts.commands.lint && `${run} ${facts.commands.lint}`,
-    facts.commands.typecheck && `${run} ${facts.commands.typecheck}`
-  ].filter(Boolean).join("\n") || "# add the project's key commands"}
+      facts.commands.dev && `${run} ${facts.commands.dev}`,
+      facts.commands.build && `${run} ${facts.commands.build}`,
+      facts.commands.test && `${run} ${facts.commands.test}`,
+      facts.commands.lint && `${run} ${facts.commands.lint}`,
+      facts.commands.typecheck && `${run} ${facts.commands.typecheck}`
+    ].filter(Boolean).join("\n") || "# add the project's key commands"}
 \`\`\`
 
-<!-- etymd pack v${PACK_VERSION} -->
-`;
+`,
+    "md"
+  );
 }
 var CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(command -v etymd || true)}"`;
 function localHookCall(hook) {
@@ -121,7 +142,7 @@ if [ -x "$LOCAL" ]; then
 fi`;
 }
 function generatePreCommitHook() {
-  return `#!/usr/bin/env sh
+  return stampGenerated(`#!/usr/bin/env sh
 # etymd: process gate. Cheap, locally-knowable checks belong here (fast, blocks the commit).
 
 ${localHookCall("pre-commit")}
@@ -138,10 +159,10 @@ if [ -x "$GATE" ]; then
 fi
 
 exit 0
-`;
+`);
 }
 function generateCommitMsgHook() {
-  return `#!/usr/bin/env sh
+  return stampGenerated(`#!/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
@@ -156,7 +177,7 @@ fi
 ${localHookCall("commit-msg")}
 
 exit 0
-`;
+`);
 }
 function shellcheckStep() {
   return `
@@ -209,7 +230,7 @@ if command -v etymd >/dev/null 2>&1; then
 else
   echo "\u203A etymd audit skipped (not on PATH)"
 fi`;
-  return `#!/usr/bin/env sh
+  return stampGenerated(`#!/usr/bin/env sh
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
 
 ${localHookCall("pre-push")}
@@ -225,10 +246,10 @@ if [ -x "$GATE" ] && [ "\${CONTENT_GATE_PREPUSH:-1}" = "1" ]; then
 fi
 
 exit 0
-`;
+`);
 }
 function generateArtifactCheckScript() {
-  return `#!/usr/bin/env sh
+  return stampGenerated(`#!/usr/bin/env sh
 # etymd: content screen \u2014 the published ARTIFACT, not the repository.
 #
 # Wire it into the irreversible moment:
@@ -257,7 +278,7 @@ fi
 
 "$GATE" screen --dir "$WORK" || exit 1
 exit 0
-`;
+`);
 }
 
 // src/core/generate.ts
@@ -277,11 +298,14 @@ async function planWorkflow(root, facts, opts) {
     const abs = path.join(root, rel);
     const exists = await pathExists(abs);
     const existing = exists ? await readText(abs) : null;
+    const differs = exists ? existing !== contents : void 0;
+    const origin = differs && existing !== null ? fileOrigin(existing) : void 0;
     out.push({
       path: rel,
       contents,
       exists,
-      differs: exists ? existing !== contents : void 0,
+      differs,
+      drift: origin === "pack" ? "stale" : origin,
       executable,
       label
     });

package/dist/{chunk-WWBF4Y7K.js → chunk-OAFYLBVG.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readJson } from './chunk-YLNQQZ5F.js';
+import { readJson } from './chunk-IV3FYVTS.js';
 import { promises } from 'node:fs';
 import path from 'node:path';