etymd 0.5.0 → 0.6.0

package/dist/index.js

@@ -2,6 +2,7 @@ import { execFile } from 'node:child_process';
 import { promises } from 'node:fs';
 import { promisify } from 'node:util';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import YAML from 'yaml';
 import os from 'node:os';
 
@@ -19,7 +20,7 @@ var __export = (target, all) => {
 var PACK_VERSION;
 var init_version = __esm({
   "src/pack/version.ts"() {
-    PACK_VERSION = "5";
+    PACK_VERSION = "6";
   }
 });
 
@@ -29,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.5.0",
+      version: "0.6.0",
       description: "Keep your agent instructions true \u2014 verify AGENTS.md, CLAUDE.md, rules & skills against the actual repo, with drift caught over time and a regression ledger.",
       keywords: [
         "cli",
@@ -89,14 +90,13 @@ var init_package = __esm({
         prepare: "npm run build",
         prepublishOnly: "npm run build && ./scripts/artifact-check.sh",
         changeset: "changeset",
-        "version:packages": "changeset version",
-        release: "npm run build && changeset publish"
+        "version:packages": "changeset version"
       },
       dependencies: {
         "@clack/prompts": "0.7.0",
         commander: "12.1.0",
         picocolors: "1.1.1",
-        yaml: "2.7.0"
+        yaml: "2.9.0"
       },
       devDependencies: {
         "@changesets/cli": "2.27.11",
@@ -152,6 +152,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 });
@@ -990,8 +1000,24 @@ var init_config = __esm({
     };
   }
 });
-
-// src/pack/templates.ts
+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":
@@ -1044,7 +1070,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
@@ -1087,16 +1114,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"
+  );
 }
 function localHookCall(hook) {
   return `# Repo-owned checks. This file is generated and will be overwritten; \`.githooks/${hook}.local\`
@@ -1107,7 +1135,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")}
@@ -1124,10 +1152,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
@@ -1142,7 +1170,7 @@ fi
 ${localHookCall("commit-msg")}
 
 exit 0
-`;
+`);
 }
 function shellcheckStep() {
   return `
@@ -1195,7 +1223,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")}
@@ -1211,10 +1239,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:
@@ -1243,12 +1271,13 @@ fi
 
 "$GATE" screen --dir "$WORK" || exit 1
 exit 0
-`;
+`);
 }
-var CONTENT_GATE_RESOLUTION;
+var GENERATION_MARKER_RE, CONTENT_GATE_RESOLUTION;
 var init_templates = __esm({
   "src/pack/templates.ts"() {
     init_version();
+    GENERATION_MARKER_RE = /^(?:# |<!-- )etymd:generated pack-v\S+ ([0-9a-f]{16})(?: -->)?$/;
     CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(command -v etymd || true)}"`;
   }
 });
@@ -1275,11 +1304,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
     });
