etymd 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # etymd
 
+## 0.4.0
+
+### Minor Changes
+
+- 69d1aad: Gate the shell surface: `etymd gates` now installs a shellcheck step in repos that have one.
+
+  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 — and those repos were told "no correctness commands detected", which reads
+  as "nothing to check" when it means "nothing was looked at".
+
+  The scan now counts tracked files a shell executes (`facts.shell.scripts`), by extension and by
+  shebang, and the generated pre-push gains a shellcheck step when that count is non-zero. Three
+  properties, each one a lesson from a gate that failed:
+
+  - Scripts are re-discovered inside the hook at push time, by shebang over tracked files, never
+    baked in 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.
+  - The blocking bar is severity `warning`; style and info print as advice. 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 content screen, which must never be bypassed.
+
+  The install summary lists the step too, so accepting the plan shows what will actually run.
+  Pack version 4.
+
+## 0.3.2
+
+### Patch Changes
+
+- A truth finding from any lens now reaches a `doctor` run.
+
+  `doctor` filters to truth-only, and it used to filter at the **lens** level — so `gate-integrity`
+  (an improvement lens) was skipped entirely, and its `hooks-not-wired` finding (tier: risk —
+  "tracked hooks exist but never run") was invisible in the one view meant to catch it. The lens
+  label was never the right granularity: a lens can emit both kinds, and "hooks exist and are
+  unwired" is as objective as anything the truth lens reports.
+
+  `kind` now lives on the Finding, defaulting to the lens kind when a finding does not set its
+  own, and the `--truth` filter operates at the finding level. Every lens still runs under
+  `--truth`; findings are filtered afterward, so nothing objective is invisible.
+
+  Also in this release: CI proves the publish tarball's exact manifest on every push (packagers
+  ignore `.gitignore`, so a stray local file can ship while every git-scoped check stays green),
+  and the generated hook companions (`.githooks/<hook>.local`) ship in this repo as a worked
+  example of the resolve-by-name convention.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -1,11 +1,11 @@
 # Etymd
 
 <div align="center">
-  <img src="media/etymd-logo.png" width="520" alt="Etymd — a papyrus of written instructions, each line checked against the repository it describes">
+  <img src="https://raw.githubusercontent.com/triartleet/etymd/main/media/etymd-logo.png" width="520" alt="Etymd — a papyrus of written instructions, each line checked against the repository it describes">
   <p>
     <a href="https://www.npmjs.com/package/etymd"><img src="https://img.shields.io/npm/v/etymd.svg?label=npm&color=cb3837" alt="npm version"></a>
     <a href="https://github.com/triartleet/etymd/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/triartleet/etymd/ci.yml?branch=main&label=CI" alt="CI"></a>
-    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
+    <a href="https://github.com/triartleet/etymd/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
   </p>
 </div>
 
@@ -335,7 +335,7 @@ agent-context file: claims about your fleet (what exists, where, under which **p
 side of the wall an entry belongs to, `personal` or `corp`; the **wall** is the placement
 boundary between personal and employer content that the sweep polices). It rots like any
 AGENTS.md does, and `etymd fleet` keeps it true. Decision record:
