etymd 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # etymd
 
+## 0.7.0
+
+### Minor Changes
+
+- 7371c8b: Decisions records can require fields of their own, and etymd holds no opinion about which.
+
+  A decisions file already opts into per-entry format checks with a marker. It can now append field
+  names to it — `<!-- decisions-format: 1 fields=Owner,Rollback -->` — and every entry after the
+  marker must carry each one. `Owner:` and `**Owner:**` both count. Decision record:
+  [`docs/decisions/007-declared-entry-fields.md`](docs/decisions/007-declared-entry-fields.md).
+
+  **The tool ships the shape, not the vocabulary.** Etymd never interprets a declared name and has no
+  list of fields it thinks a record ought to have; it verifies that a line introducing the name
+  exists, and that is all. Which fields are worth requiring is the file's position to take, not the
+  tool's — a name coined for one project's process is exactly the kind of opinion this package does
+  not ship, however cleanly it would mechanize.
+
+  **Nothing is dropped in silence.** A name that cannot be used as a field, a marker version this
+  build does not know, and a redeclared `Scope` are each disclosed in the lens report. A file that
+  believes it declared a requirement, and is quietly audited without it, would come back clean for
+  the one reason this tool exists to reject — so the failure is stated rather than absorbed.
+  Declarable names are letters, digits, spaces, `-` and `_`, which keeps regex metacharacters out of
+  the matcher by construction.
+
+  **Enforcement is every-entry, with no keyword trigger.** Requiring the fields only on entries whose
+  prose looks like it is claiming something would flag an entry that mentions a closed tab or a fixed
+  price, and a false "your file is lying" costs more trust than a missed one. Every entry after the
+  marker is held to the same rule, which is what `Scope:` already does and takes one sentence to
+  explain.
+
+  **Existing files are unaffected.** `fields=` is an extension rather than a new format version: a
+  marker without it behaves exactly as before, pre-marker entries stay untouched, and a repo that
+  declares nothing sees no change. The declaration lives on the marker rather than in
+  `.etymd/config.json` so the requirement sits beside the entries it governs, which also lets a repo
+  keep two decision records with different obligations.
+
+## 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

package/README.md

@@ -147,7 +147,11 @@ _relative_ — a state doc is stale only when the repo moved past it, so a dorma
 state is current; a tracked file with uncommitted edits is treated fresh-now (the refresh is
 already on disk) and disclosed. Decisions records get format checks (`Scope:` presence, a
 `Revisit:` date that, once past, becomes a finding) — opt in by adding the literal marker
-`<!-- decisions-format: 1 -->` anywhere in the file; forward-only, never retroactive. Duplicate
+`<!-- decisions-format: 1 -->` anywhere in the file; forward-only, never retroactive. A file can
+require field names of its own by appending them to the marker —
+`<!-- decisions-format: 1 fields=Owner,Rollback -->` — and each is then checked on every entry.
+Etymd ships no field vocabulary and reads no meaning into the names; it verifies only that what
+the file declared is present, and discloses any name it could not use. Duplicate
 or out-of-order `D-NNN` ids are flagged with a rename action even without the marker — an
 append race is a defect in the file's own convention, not a format opinion.
 
