etymd 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# etymd
+
+## 0.1.0 — 2026-07-31
+
+First public release.
+
+The truth guard for agent instruction files — **keep your agent instructions true**. (Formerly
+prototyped as "clothaid", a broader workflow installer; the pivot and its state-of-the-field
+rationale are recorded in `docs/design/003-truth-guard-pivot.md`.)
+
+- `etymd audit` — verify every instruction claim against the actual repo, through three lenses:
+  - **instruction-truth**: command claims vs `package.json` scripts, path claims vs the tree,
+    package-manager consistency, cross-reference integrity, and drift vs the committed baseline —
+    over AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions, Cursor rules, and skills.
+  - **gate-integrity**: the CI ↔ local gate inventory (GitLab incl. `!reference`/includes/
+    script-less jobs, GitHub, husky modern + v3, lint-staged) with honesty rules — advisory jobs
+    are never gates, unseen templates are disclosed, server-side thresholds named as such.
+  - **context-economy**: the always-loaded footprint in words/tokens; extraction candidates.
+  - Ranked findings (risk → gap → polish) with evidence · a **committed ledger** (resolved /
+    regressed / dismissed-never-resurfaces) · lens-coverage reporting · `--fail-on <tier>` for CI.
+- **Excluding a file never resolves its tracked findings.** A finding missing from a scoped run is
+  absent because nobody looked, not because it was fixed. The ledger holds those entries open
+  (`lastSeen` untouched) and the diff reports them as held rather than folding them into
+  "N resolved".
+- **`init` baselines the repo it leaves behind.** It used to approve the scan taken *before* its
+  own scaffold, so the first baseline recorded AGENTS.md and the hooks as absent — and deleting
+  them later never registered as drift, which is the baseline's whole job. It now re-scans after
+  writing.
+- **The committed baseline carries no machine path.** `baseline.json` used to record the scan's
+  absolute root — the approver's username and directory layout — in the one file etymd tells people
+  to commit and therefore publish. The root is now elided on write (`"."`; it is redundant inside
+  the repo it describes). A baseline written by an older etymd is detected and disclosed with the
+  fix: `etymd approve`.
+- **`.etymd/config.json`** (optional, committed) — `instructions.include` / `instructions.exclude`
+  globs scope which instruction files are audited (a fork keeps its own layer honest without
+  auditing inherited upstream skills), and `context.perFileWords` / `context.totalWords` make the
+  economy budgets per-repo. Excluded files are counted and named in the disclosures, and malformed
+  config is disclosed — narrowing an audit can never quietly buy a clean report.
+- `etymd init` — onboarding: approve the committed baseline, gitignore the cache, scaffold a
+  minimal AGENTS.md only where none exists. Never overwrites.
+- `etymd doctor` — alias for `audit --truth`.
+- `etymd context` — the per-file always-loaded footprint view.
+- `etymd gates` — local git-hook gates built from the repo's own check commands (writers can
+  never enter the gate); pairs with the gate-integrity findings.
+- `etymd scan` — the deterministic reckoning (corpus-validated detectors incl. husky v3 and
+  meta-script-proof command classification). `etymd brief` — the agent briefing for the
+  semantic layer.
+- Zero-trace guarantee: read-only probes of foreign repos write nothing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alkis Yuv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# etymd
+
+**Keep your agent instructions true.**
+
+Your `AGENTS.md` is the interface between your team and every coding agent — and it rots silently.
+Scripts get renamed, directories move, rules go stale, and the file keeps instructing agents with
+confidence. etymd continuously **verifies the agent context layer against the actual repo**:
+
+```
+$ etymd audit
+
+  RISK   AGENTS.md tells agents to run `pnpm dev` — no such script exists
+         evidence  AGENTS.md: `pnpm dev` · package.json scripts
+         action    Update the instruction to the current script name.
+
+  GAP    AGENTS.md references `src/legacy/` — it does not exist in the repo
+  GAP    Type checking is enforced only in CI — no local hook runs it
+  GAP    AGENTS.md loads 13,809 words (~18k tokens) into every session
+
+  since last audit: 1 new · 3 still open · 1 resolved · 1 REGRESSED
+```
+
+_From Greek **étymon** — a word's true, original sense (→ etymology) — clipped to **etym.** + the
+**.md** family it guards._
+
+## Why this exists
+
+- Instruction files are now load-bearing: 20+ agents (Claude Code, Codex, Cursor, Copilot,
+  Gemini, …) read `AGENTS.md` natively. A stale claim doesn't error — it silently misleads every
+  session.
+- Linters exist for these files, but they check **a point in time**. Truth is a property **over
+  time**: etymd measures drift against a **committed baseline**, remembers findings in a
+  **ledger** (fixed things stay fixed; a returning problem is named a _regression_, and a finding
+  you dismissed with a reason never resurfaces), and gates CI on it.
+- **Honesty is structural.** Every report declares what it could NOT see — CI jobs inherited from
+  unreadable org templates, server-side quality-gate thresholds, skipped heuristics. No guess is
+  ever dressed as a fact.
+
+## Quick start
+
+```bash
+cd your-project
+npx etymd init          # approve the baseline (+ scaffold AGENTS.md only if you have none)
+npx etymd audit         # verify every instruction claim against the repo
+npx etymd audit --fail-on risk   # the CI gate
+```
+
+Requires Node ≥ 18.17. **Status: pre-publish** — run from a checkout (`npm run build &&
+node dist/cli.js …`) until the first npm release.
+
+## What it checks
+
+**`instruction-truth`** — over `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions,
+`.cursor/rules/*`, `.clinerules`, `.claude/skills/*/SKILL.md`:
+
+- **Command claims** — every `pnpm X` / `npm run X` the files tell agents to run must exist in
+  `package.json` scripts.
+- **Path claims** — every repo path the files point at must exist (conservative heuristics; what's
+  skipped is disclosed). A path the surrounding prose tells the agent to _create_, and an obvious
+  naming stand-in like `my-custom-skill`, are forward-looking instructions, not stale references.
+- **Package-manager consistency** — instructions must not command `yarn` in a `pnpm` repo.
+- **Cross-references** — pointer chains (`CLAUDE.md` → `AGENTS.md` → state docs) must resolve.
+- **Drift vs baseline** — documented commands/artifacts/layout that existed at approval and are
+  now gone.
+
+**`gate-integrity`** — a CI config is a claim too: checks enforced only in CI (failures surface a
+slow pipeline after the agent finished — `etymd gates` generates the local mirror), checks only in
+skippable local hooks, latent gaps (coverage collected but nothing gates on it; commitlint
+installed but unwired). `allow_failure` jobs count as advisory, never as gates.
+
+**`context-economy`** — the always-loaded footprint in words/tokens (only genuinely
+`alwaysApply` Cursor rules count), flagging files worth extracting into on-demand skills. Context
+is the dominant cost of the loop; a lean contract is a correctness feature.
+
+## 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 / pre-push) built from your own check scripts.                                                    |
+| `etymd scan`    | The deterministic reckoning behind everything. `--json`.                                                                                   |
+| `etymd brief`   | A grounded briefing your in-repo agent completes to author the semantic layer.                                                             |
+
+`--cwd <dir>` targets another directory. Read-only probing of any repo leaves **zero trace**
+(`audit --no-ledger` writes nothing).
+
+## The files etymd keeps
+
+| Path                   | Lifecycle     | Role                                             |
+| ---------------------- | ------------- | ------------------------------------------------ |
+| `.etymd/baseline.json` | **committed** | the approved reckoning drift is measured against |
+| `.etymd/ledger.json`   | **committed** | the findings memory: statuses, diffs, dismissals |
+| `.etymd/config.json`   | **committed** | optional: audit scope + context budgets          |
+| `.etymd/cache/`        | gitignored    | transient scan cache                             |
+
+The committed files are written to be publishable: the baseline records `"."` as its scan root, never
+your absolute machine path. Only the gitignored cache keeps the real one.
+
+### `.etymd/config.json` (optional)
+
+Every key is optional; omit the file entirely and the defaults below apply.
+
+```jsonc
+{
+  "instructions": {
+    // Audit these too — files detection would not find on its own.
+    "include": ["design/**/*.md"],
+    // Leave these out. The classic case: a fork that inherits upstream's skills
+    // and will never fix them, but must keep its OWN instruction layer honest.
+    "exclude": [".claude/skills/**"],
+  },
+  "context": {
+    "perFileWords": 4000, // extraction candidate above this
+    "totalWords": 8000, // always-loaded footprint budget
+  },
+}
+```
+
+Globs are repo-relative: `*` within a path segment, `**` across segments, `?` one character. A
+pattern with no wildcard is a **path prefix**, so `.claude/skills` covers everything beneath it.
+
+Narrowing an audit can hide findings, so etymd never lets it happen quietly: **every excluded file
+is counted and named in the lens disclosures**, and a config that fails to parse is reported as a
+disclosure rather than silently falling back to defaults.
+
+## Programmatic use
+
+```ts
+import { runAudit } from "etymd"
+
+const audit = await runAudit(process.cwd(), { persistLedger: false })
+console.log(audit.findings) // one schema: claim · evidence · why · action · effort · confidence
+```
+
+## 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
+repo proved the previous one wrong, and each skip class in the truth lens is a false positive that
+a corpus run caught.
+
+Some corpus entries are private and are named by shape (`nx-monorepo`, `spa-bff`, `cra-legacy`)
+rather than by directory. To run those smokes locally, add an untracked `sources.local.json`
+mapping each name to its sibling directory:
+
+```json
+{ "dirs": { "nx-monorepo": "my-monorepo-checkout" } }
+```
+
+Each value is resolved as a sibling of the etymd checkout.
+
+Without it — on a fresh clone or in CI — those suites skip cleanly and the rest still run.
+
+## Design record & roadmap
+
+[`docs/design/`](docs/design/) — 001 founding · 002 foundation re-lock · **003 the truth-guard
+pivot** (the current identity; includes the state-of-the-field investigation it rests on).
+[`ROADMAP.md`](ROADMAP.md) — what's now / next / later, the pre-publish checklist, and the
+accepted heuristic trade-offs.
+
+## License
+
+MIT

package/dist/approve-WM6OJHQG.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { scanProject, PACK_VERSION } from './chunk-TCWKIMCU.js';
+import { VERSION } from './chunk-U33XLT5I.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-SMM2TW35.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-WVYKYPKS.js';
+
+// src/commands/approve.ts
+async function run(opts) {
+  const prior = await readBaseline(opts.cwd);
+  if (!prior) {
+    throw new Error(
+      "no committed baseline to re-approve \u2014 run `etymd init` to create the first one"
+    );
+  }
+  const facts = await scanProject(opts.cwd);
+  const drift = summarizeBaselineDrift(prior.facts, facts);
+  section(`Re-approving baseline ${theme.dim(`\xB7 ${facts.name} \xB7 ${prior.profile} profile`)}`);
+  if (isDriftEmpty(drift)) {
+    print(`  ${theme.dim("no structural change on the measured axes \u2014 refreshing the stamp only")}`);
+  } else {
+    renderBaselineDrift(drift);
+  }
+  await writeBaseline(opts.cwd, {
+    packVersion: PACK_VERSION,
+    etymdVersion: VERSION,
+    approvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    // A refresh re-blesses the current tree; the profile is a human decision from init — keep it.
+    profile: prior.profile ?? deriveProfile(facts),
+    facts
+  });
+  print();
+  print(
+    `  ${glyph.ok} ${theme.dim("baseline re-approved \u2192")} ${theme.info(".etymd/baseline.json")} ${theme.dim("(commit it \u2014 drift is now measured against this state)")}`
+  );
+}
+
+export { run };

package/dist/audit-OHOSWOWA.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export { run } from './chunk-5D7WNJ6N.js';
+import './chunk-N64ZTBCW.js';
+import './chunk-I566LDX7.js';
+import './chunk-TCWKIMCU.js';
+import './chunk-U33XLT5I.js';
+import './chunk-SMM2TW35.js';
+import './chunk-WVYKYPKS.js';

package/dist/brief-2MPNTITQ.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { scanProject } from './chunk-TCWKIMCU.js';
+import './chunk-U33XLT5I.js';
+import { ETYMD_DIR } from './chunk-SMM2TW35.js';
+import { print, theme } from './chunk-WVYKYPKS.js';
+import { promises } from 'node:fs';
+import path from 'node:path';
+
+async function run(opts) {
+  const facts = await scanProject(opts.cwd);
+  const contents = opts.human ? humanBrief(facts) : agentBrief(facts);
+  const rel = path.join(ETYMD_DIR, opts.human ? "onboarding.md" : "brief.md");
+  const target = path.join(opts.cwd, rel);
+  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.writeFile(target, contents, "utf8");
+  print();
+  print(`  ${theme.dim("wrote")} ${theme.info(rel)}`);
+  if (opts.human) {
+    print(`  ${theme.dim("A human-readable onboarding brief drawn from the reckoning.")}`);
+  } else {
+    print(
+      `  ${theme.dim("Hand this to the agent already in your repo (Claude Code / Cursor / Copilot):")}`
+    );
+    print(
+      `  ${theme.dim('  "Read')} ${theme.info(rel)}${theme.dim(' and complete it against the codebase."')}`
+    );
+    print(
+      `  ${theme.dim("Its answers become the semantic half of AGENTS.md \u2014 you approve before it lands.")}`
+    );
+  }
+}
+function factsSummary(facts) {
+  const dirs = facts.tree.dirs.slice(0, 14).map((d) => `- \`${d.name}/\` (${d.files} files)`).join("\n");
+  return `- Name: ${facts.name}
+- Shape: ${facts.workspace.kind === "none" ? "single package" : `${facts.workspace.kind} workspace`}, ${facts.packageManager}
+- Frameworks: ${facts.frameworks.join(", ") || "unknown"}
+- CI: ${facts.ci.system}
+- Top-level layout:
+${dirs || "- (single package)"}`;
+}
+function agentBrief(facts) {
+  return `# Reckoning brief \u2014 ${facts.name}
+
+You are completing the **semantic half** of this project's operating contract. etymd has already
+gathered the deterministic facts below. Your job is to fill in what only reading the code reveals.
+Ground every answer in real files; cite paths. Do not invent structure. When unsure, say so.
+
+## Facts already known (do not re-derive)
+
+${factsSummary(facts)}
+
+## Produce these sections
+
+1. **What this project is** \u2014 one paragraph: what it does, who uses it, the core domain.
+2. **Composition points** \u2014 the 4\u20138 architectural seams a change usually flows through (entry
+   points, routers, the data-access layer, the shared contract surface). For each: file path +
+   one line on the invariant that must not break when editing it.
+3. **Reuse inventory** \u2014 the existing components/hooks/utils/types a new task most often should
+   reuse instead of writing fresh. Point at where they live.
+4. **Ownership boundaries** \u2014 which directories own which concerns; what must not leak across them.
+5. **Gotchas** \u2014 non-obvious rules, environment traps, or footguns worth a failure-modes entry.
+
+## Output
+
+Write your answer to \`AGENTS.md\` under the matching headings (replace the \`<!-- ... -->\`
+placeholders), or return it for review. The human approves before it becomes the contract.
+`;
+}
+function humanBrief(facts) {
+  return `# Onboarding \u2014 ${facts.name}
+
+A quick orientation generated from the project reckoning.
+
+## At a glance
+
+${factsSummary(facts)}
+
+## Getting started
+
+\`\`\`bash
+${facts.commands.dev ? `${facts.packageManager} ${facts.commands.dev}   # run locally` : "# add the dev command"}
+${facts.commands.test ? `${facts.packageManager} ${facts.commands.test}  # run tests` : ""}
+\`\`\`
+
+## Where to look next
+
+- \`AGENTS.md\` \u2014 the operating contract (stack, rules, repo map, definition of done).
+- \`PROJECT_CONTEXT.md\` \u2014 current state and decisions.
+
+_This is a starting point. Refine it with the domain knowledge only the team has._
+`;
+}
+
+export { run };