@@ -1696,13 +1728,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 = [];
@@ -1746,7 +1808,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"));
@@ -1879,6 +1951,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));
@@ -1979,6 +2069,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);
@@ -3571,7 +3671,14 @@ async function checkGateDrift(manifest, findings, disclosures) {
     const { config } = await readConfig2(root);
     const planned = (await planWorkflow2(root, facts, { agents: false, gates: true, gateConfig: config.gates })).filter((f) => f.executable);
     const missing = planned.filter((f) => !f.exists).map((f) => f.path);
-    const stale = planned.filter((f) => f.exists && f.differs).map((f) => f.path);
+    const differing = planned.filter((f) => f.exists && f.differs);
+    const stale = differing.filter((f) => f.drift !== "edited").map((f) => f.path);
+    const edited = differing.filter((f) => f.drift === "edited").map((f) => f.path);
+    if (edited.length) {
+      disclosures.push(
+        `${entry.name}: ${edited.join(", ")} edited since etymd generated ${edited.length === 1 ? "it" : "them"} \u2014 a customisation, not drift; etymd will not overwrite ${edited.length === 1 ? "it" : "them"}`
+      );
+    }
     if (missing.length) {
       findings.push(
         finding3(
@@ -3591,8 +3698,8 @@ async function checkGateDrift(manifest, findings, disclosures) {
           "polish",
           `\`${entry.name}\` has ${stale.length} gate${stale.length === 1 ? "" : "s"} that differ from what its own inputs generate`,
           stale.map((s) => `${entry.name}: ${s}`),
-          "A hand-edited or outdated hook drifts from the pack silently \u2014 the repo believes it runs checks the file no longer contains.",
-          "Re-run `etymd gates` (it asks before overwriting), or record the intent in .etymd/config.json."
+          "An outdated hook drifts from the pack silently \u2014 the repo believes it runs checks the file no longer contains.",
+          "Re-run `etymd gates` in that repo \u2014 it regenerates a gate it provably wrote and asks before touching anything else."
         )
       );
     }

package/dist/{init-AVE2GDJ6.js → init-IPUPP4GB.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { applyFiles } from './chunk-EF6BPBG6.js';
-import { planWorkflow } from './chunk-OX3LUOZR.js';
-import './chunk-NMZ3RHWW.js';
-import { theme, renderFacts, print, renderPlan, section, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-4KOP36RD.js';
-import { VERSION } from './chunk-OJVQXB5Z.js';
-import { writeCachedFacts, deriveProfile, writeBaseline, CACHE_DIR } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-IGHES6AK.js';
-import { git, readText } from './chunk-YLNQQZ5F.js';
+import { planWorkflow } from './chunk-KTIEYKFK.js';
+import './chunk-K7QBTANO.js';
+import { theme, renderFacts, print, renderPlan, section, glyph } from './chunk-5BVKFJWM.js';
+import { scanProject } from './chunk-ULEWJ3ZK.js';
+import { VERSION } from './chunk-HLWCODYX.js';
+import { writeCachedFacts, deriveProfile, writeBaseline, CACHE_DIR } from './chunk-C7LBUFNU.js';
+import { PACK_VERSION } from './chunk-6DUDIVIC.js';
+import { git, readText } from './chunk-IV3FYVTS.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 import { intro, spinner, select, confirm, outro, isCancel, cancel } from '@clack/prompts';

package/dist/ledger-B2XGANTH.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+export { accept, dismiss, list } from './chunk-V2SOHPXF.js';
+import './chunk-OAFYLBVG.js';
+import './chunk-5BVKFJWM.js';
+import './chunk-IV3FYVTS.js';

package/dist/{scan-5DSECI43.js → scan-6L4L2GXT.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { print, renderFacts, theme } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-4KOP36RD.js';
-import './chunk-OJVQXB5Z.js';
-import { writeCachedFacts } from './chunk-R74SJ7HS.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';
+import { print, renderFacts, theme } from './chunk-5BVKFJWM.js';
+import { scanProject } from './chunk-ULEWJ3ZK.js';
+import './chunk-HLWCODYX.js';
+import { writeCachedFacts } from './chunk-C7LBUFNU.js';
+import './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';
 
 // src/commands/scan.ts
 async function run(opts) {

package/dist/scan-D4M7JXE3.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+export { scanProject } from './chunk-ULEWJ3ZK.js';
+import './chunk-HLWCODYX.js';
+import './chunk-6DUDIVIC.js';
+import './chunk-IV3FYVTS.js';

package/dist/{screen-U7JMWZPS.js → screen-6R6NXDSY.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { print, glyph, theme, section } from './chunk-TADKOW6P.js';
-import { readText, git, pathExists } from './chunk-YLNQQZ5F.js';
+import { print, glyph, theme, section } from './chunk-5BVKFJWM.js';
+import { readText, git, pathExists } from './chunk-IV3FYVTS.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etymd",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Keep your agent instructions true — verify AGENTS.md, CLAUDE.md, rules & skills against the actual repo, with drift caught over time and a regression ledger.",
   "keywords": [
     "cli",
@@ -60,14 +60,13 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && ./scripts/artifact-check.sh",
     "changeset": "changeset",
-    "version:packages": "changeset version",
-    "release": "npm run build && changeset publish"
+    "version:packages": "changeset version"
   },
   "dependencies": {
     "@clack/prompts": "0.7.0",
     "commander": "12.1.0",
     "picocolors": "1.1.1",
-    "yaml": "2.7.0"
+    "yaml": "2.9.0"
   },
   "devDependencies": {
     "@changesets/cli": "2.27.11",

package/dist/audit-LPZOGOHE.js

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-export { run } from './chunk-CYSEGWIW.js';
-import './chunk-QJRPKZPA.js';
-import './chunk-LT67FU2Y.js';
-import './chunk-WWBF4Y7K.js';
-import './chunk-NMZ3RHWW.js';
-import './chunk-TADKOW6P.js';
-import './chunk-4KOP36RD.js';
-import './chunk-OJVQXB5Z.js';
-import './chunk-R74SJ7HS.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';

package/dist/config-MX7OYI7F.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-export { CONFIG_FILE, DEFAULT_CONFIG, configPath, readConfig } from './chunk-NMZ3RHWW.js';
-import './chunk-R74SJ7HS.js';
-import './chunk-YLNQQZ5F.js';

package/dist/doctor-MJ6RBZ2Q.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-import { run } from './chunk-CYSEGWIW.js';
-import './chunk-QJRPKZPA.js';
-import './chunk-LT67FU2Y.js';
-import './chunk-WWBF4Y7K.js';
-import './chunk-NMZ3RHWW.js';
-import './chunk-TADKOW6P.js';
-import './chunk-4KOP36RD.js';
-import './chunk-OJVQXB5Z.js';
-import './chunk-R74SJ7HS.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';
-
-// src/commands/doctor.ts
-async function run2(opts) {
-  await run({ cwd: opts.cwd, json: opts.json, truth: true });
-}
-
-export { run2 as run };

package/dist/generate-CBMTNN7P.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-export { derivedCommands, planWorkflow } from './chunk-OX3LUOZR.js';
-import './chunk-NMZ3RHWW.js';
-import './chunk-R74SJ7HS.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';

package/dist/ledger-TMIV45AA.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-export { accept, dismiss, list } from './chunk-MMPV67FW.js';
-import './chunk-WWBF4Y7K.js';
-import './chunk-TADKOW6P.js';
-import './chunk-YLNQQZ5F.js';

package/dist/scan-ES7IOXOC.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-export { scanProject } from './chunk-4KOP36RD.js';
-import './chunk-OJVQXB5Z.js';
-import './chunk-IGHES6AK.js';
-import './chunk-YLNQQZ5F.js';