@@ -494,9 +498,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-ASWRO6OD.js → approve-TXF3MA3G.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { section, theme, print, renderBaselineDrift, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-4KOP36RD.js';
-import { VERSION } from './chunk-OJVQXB5Z.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-XJMN2HMH.js';
+import { VERSION } from './chunk-OGIHOTLP.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-354X7QN6.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export { run } from './chunk-7LVCGCHB.js';
+import './chunk-LXEYYITD.js';
+import './chunk-OKU3HXIH.js';
+import './chunk-OAFYLBVG.js';
+import './chunk-K7QBTANO.js';
+import './chunk-5BVKFJWM.js';
+import './chunk-XJMN2HMH.js';
+import './chunk-OGIHOTLP.js';
+import './chunk-C7LBUFNU.js';
+import './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';

package/dist/{brief-HWD7CILP.js → brief-QUYHRWH6.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { print, theme } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-4KOP36RD.js';
-import './chunk-OJVQXB5Z.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-XJMN2HMH.js';
+import './chunk-OGIHOTLP.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-CYSEGWIW.js → chunk-7LVCGCHB.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-QJRPKZPA.js';
-import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-TADKOW6P.js';
+import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-LXEYYITD.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-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-QJRPKZPA.js → chunk-LXEYYITD.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { measureContext } from './chunk-LT67FU2Y.js';
-import { readLedger, reconcileLedger, writeLedger, visibleFindings } from './chunk-WWBF4Y7K.js';
-import { DEFAULT_CONFIG, readConfig, CONFIG_FILE } from './chunk-NMZ3RHWW.js';
-import { scanProject, expandFileGlobs } from './chunk-4KOP36RD.js';
-import { ETYMD_DIR, writeCachedFacts, readBaseline, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-IGHES6AK.js';
-import { pathExists, readJson, git, readText, isDirectory, matchesAnyGlob, isCiEnvironment, normalizeRelPath } from './chunk-YLNQQZ5F.js';
+import { measureContext } from './chunk-OKU3HXIH.js';
+import { readLedger, reconcileLedger, writeLedger, visibleFindings } from './chunk-OAFYLBVG.js';
+import { DEFAULT_CONFIG, readConfig, CONFIG_FILE } from './chunk-K7QBTANO.js';
+import { scanProject, expandFileGlobs } from './chunk-XJMN2HMH.js';
+import { ETYMD_DIR, writeCachedFacts, readBaseline, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE } from './chunk-C7LBUFNU.js';
+import { PACK_VERSION } from './chunk-6DUDIVIC.js';
+import { pathExists, readJson, git, readText, isDirectory, matchesAnyGlob, isCiEnvironment, normalizeRelPath, isExecutable } from './chunk-IV3FYVTS.js';
 import path from 'node:path';
 import YAML from 'yaml';
 import { promises } from 'node:fs';
@@ -302,13 +302,43 @@ function parseGithubWorkflow(text, file, scripts) {
   }
   return { jobs, parseErrors };
 }
+async function companionOf(root, hooksDir, hook, hookText, scripts) {
+  const rel = path.posix.join(hooksDir.split(path.sep).join("/"), `${hook}.local`);
+  if (!hookText.includes(`${hook}.local`)) return null;
+  const abs = path.join(root, hooksDir, `${hook}.local`);
+  const text = await readText(abs);
+  if (text === null) return null;
+  const [executable, hookExecutable] = await Promise.all([
+    isExecutable(abs),
+    isExecutable(path.join(root, hooksDir, hook))
+  ]);
+  if (executable === false && hookExecutable === true) return { rel, tools: [], state: "inert" };
+  return {
+    rel,
+    tools: matchTools(text, scripts),
+    state: executable === true ? "counted" : "unverified"
+  };
+}
 async function localHookTools(root, facts, scripts) {
   const hooks = facts.hooks;
   const empty = [];
+  const companions = [];
+  const unverifiedCompanions = [];
+  const inertCompanions = [];
   const readHook = async (name) => {
     if (!hooks.dir) return empty;
     const text = await readText(path.join(root, hooks.dir, name));
-    return text ? matchTools(text, scripts) : empty;
+    if (!text) return empty;
+    const tools = new Set(matchTools(text, scripts));
+    const companion = await companionOf(root, hooks.dir, name, text, scripts);
+    if (companion) {
+      if (companion.state === "inert") inertCompanions.push(companion.rel);
+      else {
+        (companion.state === "counted" ? companions : unverifiedCompanions).push(companion.rel);
+        for (const t of companion.tools) tools.add(t);
+      }
+    }
+    return [...tools];
   };
   let preCommit = [];
   let prePush = [];
@@ -352,7 +382,17 @@ async function localHookTools(root, facts, scripts) {
     }
   }
   const wired = hooks.source === "custom" || hooks.source === "husky" || hooks.source === "husky-legacy" ? true : hooks.source === "githooks" ? facts.git.hooksPath === hooks.dir : false;
-  return { source: hooks.source, wired, preCommit, prePush, commitMsg, lintStaged };
+  return {
+    source: hooks.source,
+    wired,
+    preCommit,
+    prePush,
+    commitMsg,
+    lintStaged,
+    companions,
+    unverifiedCompanions,
+    inertCompanions
+  };
 }
 async function detectThresholds(root, scripts, ciJobs) {
   const sonarConfigured = await pathExists(path.join(root, "sonar-project.properties")) || ciJobs.some((j) => j.tools.includes("sonar"));
@@ -485,6 +525,24 @@ function deriveGateFindings(inv, disclosures = []) {
       );
     }
   }