-[`docs/decisions/004-fleet-truth-guard.md`](docs/decisions/004-fleet-truth-guard.md). Both the
+[`docs/decisions/004-fleet-truth-guard.md`](https://github.com/triartleet/etymd/blob/main/docs/decisions/004-fleet-truth-guard.md). Both the
 registry schema and the fleet `--json` schema are **experimental through 0.2.x**.
 
 Two files beside each other — the split is the privacy model:
@@ -346,7 +346,7 @@ Two files beside each other — the split is the privacy model:
 {
   "registryVersion": 1,
   "root": "~/projects", // ~ expands on the consumer side — never a machine home
-  "orientation": { "root": "north" }, // optional: the entry every other entry is guided by
+  "orientation": { "root": "notes" }, // optional: the entry every other entry is guided by
   "projects": [
     {
       "name": "web-app",
@@ -451,7 +451,7 @@ console.log(audit.findings) // one schema: claim · evidence · why · action ·
 ## The corpus (how this is validated)
 
 Etymd is developed against a corpus of real sibling repos rather than fixtures alone —
-[`sources.json`](sources.json) lists them by shape. Every heuristic here exists because a real
+[`sources.json`](https://github.com/triartleet/etymd/blob/main/sources.json) lists them by shape. Every heuristic here exists because a real
 repo proved the previous one wrong, and each skip class in the truth lens is a false positive that
 a corpus run caught.
 
@@ -469,10 +469,10 @@ Without it — on a fresh clone or in CI — those suites skip cleanly and the r
 
 ## Decision record & roadmap
 
-[`docs/decisions/`](docs/decisions/) — 001 founding · 002 foundation re-lock · **003 the truth-guard
+[`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`](ROADMAP.md) — what's now / next / later, the pre-publish checklist, and the
+[`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.
 
 ## License

package/dist/{approve-3B2UL7LG.js → approve-Y6TX4LTN.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { section, theme, print, renderBaselineDrift, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import { VERSION } from './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import { VERSION } from './chunk-QYHROOMK.js';
 import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { PACK_VERSION } from './chunk-HGSLHNNT.js';
 import './chunk-YLNQQZ5F.js';
 
 // src/commands/approve.ts

package/dist/{audit-4YB3K62W.js → audit-AU4R45TP.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-export { run } from './chunk-MEJ4MBVL.js';
-import './chunk-V6NZEIHF.js';
+export { run } from './chunk-7K3BDNLW.js';
+import './chunk-ECY7BLBT.js';
 import './chunk-LT67FU2Y.js';
 import './chunk-WWBF4Y7K.js';
 import './chunk-NMZ3RHWW.js';
 import './chunk-TADKOW6P.js';
-import './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import './chunk-YLNQQZ5F.js';

package/dist/{brief-6EEXGQUW.js → brief-TIKPGPFV.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { print, theme } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import { ETYMD_DIR } from './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import './chunk-YLNQQZ5F.js';
 import { promises } from 'node:fs';
 import path from 'node:path';

package/dist/{chunk-MEJ4MBVL.js → chunk-7K3BDNLW.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-V6NZEIHF.js';
+import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-ECY7BLBT.js';
 import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-TADKOW6P.js';
 
 // src/commands/audit.ts

package/dist/{chunk-V6NZEIHF.js → chunk-ECY7BLBT.js}

@@ -2,9 +2,9 @@
 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-HOLFW5QY.js';
+import { scanProject, expandFileGlobs } from './chunk-SXCR6RRM.js';
 import { ETYMD_DIR, writeCachedFacts, readBaseline, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { PACK_VERSION } from './chunk-HGSLHNNT.js';
 import { pathExists, readJson, git, readText, isDirectory, matchesAnyGlob, isCiEnvironment, normalizeRelPath } from './chunk-YLNQQZ5F.js';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -474,6 +474,7 @@ function deriveGateFindings(inv, disclosures = []) {
         finding({
           id: `${LENS_ID2}/hooks-not-wired`,
           tier: "risk",
+          kind: "truth",
           claim: "Tracked .githooks/ exist but git core.hooksPath is unset \u2014 the hooks never run",
           evidence: [".githooks/"],
           why: "Every check in those hooks is silently skipped on this clone.",
@@ -1329,9 +1330,7 @@ async function runAudit(root, opts = {}) {
     };
   }
   const profile = baseline?.profile ?? deriveProfile(facts);
-  const selected = LENSES.filter(
-    (lens) => (!opts.kind || lens.kind === opts.kind) && (!opts.lensIds || opts.lensIds.includes(lens.id))
-  );
+  const selected = LENSES.filter((lens) => !opts.lensIds || opts.lensIds.includes(lens.id));
   const reports = [];
   for (const lens of selected) {
     try {
@@ -1349,11 +1348,12 @@ async function runAudit(root, opts = {}) {
       });
     }
   }
-  const all = reports.flatMap((r) => r.findings);
+  const all = reports.flatMap((r) => r.findings.map((f) => ({ ...f, kind: f.kind ?? r.kind })));
+  const visible = opts.kind ? all.filter((f) => f.kind === opts.kind) : all;
   const previous = await readLedger(ledgerRoot);
   const outOfScope = reports.flatMap((r) => r.outOfScope ?? []);
   const { ledger, diff } = reconcileLedger(previous, all, void 0, outOfScope);
-  const fullRun = selected.length === LENSES.length;
+  const fullRun = !opts.kind && !opts.lensIds;
   const ledgerWritable = !opts.readOnlyRoot || ledgerRoot !== root;
   if ((opts.persistLedger ?? true) && fullRun && ledgerWritable) {
     await writeLedger(ledgerRoot, ledger);
@@ -1364,7 +1364,7 @@ async function runAudit(root, opts = {}) {
     baseline,
     config,
     reports,
-    findings: rankFindings(visibleFindings(all, previous)),
+    findings: rankFindings(visibleFindings(visible, previous)),
     ledger,
     diff
   };

package/dist/{chunk-CRJHIXJH.js → chunk-HGSLHNNT.js}

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

package/dist/{chunk-VFUYQLW7.js → chunk-JTHZVEON.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { DEFAULT_CONFIG } from './chunk-NMZ3RHWW.js';
-import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { PACK_VERSION } from './chunk-HGSLHNNT.js';
 import { readText, pathExists } from './chunk-YLNQQZ5F.js';
 import path from 'node:path';
 
@@ -158,6 +158,25 @@ ${localHookCall("commit-msg")}
 exit 0
 `;
 }
+function shellcheckStep() {
+  return `
+# Shell correctness. Scripts are discovered by shebang over TRACKED files at push time, so a
+# script added later is covered without regenerating this hook.
+if command -v shellcheck >/dev/null 2>&1; then
+  scripts=$(git ls-files -z \\
+    | xargs -0 -I{} sh -c 'head -1 "{}" 2>/dev/null | grep -qE "^#!.*[/ ](ba|da|z)?sh( |$)" && echo "{}"' \\
+    | sort)
+  if [ -n "$scripts" ]; then
+    echo "\u203A shellcheck ($(printf '%s\\n' "$scripts" | wc -l | tr -d ' ') scripts, blocking at severity=warning)"
+    printf '%s\\n' "$scripts" | xargs shellcheck -S warning || {
+      echo "  fix, or justify inline with '# shellcheck disable=SCxxxx  # why'"
+      exit 1
+    }
+  fi
+else
+  echo "\u203A shellcheck skipped (not on PATH) \u2014 install it to gate this repo's shell scripts"
+fi`;
+}
 function generatePrePushHook(facts, gates) {
   const run = runPrefix(facts.packageManager);
   const c = facts.commands;
@@ -166,8 +185,14 @@ function generatePrePushHook(facts, gates) {
   const steps = candidates.filter(
     (key) => Boolean(key) && (allowed.has(key) || isSafeGateCommand(c.raw[key]))
   ).map((key) => `${run} ${key}`);
+  const shellStep = facts.shell?.scripts ? shellcheckStep() : "";
   const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
-${s} || exit 1`).join("\n") : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
+${s} || exit 1`).join("\n") : shellStep ? (
+    // A repo whose executable surface is shell HAS a correctness command — it just is not in
+    // package.json. Claiming "none detected" beside a step that is about to run would be the
+    // tool contradicting itself.
+    `echo "\u203A no package scripts \u2014 shell is this repo's checkable surface"`
+  ) : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
   const failOn = gates?.failOn ?? "risk";
   const auditStep = `
 if command -v etymd >/dev/null 2>&1; then
@@ -180,7 +205,7 @@ fi`;
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
 
 ${localHookCall("pre-push")}
-${body}
+${body}${shellStep}
 ${auditStep}
 
 # Content screen, second pass \u2014 the WHOLE TREE rather than one diff. Catches anything committed

package/dist/{chunk-DKC7MLWG.js → chunk-QYHROOMK.js}

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

package/dist/{chunk-HOLFW5QY.js → chunk-SXCR6RRM.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-DKC7MLWG.js';
-import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { VERSION } from './chunk-QYHROOMK.js';
+import { PACK_VERSION } from './chunk-HGSLHNNT.js';
 import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-YLNQQZ5F.js';
 import path from 'node:path';
 import { promises } from 'node:fs';
@@ -390,6 +390,33 @@ var ARTIFACT_SPECS = [
     kind: "map"
   }
 ];
+async function firstLine(file) {
+  let handle;
+  try {
+    handle = await promises.open(file, "r");
+    const { buffer, bytesRead } = await handle.read(Buffer.alloc(128), 0, 128, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8").split("\n", 1)[0] ?? "";
+  } catch {
+    return "";
+  } finally {
+    await handle?.close();
+  }
+}
+var SHELL_SHEBANG = /^#!\s*\/\S*\b(?:ba|da|z)?sh\b|^#!\s*\/usr\/bin\/env\s+(?:ba|da|z)?sh\b/;
+var SHELL_EXT = /\.(?:sh|bash|zsh)$/;
+async function detectShellSurface(root, isRepo) {
+  if (!isRepo) return { scripts: 0 };
+  const listed = await git(root, ["ls-files", "-z"]);
+  if (!listed) return { scripts: 0 };
+  const files = listed.split("\0").filter(Boolean);
+  const byExtension = files.filter((f) => SHELL_EXT.test(f));
+  const candidates = files.filter((f) => !path.basename(f).includes("."));
+  const SHEBANG_PROBE_CAP = 400;
+  const probed = await Promise.all(
+    candidates.slice(0, SHEBANG_PROBE_CAP).map(async (f) => SHELL_SHEBANG.test(await firstLine(path.join(root, f))))
+  );
+  return { scripts: byExtension.length + probed.filter(Boolean).length };
+}
 async function detectArtifacts(root) {
   const artifacts = await Promise.all(
     ARTIFACT_SPECS.map(async (spec) => ({
@@ -537,6 +564,7 @@ async function scanProject(root, opts = {}) {
   ]) : [null, null, null, null, null];
   const hooksPath = hooksPathRaw ?? void 0;
   const hooks = await detectHooks(abs, hooksPath, rootPkg);
+  const shell = await detectShellSurface(abs, isRepo);
   const freshness = await collectFreshness(abs, isRepo, artifacts, opts.upstreamRemote);
   const packages = workspace.packageGlobs.length ? await listWorkspacePackages(abs, workspace.packageGlobs) : [];
   const recentAuthors = authorsRaw ? new Set(authorsRaw.split("\n").filter(Boolean)).size : void 0;
@@ -568,6 +596,7 @@ async function scanProject(root, opts = {}) {
     // vsce — which never runs prepublishOnly.
     publishRoute: !rootPkg ? "none" : rootPkg.engines?.vscode ? "vscode" : "npm",
     artifacts,
+    shell,
     freshness,
     tree
   };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-DKC7MLWG.js';
+import { VERSION } from './chunk-QYHROOMK.js';
 import path from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
@@ -31,7 +31,7 @@ program.command("audit").description("Verify every instruction claim against the
   "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
 ).action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./audit-4YB3K62W.js');
+    const { run } = await import('./audit-AU4R45TP.js');
     await run({
       cwd: resolveCwd(cmd),
       json: opts.json,
@@ -44,7 +44,7 @@ program.command("audit").description("Verify every instruction claim against the
 );
 program.command("init").description("Onboard the truth guard: approve the baseline; scaffold AGENTS.md only if missing").option("-y, --yes", "accept defaults without prompting (never overwrites)").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./init-NSYVVMF2.js');
+    const { run } = await import('./init-BYZJOCS6.js');
     await run({ cwd: resolveCwd(cmd), yes: opts.yes });
   })
 );
@@ -52,19 +52,19 @@ program.command("approve").description(
   "Re-approve the committed baseline after intentional structural changes (non-interactive)"
 ).action(
   (_opts, cmd) => action(async () => {
-    const { run } = await import('./approve-3B2UL7LG.js');
+    const { run } = await import('./approve-Y6TX4LTN.js');
     await run({ cwd: resolveCwd(cmd) });
   })
 );
 program.command("scan").description("Deterministically reckon the project into a facts index").option("--json", "print the raw facts as JSON").option("--no-save", "do not write the .etymd cache").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./scan-COEPZJBO.js');
+    const { run } = await import('./scan-DPEOA3KZ.js');
     await run({ cwd: resolveCwd(cmd), json: opts.json, save: opts.save });
   })
 );
 program.command("doctor").description('Alias for `audit --truth` \u2014 "are the recorded instructions still true?"').option("--json", "print findings as JSON").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./doctor-T76ZNL4S.js');
+    const { run } = await import('./doctor-OE5E36DX.js');
     await run({ cwd: resolveCwd(cmd), json: opts.json });
   })
 );
@@ -76,7 +76,7 @@ program.command("context").description("Measure the always-loaded context footpr
 );
 program.command("brief").description("Emit a grounded briefing for the in-repo agent to complete the semantic layer").option("--human", "write a human onboarding brief instead of the agent briefing").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./brief-6EEXGQUW.js');
+    const { run } = await import('./brief-TIKPGPFV.js');
     await run({ cwd: resolveCwd(cmd), human: opts.human });
   })
 );
@@ -111,7 +111,7 @@ var fleet = program.command("fleet").description(
   "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
 ).action(
   (opts, cmd) => action(async () => {
-    const { sweep } = await import('./fleet-WOPKM2Z3.js');
+    const { sweep } = await import('./fleet-LSN5XZ5Q.js');
     await sweep({
       cwd: resolveCwd(cmd),
       manifest: opts.manifest,
@@ -126,7 +126,7 @@ var fleet = program.command("fleet").description(
 );
 fleet.command("check").description("Validate the manifest pair only \u2014 no lenses: dangling mappings, duplicates, leaks").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").option("--json", "print the findings as JSON (EXPERIMENTAL through 0.2.x)").action(
   (_opts, cmd) => action(async () => {
-    const { check } = await import('./fleet-WOPKM2Z3.js');
+    const { check } = await import('./fleet-LSN5XZ5Q.js');
     const opts = cmd.optsWithGlobals();
     await check({ cwd: resolveCwd(cmd), manifest: opts.manifest, json: opts.json });
   })
@@ -136,7 +136,7 @@ fleet.command("add").argument("<dir>", "directory of the project to register").d
   "public-repo | public-bound | private \u2014 mandatory for personal entries"
 ).option("-y, --yes", "skip prompts; every mandatory value must be passed as a flag").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (dir, opts, cmd) => action(async () => {
-    const { add } = await import('./fleet-WOPKM2Z3.js');
+    const { add } = await import('./fleet-LSN5XZ5Q.js');
     const shared = cmd.optsWithGlobals();
     await add({
       cwd: resolveCwd(cmd),
@@ -154,7 +154,7 @@ fleet.command("dismiss").argument("<name>", "the registered project name").argum
   "Dismiss a project's finding from any cwd \u2014 corp ledgers persist beside the manifest"
 ).requiredOption("--reason <text>", "why it is dismissed \u2014 recorded so the decision survives").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (name, id, _opts, cmd) => action(async () => {
-    const { dismiss } = await import('./fleet-WOPKM2Z3.js');
+    const { dismiss } = await import('./fleet-LSN5XZ5Q.js');
     const opts = cmd.optsWithGlobals();
     await dismiss({
       cwd: resolveCwd(cmd),
@@ -169,7 +169,7 @@ fleet.command("accept").argument("<name>", "the registered project name").argume
   "Accept a project's finding as a known trade-off \u2014 corp ledgers persist beside the manifest"
 ).option("--reason <text>", "optional note on why the trade-off is accepted").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (name, id, _opts, cmd) => action(async () => {
-    const { accept } = await import('./fleet-WOPKM2Z3.js');
+    const { accept } = await import('./fleet-LSN5XZ5Q.js');
     const opts = cmd.optsWithGlobals();
     await accept({ cwd: resolveCwd(cmd), manifest: opts.manifest, name, id, reason: opts.reason });
   })
@@ -191,7 +191,7 @@ program.command("screen").description(
 );
 program.command("gates").description("Install the local git-hook gates (process \u2192 pre-commit, correctness \u2192 pre-push)").option("--ci", "note about the CI review gate (ships later; local gates install now)").option("-y, --yes", "skip prompts; never overwrites a hand-edited hook").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./gates-WIGDS5VF.js');
+    const { run } = await import('./gates-IJNAQ7DC.js');
     await run({ cwd: resolveCwd(cmd), ci: opts.ci, yes: opts.yes });
   })
 );

package/dist/{doctor-T76ZNL4S.js → doctor-OE5E36DX.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
-import { run } from './chunk-MEJ4MBVL.js';
-import './chunk-V6NZEIHF.js';
+import { run } from './chunk-7K3BDNLW.js';
+import './chunk-ECY7BLBT.js';
 import './chunk-LT67FU2Y.js';
 import './chunk-WWBF4Y7K.js';
 import './chunk-NMZ3RHWW.js';
 import './chunk-TADKOW6P.js';
-import './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import './chunk-YLNQQZ5F.js';
 
 // src/commands/doctor.ts

package/dist/{fleet-WOPKM2Z3.js → fleet-LSN5XZ5Q.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { dismiss, accept } from './chunk-MMPV67FW.js';
-import { parseFailOnTier, meetsFailOn, runAudit } from './chunk-V6NZEIHF.js';
+import { parseFailOnTier, meetsFailOn, runAudit } from './chunk-ECY7BLBT.js';
 import './chunk-LT67FU2Y.js';
 import { readLedger } from './chunk-WWBF4Y7K.js';
 import { DEFAULT_CONFIG } from './chunk-NMZ3RHWW.js';
 import { print, theme, section, renderFleetRows, renderFleetNotes, renderFindings, TIER_BADGE, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import { ETYMD_DIR } from './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import { readText, pathExists, git, isDirectory } from './chunk-YLNQQZ5F.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
@@ -687,8 +687,8 @@ async function checkCorpEmails(manifest, findings, disclosures) {
   }
 }
 async function checkGateDrift(manifest, findings, disclosures) {
-  const { planWorkflow } = await import('./generate-I75IEXXF.js');
-  const { scanProject: scanProject2 } = await import('./scan-BAD2UJAL.js');
+  const { planWorkflow } = await import('./generate-JEREMVVO.js');
+  const { scanProject: scanProject2 } = await import('./scan-O3SM2ODH.js');
   const { readConfig } = await import('./config-MX7OYI7F.js');
   for (const entry of manifest.entries) {
     const root = entry.resolvedRoot;

package/dist/{gates-WIGDS5VF.js → gates-IJNAQ7DC.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { applyFiles } from './chunk-EF6BPBG6.js';
-import { derivedCommands, planWorkflow, runPrefix, isSafeGateCommand } from './chunk-VFUYQLW7.js';
+import { derivedCommands, planWorkflow, runPrefix, isSafeGateCommand } from './chunk-JTHZVEON.js';
 import { readConfig, CONFIG_FILE, configPath } from './chunk-NMZ3RHWW.js';
 import { section, print, glyph, theme, renderPlan } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import { readText, git } from './chunk-YLNQQZ5F.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
@@ -57,7 +57,9 @@ function publishGateKey(route) {
 }
 function printGateSummary(gates, facts, source) {
   const run2 = runPrefix(facts.packageManager);
-  const cmds = gates.commands.length ? gates.commands.map((c) => `${run2} ${c}`).join(", ") : "none detected";
+  const shellStep = facts.shell?.scripts ? `shellcheck (${facts.shell.scripts} script${facts.shell.scripts === 1 ? "" : "s"})` : "";
+  const listed = [...gates.commands.map((c) => `${run2} ${c}`), ...shellStep ? [shellStep] : []];
+  const cmds = listed.length ? listed.join(", ") : "none detected";
   print(`  ${glyph.bullet} ${theme.dim("pre-push runs")} ${theme.info(cmds)}`);
   print(`  ${glyph.bullet} ${theme.dim("audit fails on")} ${theme.info(gates.failOn)}`);
   print(

package/dist/{generate-I75IEXXF.js → generate-JEREMVVO.js}

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

package/dist/index.d.ts

@@ -121,6 +121,23 @@ interface ProjectFacts {
      */
     publishRoute: "npm" | "vscode" | "none";
     artifacts: DetectedArtifact[];
+    /**
+     * The repo's SHELL surface: tracked files that a shell executes.
+     *
+     * 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 are exactly the repos that report "no correctness
+     * commands detected", which reads as "nothing to check" when it means "nothing was looked at".
+     *
+     * Counted, not listed: the generated hook re-discovers scripts at push time by shebang, so it
+     * stays correct as the repo grows. This number only decides WHETHER the step is worth writing.
+     *
+     * Optional for the same reason as `freshness`: a facts file written by an older etymd predates
+     * the field, and absent must read as "not measured" rather than "measured as zero".
+     */
+    shell?: {
+        scripts: number;
+    };
     /** Optional: baselines approved by older versions predate this fact. */
     freshness?: FreshnessFacts;
     tree: {
@@ -279,6 +296,13 @@ interface Finding {
     id: string;
     lens: string;
     tier: FindingTier;
+    /**
+     * Whether this finding is an objective truth (the repo is lying) or an improvement opinion
+     * (something worth doing). Lives ON THE FINDING, not the lens: a lens can emit both kinds —
+     * gate-integrity is an improvement lens, but "hooks-not-wired" is an objective truth a `doctor`
+     * run must not skip. Defaulted from the lens kind when a finding does not set its own.
+     */
+    kind?: LensKind;
     /** One sentence: what is wrong / missing. */
     claim: string;
     /** File paths, job names, or metrics that ground the claim. Never empty. */
@@ -745,7 +769,7 @@ declare const gateIntegrityLens: Lens;
  * change meaning. Stamped into facts, baselines, and generated artifacts so drift against the
  * pack is computable and `harvest` has something to diff.
  */
-declare const PACK_VERSION = "3";
+declare const PACK_VERSION = "4";
 
 declare const VERSION: string;
 declare const NAME: string;

package/dist/index.js

@@ -19,7 +19,7 @@ var __export = (target, all) => {
 var PACK_VERSION;
 var init_version = __esm({
   "src/pack/version.ts"() {
-    PACK_VERSION = "3";
+    PACK_VERSION = "4";
   }
 });
 
@@ -29,7 +29,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.3.1",
+      version: "0.4.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",
@@ -438,6 +438,31 @@ async function detectHooks(root, hooksPath, pkg) {
   }
   return { source: "none", preCommit: false, prePush: false, commitMsg: false, lintStaged };
 }
+async function firstLine(file) {
+  let handle;
+  try {
+    handle = await promises.open(file, "r");
+    const { buffer, bytesRead } = await handle.read(Buffer.alloc(128), 0, 128, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8").split("\n", 1)[0] ?? "";
+  } catch {
+    return "";
+  } finally {
+    await handle?.close();
+  }
+}
+async function detectShellSurface(root, isRepo) {
+  if (!isRepo) return { scripts: 0 };
+  const listed = await git(root, ["ls-files", "-z"]);
+  if (!listed) return { scripts: 0 };
+  const files = listed.split("\0").filter(Boolean);
+  const byExtension = files.filter((f) => SHELL_EXT.test(f));
+  const candidates = files.filter((f) => !path.basename(f).includes("."));
+  const SHEBANG_PROBE_CAP = 400;
+  const probed = await Promise.all(
+    candidates.slice(0, SHEBANG_PROBE_CAP).map(async (f) => SHELL_SHEBANG.test(await firstLine(path.join(root, f))))
+  );
+  return { scripts: byExtension.length + probed.filter(Boolean).length };
+}
 async function detectArtifacts(root) {
   const artifacts = await Promise.all(
     ARTIFACT_SPECS.map(async (spec) => ({
@@ -504,7 +529,7 @@ async function walkTree(root) {
   dirs.sort((a, b) => b.files - a.files);
   return { dirs, truncated: state.truncated };
 }
-var IGNORED_DIRS, MEANINGFUL_DOT_DIRS, isMeta, ROLE_LADDERS, FRAMEWORK_MARKERS, ARTIFACT_SPECS;
+var IGNORED_DIRS, MEANINGFUL_DOT_DIRS, isMeta, ROLE_LADDERS, FRAMEWORK_MARKERS, ARTIFACT_SPECS, SHELL_SHEBANG, SHELL_EXT;
 var init_detect = __esm({
   "src/core/detect.ts"() {
     init_util();
@@ -677,6 +702,8 @@ var init_detect = __esm({
         kind: "map"
       }
     ];
+    SHELL_SHEBANG = /^#!\s*\/\S*\b(?:ba|da|z)?sh\b|^#!\s*\/usr\/bin\/env\s+(?:ba|da|z)?sh\b/;
+    SHELL_EXT = /\.(?:sh|bash|zsh)$/;
   }
 });
 
@@ -764,6 +791,7 @@ async function scanProject(root, opts = {}) {
   ]) : [null, null, null, null, null];
   const hooksPath = hooksPathRaw ?? void 0;
   const hooks = await detectHooks(abs, hooksPath, rootPkg);
+  const shell = await detectShellSurface(abs, isRepo);
   const freshness = await collectFreshness(abs, isRepo, artifacts, opts.upstreamRemote);
   const packages = workspace.packageGlobs.length ? await listWorkspacePackages(abs, workspace.packageGlobs) : [];
   const recentAuthors = authorsRaw ? new Set(authorsRaw.split("\n").filter(Boolean)).size : void 0;
@@ -795,6 +823,7 @@ async function scanProject(root, opts = {}) {
     // vsce — which never runs prepublishOnly.
     publishRoute: !rootPkg ? "none" : rootPkg.engines?.vscode ? "vscode" : "npm",
     artifacts,
+    shell,
     freshness,
     tree
   };
@@ -1115,6 +1144,25 @@ ${localHookCall("commit-msg")}
 exit 0
 `;
 }
+function shellcheckStep() {
+  return `
+# Shell correctness. Scripts are discovered by shebang over TRACKED files at push time, so a
+# script added later is covered without regenerating this hook.
+if command -v shellcheck >/dev/null 2>&1; then
+  scripts=$(git ls-files -z \\
+    | xargs -0 -I{} sh -c 'head -1 "{}" 2>/dev/null | grep -qE "^#!.*[/ ](ba|da|z)?sh( |$)" && echo "{}"' \\
+    | sort)
+  if [ -n "$scripts" ]; then
+    echo "\u203A shellcheck ($(printf '%s\\n' "$scripts" | wc -l | tr -d ' ') scripts, blocking at severity=warning)"
+    printf '%s\\n' "$scripts" | xargs shellcheck -S warning || {
+      echo "  fix, or justify inline with '# shellcheck disable=SCxxxx  # why'"
+      exit 1
+    }
+  fi
+else
+  echo "\u203A shellcheck skipped (not on PATH) \u2014 install it to gate this repo's shell scripts"
+fi`;
+}
 function generatePrePushHook(facts, gates) {
   const run = runPrefix(facts.packageManager);
   const c = facts.commands;
@@ -1123,8 +1171,14 @@ function generatePrePushHook(facts, gates) {
   const steps = candidates.filter(
     (key) => Boolean(key) && (allowed.has(key) || isSafeGateCommand(c.raw[key]))
   ).map((key) => `${run} ${key}`);
+  const shellStep = facts.shell?.scripts ? shellcheckStep() : "";
   const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
-${s} || exit 1`).join("\n") : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
+${s} || exit 1`).join("\n") : shellStep ? (
+    // A repo whose executable surface is shell HAS a correctness command — it just is not in
+    // package.json. Claiming "none detected" beside a step that is about to run would be the
+    // tool contradicting itself.
+    `echo "\u203A no package scripts \u2014 shell is this repo's checkable surface"`
+  ) : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
   const failOn = gates?.failOn ?? "risk";
   const auditStep = `
 if command -v etymd >/dev/null 2>&1; then
@@ -1137,7 +1191,7 @@ fi`;
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
 
 ${localHookCall("pre-push")}
-${body}
+${body}${shellStep}
 ${auditStep}
 
 # Content screen, second pass \u2014 the WHOLE TREE rather than one diff. Catches anything committed
@@ -1806,6 +1860,7 @@ function deriveGateFindings(inv, disclosures = []) {
         finding({
           id: `${LENS_ID2}/hooks-not-wired`,
           tier: "risk",
+          kind: "truth",
           claim: "Tracked .githooks/ exist but git core.hooksPath is unset \u2014 the hooks never run",
           evidence: [".githooks/"],
           why: "Every check in those hooks is silently skipped on this clone.",
@@ -2769,9 +2824,7 @@ async function runAudit(root, opts = {}) {
     };
   }
   const profile = baseline?.profile ?? deriveProfile(facts);
-  const selected = LENSES.filter(
-    (lens) => (!opts.kind || lens.kind === opts.kind) && (!opts.lensIds || opts.lensIds.includes(lens.id))
-  );
+  const selected = LENSES.filter((lens) => !opts.lensIds || opts.lensIds.includes(lens.id));
   const reports = [];
   for (const lens of selected) {
     try {
@@ -2789,11 +2842,12 @@ async function runAudit(root, opts = {}) {
       });
     }
   }
-  const all = reports.flatMap((r) => r.findings);
+  const all = reports.flatMap((r) => r.findings.map((f) => ({ ...f, kind: f.kind ?? r.kind })));
+  const visible = opts.kind ? all.filter((f) => f.kind === opts.kind) : all;
   const previous = await readLedger(ledgerRoot);
   const outOfScope = reports.flatMap((r) => r.outOfScope ?? []);
   const { ledger, diff } = reconcileLedger(previous, all, void 0, outOfScope);
-  const fullRun = selected.length === LENSES.length;
+  const fullRun = !opts.kind && !opts.lensIds;
   const ledgerWritable = !opts.readOnlyRoot || ledgerRoot !== root;
   if ((opts.persistLedger ?? true) && fullRun && ledgerWritable) {
     await writeLedger(ledgerRoot, ledger);
@@ -2804,7 +2858,7 @@ async function runAudit(root, opts = {}) {
     baseline,
     config,
     reports,
-    findings: rankFindings(visibleFindings(all, previous)),
+    findings: rankFindings(visibleFindings(visible, previous)),
     ledger,
     diff
   };

package/dist/{init-NSYVVMF2.js → init-BYZJOCS6.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { applyFiles } from './chunk-EF6BPBG6.js';
-import { planWorkflow } from './chunk-VFUYQLW7.js';
+import { planWorkflow } from './chunk-JTHZVEON.js';
 import './chunk-NMZ3RHWW.js';
 import { theme, renderFacts, print, renderPlan, section, glyph } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import { VERSION } from './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import { VERSION } from './chunk-QYHROOMK.js';
 import { writeCachedFacts, deriveProfile, writeBaseline, CACHE_DIR } from './chunk-R74SJ7HS.js';
-import { PACK_VERSION } from './chunk-CRJHIXJH.js';
+import { PACK_VERSION } from './chunk-HGSLHNNT.js';
 import { git, readText } from './chunk-YLNQQZ5F.js';
 import { promises } from 'node:fs';
 import path from 'node:path';

package/dist/{scan-COEPZJBO.js → scan-DPEOA3KZ.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { print, renderFacts, theme } from './chunk-TADKOW6P.js';
-import { scanProject } from './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
+import { scanProject } from './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
 import { writeCachedFacts } from './chunk-R74SJ7HS.js';
-import './chunk-CRJHIXJH.js';
+import './chunk-HGSLHNNT.js';
 import './chunk-YLNQQZ5F.js';
 
 // src/commands/scan.ts

package/dist/scan-O3SM2ODH.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+export { scanProject } from './chunk-SXCR6RRM.js';
+import './chunk-QYHROOMK.js';
+import './chunk-HGSLHNNT.js';
+import './chunk-YLNQQZ5F.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etymd",
-  "version": "0.3.1",
+  "version": "0.4.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",

package/dist/scan-BAD2UJAL.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-export { scanProject } from './chunk-HOLFW5QY.js';
-import './chunk-DKC7MLWG.js';
-import './chunk-CRJHIXJH.js';
-import './chunk-YLNQQZ5F.js';