+  if (inv.local.inertCompanions?.length) {
+    const files = inv.local.inertCompanions;
+    findings.push(
+      finding({
+        id: `${LENS_ID2}/companion-not-executable`,
+        tier: "gap",
+        kind: "truth",
+        claim: `${files.join(", ")} ${files.length === 1 ? "is" : "are"} called by a hook but not executable \u2014 the checks inside never run`,
+        evidence: files,
+        why: "The hook guards the call with `[ -x ]`, so it skips the file in silence \u2014 the repo looks guarded and is not, on every clone that carries the same mode bit.",
+        // chmod alone does not survive a fresh clone: git tracks exactly one permission bit, so
+        // the fix has to reach the index or the dead gate propagates to everyone else.
+        action: `Run \`chmod +x ${files[0]}\` and commit the mode with \`git update-index --chmod=+x ${files[0]}\`.`,
+        effort: "S",
+        confidence: "high"
+      })
+    );
+  }
   for (const tool of CORRECTNESS_TOOLS) {
     if (!enforcedCiTools.has(tool) || localTools.has(tool)) continue;
     const jobs = enforcedCiJobs.filter((j) => j.tools.includes(tool));
@@ -585,6 +643,16 @@ var gateIntegrityLens = {
     }
     if (inv.ci.parseErrors.length)
       disclosures.push(...inv.ci.parseErrors.map((e) => `CI parse: ${e}`));
+    if (inv.local.companions.length) {
+      disclosures.push(
+        `Checks in ${inv.local.companions.join(", ")} are counted as locally enforced \u2014 the generated hook calls the companion, and etymd reads it without owning it.`
+      );
+    }
+    if (inv.local.unverifiedCompanions.length) {
+      disclosures.push(
+        `Checks in ${inv.local.unverifiedCompanions.join(", ")} are counted as locally enforced, but the execute bit could not be judged here (no POSIX mode bits, or the hook beside it is not executable either) \u2014 whether ${inv.local.unverifiedCompanions.length === 1 ? "it runs" : "they run"} was not verified.`
+      );
+    }
     if (inv.ci.system === "none")
       disclosures.push("No CI configuration found \u2014 CI\u2194local comparisons skipped.");
     const findings = deriveGateFindings(inv, disclosures);
@@ -1109,7 +1177,52 @@ var instructionTruthLens = {
 };
 var LENS_ID4 = "state-freshness";
 var DECISIONS_FORMAT_MARKER = "<!-- decisions-format: 1 -->";
+var KNOWN_FORMAT_VERSION = 1;
+var MARKER_RE = /<!--\s*decisions-format:\s*(\d+)([^>]*?)-->/;
+var FIELD_NAME_RE = /^[A-Za-z0-9 _-]+$/;
+var BUILT_IN_FIELDS = /* @__PURE__ */ new Set(["scope"]);
 var MS_PER_DAY = 864e5;
+function parseDecisionsFormat(text) {
+  const m = MARKER_RE.exec(text);
+  if (!m) return null;
+  const problems = [];
+  const fields = [];
+  const version = Number(m[1]);
+  if (version !== KNOWN_FORMAT_VERSION) {
+    problems.push(
+      `declares decisions-format version ${version}; this etymd understands version ${KNOWN_FORMAT_VERSION} \u2014 checked as version ${KNOWN_FORMAT_VERSION}.`
+    );
+  }
+  const attrs = (m[2] ?? "").trim();
+  if (!attrs) return { fields, problems };
+  const declared = /^fields=(.*)$/.exec(attrs);
+  if (!declared) {
+    problems.push(`marker attribute \`${attrs}\` is not understood \u2014 ignored (only \`fields=\`).`);
+    return { fields, problems };
+  }
+  const seen = new Set(BUILT_IN_FIELDS);
+  for (const raw of declared[1].split(",")) {
+    const name = raw.trim();
+    if (!name) continue;
+    if (!FIELD_NAME_RE.test(name)) {
+      problems.push(
+        `declared field \`${name}\` is not a usable field name (letters, digits, spaces, \`-\`, \`_\`) \u2014 not checked.`
+      );
+      continue;
+    }
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    fields.push(name);
+  }
+  if (fields.length === 0 && problems.length === 0) {
+    problems.push("marker declares `fields=` with no field names \u2014 no extra fields checked.");
+  }
+  return { fields, problems };
+}
+function hasField(block, name) {
+  return new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s*]*:`).test(block);
+}
 function parseDecisionEntries(text) {
   const headings = [...text.matchAll(/^## .*$/gm)];
   const entries = [];
@@ -1165,9 +1278,23 @@ function checkIdSequence(file, entries) {
   }
   return findings;
 }
-function checkFormatFields(file, entries, today) {
+function checkFormatFields(file, entries, today, declaredFields) {
   const findings = [];
   for (const entry of entries) {
+    for (const field of declaredFields) {
+      if (hasField(entry.block, field)) continue;
+      findings.push({
+        id: `${LENS_ID4}/field-missing:${file}:${entry.id}:${field}`,
+        lens: LENS_ID4,
+        tier: "gap",
+        claim: `${file} ${entry.id} has no ${field}: field`,
+        evidence: [`${file}: ${entry.id}`, `${file} marker declares required field \`${field}\``],
+        why: "The file declares this field required on every entry after the marker; whatever reads the record for it finds nothing here.",
+        action: `Add a ${field}: line to ${entry.id}.`,
+        effort: "S",
+        confidence: "high"
+      });
+    }
     if (!/Scope[\s*]*:/.test(entry.block)) {
       findings.push({
         id: `${LENS_ID4}/scope-missing:${file}:${entry.id}`,
@@ -1283,14 +1410,21 @@ var stateFreshnessLens = {
       }
       const entries = parseDecisionEntries(text);
       findings.push(...checkIdSequence(a.path, entries));
-      if (!text.includes(DECISIONS_FORMAT_MARKER)) {
+      const format = parseDecisionsFormat(text);
+      if (!format) {
         disclosures.push(
           `${a.path} carries no \`${DECISIONS_FORMAT_MARKER}\` marker \u2014 format checks skipped (forward-only, never retroactive); id-sequence checks still ran.`
         );
         outOfScope.push(a.path);
         continue;
       }
-      findings.push(...checkFormatFields(a.path, entries, today));
+      for (const problem of format.problems) disclosures.push(`${a.path}: ${problem}`);
+      if (format.fields.length > 0) {
+        disclosures.push(
+          `${a.path} declares required entry fields: ${format.fields.join(", ")} \u2014 checked on every entry (etymd attaches no meaning to the names).`
+        );
+      }
+      findings.push(...checkFormatFields(a.path, entries, today, format.fields));
     }
     disclosures.push(
       `Thresholds: staleAfterDays ${budgets.staleAfterDays} (3x escalates to risk), state budget ${budgets.maxChars} chars (${budgets.staleAfterDays === DEFAULT_CONFIG.state.staleAfterDays && budgets.maxChars === DEFAULT_CONFIG.state.maxChars ? `defaults \u2014 override under \`state\` in ${CONFIG_FILE}` : `set in ${CONFIG_FILE}`}). Decisions artifacts are exempt from age \u2014 old decisions are history, not defects.`

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