etymd 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # etymd
 
+## 0.2.0
+
+### Minor Changes
+
+- a58d3bd: Fleet mode — the truth guard across your repositories (design record `docs/design/004-fleet-truth-guard.md`; registry + fleet `--json` schemas EXPERIMENTAL through 0.2.x).
+
+  - New `state-freshness` truth lens: state/decisions artifacts dated by git committer dates only (never mtime); staleness is relative, so a dormant repo's old state is current; state char budget against the ~10k session-hook truncation; marker-gated decisions format checks (`Scope:`, duplicate/out-of-order `D-NNN` ids, past `Revisit:` dates as due review debt); ADR conventions (`docs/adr/`, `docs/decisions/`, `NNNN-*.md`) recognized natively.
+  - New `etymd fleet` command family. The sweep runs a read-only audit per registered repo (`--manifest` required unless the cwd holds `registry.json` — no env var, no global pointer) and renders one line per project with a delta against `last.fleet.json`; detail only for new or risk findings. `fleet check` validates the manifest pair alone (dangling mappings, duplicate names, privacy leaks, machine paths). `fleet dismiss`/`fleet accept` resolve a project's finding from any cwd.
+  - The manifest loader (`src/core/fleet.ts`) resolves both the fleet registry pair (`registry.json` + gitignored `registry.local.json`) and the legacy corpus pair (`sources.json` + `sources.local.json`); corp entries are opaque aliases resolved only through the local file, and every resolution failure is disclosed, never silently skipped.
+  - Persistence invariants, pinned by tests: the sweep never creates `.etymd` anywhere; `--persist-ledgers` only persists into personal repos that already opted in; corp worktrees take zero writes under every flag combination — corp findings persist (and stay dismissible) at `<manifestDir>/corp/<name>/.etymd/`; zero corp-resolved content under the manifest repo's tracked paths.
+  - Fleet-scope wall findings (lens id `fleet-manifest`): corp contract files inside a corp worktree, unregistered corp-remote checkouts under the fleet root, tracked `/Users/` paths in the manifest's own repo, private needles inside `trust: "public-repo"` entries, corp-host commit emails on personal entries.
+  - Fork-aware freshness: entries with `upstream` are dated on fork-authored commits only (`HEAD --not --remotes=<upstream>`), with a disclosed fallback when the remote is absent.
+
 ## 0.1.0 — 2026-07-31
 
 First public release.
@@ -22,7 +35,7 @@ rationale are recorded in `docs/design/003-truth-guard-pivot.md`.)
   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
+- **`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.

package/README.md

@@ -1,5 +1,8 @@
 # etymd
 
+[![npm version](https://img.shields.io/npm/v/etymd.svg)](https://www.npmjs.com/package/etymd)
+[![CI](https://img.shields.io/github/actions/workflow/status/triartleet/etymd/ci.yml?branch=main&label=CI)](https://github.com/triartleet/etymd/actions/workflows/ci.yml)
+
 **Keep your agent instructions true.**
 
 Your `AGENTS.md` is the interface between your team and every coding agent — and it rots silently.
@@ -45,8 +48,7 @@ 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.
+Requires Node ≥ 18.17. On npm since v0.1.0 — `npx etymd` just works.
 
 ## What it checks
 
@@ -72,17 +74,38 @@ installed but unwired). `allow_failure` jobs count as advisory, never as gates.
 `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.
 
+**`state-freshness`** — the layer that claims "this describes now" (`PROJECT_CONTEXT.md`,
+`DECISIONS.md`, ADR dirs), judged by git committer dates only, never mtime. Staleness is
+_relative_ — a state doc is stale only when the repo moved past it, so a dormant repo's old
+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
+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.
+
+**`fleet-manifest`** (via `etymd fleet`) — one truth guard across every repo you registered:
+per-repo audits plus checks on the fleet manifest itself and on the placement wall between
+personal and employer repos. See [the fleet manifest](#the-fleet-manifest-experimental) below.
+
 ## 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.                                                             |
+| 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.                                                                                                         |
+| `etymd approve`                  | Refresh the committed baseline non-interactively after intentional structural changes.                                                                                                 |
+| `etymd ledger`                   | The findings memory: every tracked finding with status and history.                                                                                                                    |
+| `etymd dismiss`                  | `dismiss <id> --reason <text>` — a dismissed finding never resurfaces without regressing.                                                                                              |
+| `etymd accept`                   | `accept <id>` — record a finding as accepted reality; visible in the ledger, out of the report.                                                                                        |
+| `etymd fleet`                    | Sweep every project in a fleet manifest: read-only per-repo audits + manifest/wall checks. `--manifest`, `--only`, `--profile`, `--truth`, `--persist-ledgers`, `--json`, `--fail-on`. |
+| `etymd fleet check`              | Validate the manifest pair alone (no lenses): dangling mappings, duplicate names, privacy leaks, machine paths. Non-zero exit on any finding.                                          |
+| `etymd fleet dismiss` / `accept` | `<name> <id>` — resolve a project's finding from any cwd; corp findings persist beside the manifest, never in the corp worktree.                                                       |
 
 `--cwd <dir>` targets another directory. Read-only probing of any repo leaves **zero trace**
 (`audit --no-ledger` writes nothing).
@@ -126,6 +149,81 @@ Narrowing an audit can hide findings, so etymd never lets it happen quietly: **e
 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.
 
+## The fleet manifest (EXPERIMENTAL)
+
+`etymd fleet` extends the one objective across every repository you work in — your fleet of
+**repositories**, not a fleet of agents. The manifest, `registry.json`, is itself an
+agent-context file: claims about your fleet (what exists, where, under which profile). It rots
+like any AGENTS.md does, and `etymd fleet` keeps it true. Design record:
+[`docs/design/004-fleet-truth-guard.md`](docs/design/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:
+
+`registry.json` (tracked; safe to publish by construction):
+
+```jsonc
+{
+  "registryVersion": 1,
+  "root": "~/projects", // ~ expands on the consumer side — never a machine home
+  "projects": [
+    { "name": "web-app", "kind": "repo", "profile": "personal", "path": "web-app" },
+    {
+      "name": "notes",
+      "kind": "docs",
+      "profile": "personal",
+      "path": "notes",
+      "staleAfterDays": 45, // per-entry freshness window
+      "contract": { "state": "STATUS.md" }, // native conventions register, never migrate
+    },
+    {
+      "name": "my-fork",
+      "kind": "tool",
+      "profile": "personal",
+      "path": "my-fork",
+      "upstream": "origin", // freshness measured on fork-authored commits only
+      "trust": "public-repo", // hygiene needles apply (see below)
+    },
+    // Corp entries: opaque alias, private, NO path — real dirs live only in the local file.
+    { "name": "c-one", "kind": "repo", "profile": "corp", "private": true, "staleAfterDays": 45 },
+  ],
+}
+```
+
+`registry.local.json` (gitignored; this machine's facts — each one an identifier you don't ship):
+
+```jsonc
+{
+  "machineProfile": "corp", // "personal" resolves corp entries disclosed-absent
+  "root": "~/projects", // optional per-machine root override
+  "dirs": { "c-one": "~/projects/real-corp-dir" },
+  "labels": { "c-one": "real-corp-dir" },
+  "corpHosts": ["git.example-corp.com"],
+}
+```
+
+How the sweep behaves:
+
+- **Read-only by default, everywhere.** The sweep never creates `.etymd` anywhere.
+  `--persist-ledgers` persists only into personal repos that already opted in, and a **corp
+  worktree is never written** — regardless of flags, even if a stray `.etymd` exists inside it
+  (pinned by test). Corp findings stay dismissible: their ledger lives at
+  `<manifest-dir>/corp/<name>/.etymd/`, beside the manifest.
+- **Deltas.** Each sweep compares against `last.fleet.json` stored beside the manifest and
+  renders `Δ +new −resolved` per project. Add `*.fleet.json` to the manifest repo's
+  `.gitignore` — sweep output is local-only and never tracked.
+- **Wall checks.** Corp contract files found inside a corp worktree, unregistered checkouts
+  under the fleet root whose remotes match `corpHosts`, tracked `/Users/` paths in the manifest
+  repo, private needles (labels, dir names, hosts) inside `trust: "public-repo"` entries, and
+  corp-host commit emails on personal entries — each a risk finding; each check that cannot run
+  is disclosed.
+- **No global pointer.** `--manifest` is required unless the cwd holds `registry.json` — there
+  is deliberately no env var and no home-directory pointer.
+
+Interop note: if a repo's Prettier (or similar formatter) checks JSON, add `.etymd` to its
+`.prettierignore` — etymd writes its own JSON style, and a format gate fighting the ledger is
+noise (this repo does exactly that).
+
 ## Programmatic use
 
 ```ts
@@ -157,7 +255,8 @@ Without it — on a fresh clone or in CI — those suites skip cleanly and the r
 ## 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).
+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
 accepted heuristic trade-offs.
 

package/dist/{approve-WM6OJHQG.js → approve-EJJDCNYV.js}

@@ -1,8 +1,8 @@
 #!/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';
+import { scanProject, PACK_VERSION } from './chunk-WNMA2FYM.js';
+import { VERSION } from './chunk-JQHGV74L.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-DJ2DDFDK.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-ASKJFMSX.js';
 
 // src/commands/approve.ts
 async function run(opts) {

package/dist/audit-ATHB6FHN.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export { run } from './chunk-3WOORFOW.js';
+import './chunk-XGH2DTW4.js';
+import './chunk-XW5XQN23.js';
+import './chunk-3LBIBVX3.js';
+import './chunk-WNMA2FYM.js';
+import './chunk-JQHGV74L.js';
+import './chunk-DJ2DDFDK.js';
+import './chunk-ASKJFMSX.js';

package/dist/{brief-2MPNTITQ.js → brief-GFR3YOZT.js}

@@ -1,8 +1,8 @@
 #!/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 { scanProject } from './chunk-WNMA2FYM.js';
+import './chunk-JQHGV74L.js';
+import { ETYMD_DIR } from './chunk-DJ2DDFDK.js';
+import { print, theme } from './chunk-ASKJFMSX.js';
 import { promises } from 'node:fs';
 import path from 'node:path';
 

package/dist/{chunk-I566LDX7.js → chunk-3LBIBVX3.js}

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { ETYMD_DIR } from './chunk-SMM2TW35.js';
-import { pathExists, readText, wordCount, approxTokens } from './chunk-WVYKYPKS.js';
+import { ETYMD_DIR } from './chunk-DJ2DDFDK.js';
+import { pathExists, readText, wordCount, approxTokens } from './chunk-ASKJFMSX.js';
 import path2 from 'node:path';
 import { promises } from 'node:fs';
 
 var CONFIG_FILE = path2.join(ETYMD_DIR, "config.json");
 var DEFAULT_CONFIG = {
   instructions: { include: [], exclude: [] },
-  context: { perFileWords: 4e3, totalWords: 8e3 }
+  context: { perFileWords: 4e3, totalWords: 8e3 },
+  state: { staleAfterDays: 30, maxChars: 9500 }
 };
 function configPath(root) {
   return path2.join(root, CONFIG_FILE);
@@ -51,6 +52,7 @@ async function readConfig(root) {
   const obj = parsed;
   const instructions = obj.instructions ?? {};
   const context = obj.context ?? {};
+  const state = obj.state ?? {};
   return {
     present: true,
     problems,
@@ -62,12 +64,17 @@ async function readConfig(root) {
       context: {
         perFileWords: readBudget(context.perFileWords, "context.perFileWords", problems) ?? DEFAULT_CONFIG.context.perFileWords,
         totalWords: readBudget(context.totalWords, "context.totalWords", problems) ?? DEFAULT_CONFIG.context.totalWords
+      },
+      state: {
+        staleAfterDays: readBudget(state.staleAfterDays, "state.staleAfterDays", problems) ?? DEFAULT_CONFIG.state.staleAfterDays,
+        maxChars: readBudget(state.maxChars, "state.maxChars", problems) ?? DEFAULT_CONFIG.state.maxChars
       }
     }
   };
 }
 var ALWAYS_LOADED = [
   { path: "AGENTS.md", role: "operating contract" },
+  { path: "PROJECT_CONTEXT.md", role: "ground-truth state" },
   { path: "CLAUDE.md", role: "Claude Code pointer" },
   { path: "GEMINI.md", role: "Gemini pointer" },
   { path: ".github/copilot-instructions.md", role: "Copilot instructions" },

package/dist/chunk-3WOORFOW.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-XGH2DTW4.js';
+import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-ASKJFMSX.js';
+
+// src/commands/audit.ts
+async function run(opts) {
+  const failOn = opts.failOn === void 0 ? void 0 : parseFailOnTier(opts.failOn);
+  const result = await runAudit(opts.cwd, {
+    kind: opts.truth ? "truth" : void 0,
+    lensIds: opts.lens ? [opts.lens] : void 0,
+    persistLedger: !opts.noLedger
+  });
+  if (failOn && meetsFailOn(result.findings, failOn)) {
+    process.exitCode = 1;
+  }
+  if (opts.json) {
+    print(
+      JSON.stringify(
+        {
+          profile: result.profile,
+          baseline: result.baseline ? { packVersion: result.baseline.packVersion, approvedAt: result.baseline.approvedAt } : null,
+          reports: result.reports.map(({ findings: _findings, ...r }) => r),
+          findings: result.findings,
+          diff: {
+            new: result.diff.new.map((f) => f.id),
+            stillOpen: result.diff.stillOpen.map((f) => f.id),
+            regressed: result.diff.regressed.map((f) => f.id),
+            resolved: result.diff.resolved.map((e) => e.id),
+            dismissed: result.diff.dismissed.map((f) => f.id),
+            accepted: result.diff.accepted.map((f) => f.id)
+          }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  section(
+    `${opts.truth ? "Doctor \u2014 is this still true?" : "Audit"} ${theme.dim(`\xB7 ${result.facts.name} \xB7 ${result.profile} profile`)}`
+  );
+  if (!result.baseline && !opts.truth) {
+    print(
+      `  ${theme.dim("no committed baseline \u2014 run `etymd init` to approve one; drift checks are limited")}`
+    );
+  }
+  renderLensCoverage(result.reports);
+  section(`Findings ${theme.dim("(ranked: risk \u2192 gap \u2192 polish, cheapest first)")}`);
+  renderFindings(result.findings);
+  renderLedgerDiff(result.diff);
+  const top = result.findings[0];
+  if (top) {
+    print();
+    print(
+      `  ${theme.dim("next:")} ${theme.heading(top.claim)}${top.action ? theme.dim(` \u2014 ${top.action}`) : ""}`
+    );
+  }
+}
+
+export { run };

package/dist/{chunk-WVYKYPKS.js → chunk-ASKJFMSX.js}

@@ -280,6 +280,33 @@ function renderLedgerDiff(diff) {
     print(`  ${theme.dim("since last audit:")} ${parts.join(theme.dim(" \xB7 "))}`);
   }
 }
+function renderFleetRows(rows) {
+  if (!rows.length) {
+    print(`  ${theme.dim("no entries matched \u2014 nothing swept")}`);
+    return;
+  }
+  const nameWidth = maxWidth(rows.map((r) => r.name));
+  const ageWidth = maxWidth(rows.map((r) => r.age));
+  const countStr = (c) => c.risk + c.gap + c.polish === 0 ? theme.ok("clean") : [
+    c.risk ? theme.bad(`${c.risk} risk`) : "",
+    c.gap ? theme.warn(`${c.gap} gap`) : "",
+    c.polish ? theme.dim(`${c.polish} polish`) : ""
+  ].filter(Boolean).join(theme.dim(" \xB7 "));
+  const countsWidth = maxWidth(rows.filter((r) => !r.note).map((r) => countStr(r.counts)));
+  for (const r of rows) {
+    if (r.note) {
+      print(`  ${pad(theme.info(r.name), nameWidth)}  ${glyph.bad} ${theme.dim(r.note)}`);
+      continue;
+    }
+    print(
+      `  ${pad(theme.info(r.name), nameWidth)}  ${pad(theme.dim(r.age), ageWidth)}  ${pad(countStr(r.counts), countsWidth)}  ${theme.dim(r.delta)}`
+    );
+  }
+}
+function renderFleetNotes(problems, disclosures) {
+  for (const p of problems) print(`  ${glyph.bad} ${theme.bad(p)}`);
+  for (const d of disclosures) print(`  ${theme.dim(`\u25E6 ${d}`)}`);
+}
 var STATUS_ORDER = ["regressed", "open", "accepted", "dismissed", "done"];
 var STATUS_LABEL = {
   regressed: theme.bad,
@@ -329,4 +356,4 @@ function renderLedger(ledger) {
   }
 }
 
-export { approxTokens, git, glyph, isCiEnvironment, isDirectory, matchesAnyGlob, normalizeRelPath, pathExists, print, readJson, readText, renderBaselineDrift, renderContext, renderFacts, renderFindings, renderLedger, renderLedgerDiff, renderLensCoverage, renderPlan, section, theme, wordCount };
+export { approxTokens, git, glyph, isCiEnvironment, isDirectory, matchesAnyGlob, normalizeRelPath, pathExists, print, readJson, readText, renderBaselineDrift, renderContext, renderFacts, renderFindings, renderFleetNotes, renderFleetRows, renderLedger, renderLedgerDiff, renderLensCoverage, renderPlan, section, theme, wordCount };

package/dist/{ledger-YFTYCOIC.js → chunk-B4FYQE7S.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readLedger, resolveEntry, writeLedger } from './chunk-N64ZTBCW.js';
-import { print, renderLedger, glyph, theme } from './chunk-WVYKYPKS.js';
+import { readLedger, resolveEntry, writeLedger } from './chunk-XW5XQN23.js';
+import { print, renderLedger, glyph, theme } from './chunk-ASKJFMSX.js';
 
 // src/commands/ledger.ts
 async function list(opts) {

package/dist/{chunk-SMM2TW35.js → chunk-DJ2DDFDK.js}

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

package/dist/{chunk-U33XLT5I.js → chunk-JQHGV74L.js}

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

package/dist/{chunk-TCWKIMCU.js → chunk-WNMA2FYM.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-U33XLT5I.js';
-import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-WVYKYPKS.js';
+import { VERSION } from './chunk-JQHGV74L.js';
+import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-ASKJFMSX.js';
 import path from 'node:path';
 import { promises } from 'node:fs';
 
@@ -334,6 +334,19 @@ var ARTIFACT_SPECS = [
     path: "PROJECT_CONTEXT.md",
     kind: "state"
   },
+  {
+    id: "decisions",
+    label: "DECISIONS.md (decision record)",
+    path: "DECISIONS.md",
+    kind: "decisions"
+  },
+  { id: "adr-dir", label: "ADR directory (docs/adr)", path: "docs/adr", kind: "decisions" },
+  {
+    id: "decisions-dir",
+    label: "ADR directory (docs/decisions)",
+    path: "docs/decisions",
+    kind: "decisions"
+  },
   { id: "claude", label: "CLAUDE.md (Claude Code pointer)", path: "CLAUDE.md", kind: "adapter" },
   {
     id: "copilot",
@@ -379,12 +392,25 @@ var ARTIFACT_SPECS = [
   }
 ];
 async function detectArtifacts(root) {
-  return Promise.all(
+  const artifacts = await Promise.all(
     ARTIFACT_SPECS.map(async (spec) => ({
       ...spec,
       exists: await pathExists(path.join(root, spec.path))
     }))
   );
+  let adrFiles = false;
+  try {
+    adrFiles = (await promises.readdir(path.join(root, "docs"))).some((f) => /^\d{4}-.+\.md$/.test(f));
+  } catch {
+  }
+  artifacts.push({
+    id: "adr-files",
+    label: "ADR files (docs/NNNN-*.md)",
+    path: "docs",
+    kind: "decisions",
+    exists: adrFiles
+  });
+  return artifacts;
 }
 async function walkTree(root) {
   const state = { budget: 2e4, truncated: false };
@@ -449,7 +475,50 @@ function inferTicketKey(subjects) {
   }
   return bestCount >= 3 ? best : void 0;
 }
-async function scanProject(root) {
+async function collectFreshness(abs, isRepo, artifacts, upstreamRemote) {
+  const dated = artifacts.filter((a) => a.exists && (a.kind === "state" || a.kind === "decisions"));
+  const allUnverifiable = (reason) => ({
+    artifacts: [],
+    unverifiable: dated.map((a) => ({ path: a.path, reason }))
+  });
+  if (!isRepo) return allUnverifiable("not a git repository \u2014 no committer dates to read");
+  if (await git(abs, ["rev-parse", "--is-shallow-repository"]) === "true") {
+    return allUnverifiable("shallow clone \u2014 history is incomplete, committer dates would lie");
+  }
+  const repoLastCommit = upstreamRemote ? await git(abs, ["log", "-1", "--format=%cI", "HEAD", "--not", `--remotes=${upstreamRemote}`]) : await git(abs, ["log", "-1", "--format=%cI"]);
+  if (!repoLastCommit) {
+    if (upstreamRemote) {
+      return allUnverifiable(
+        `no fork-authored commits \u2014 every commit is reachable from \`${upstreamRemote}\`, the fork has not moved`
+      );
+    }
+    return allUnverifiable("repository has no commits yet");
+  }
+  const dirtyRaw = await git(abs, ["diff", "--name-only", "HEAD"]);
+  const dirtyPaths = dirtyRaw ? dirtyRaw.split("\n").filter(Boolean) : [];
+  const isDirty = (p) => dirtyPaths.some((d) => d === p || d.startsWith(`${p}/`));
+  const facts = { repoLastCommit, artifacts: [], unverifiable: [] };
+  await Promise.all(
+    dated.map(async (a) => {
+      const lastCommit = await git(abs, ["log", "-1", "--format=%cI", "--", a.path]);
+      if (!lastCommit) {
+        facts.unverifiable.push({ path: a.path, reason: "untracked \u2014 never committed" });
+        return;
+      }
+      facts.artifacts.push({
+        artifactId: a.id,
+        path: a.path,
+        lastCommit,
+        commitsSince: Date.parse(repoLastCommit) > Date.parse(lastCommit),
+        ...isDirty(a.path) ? { dirty: true } : {}
+      });
+    })
+  );
+  facts.artifacts.sort((x, y) => x.path.localeCompare(y.path));
+  facts.unverifiable.sort((x, y) => x.path.localeCompare(y.path));
+  return facts;
+}
+async function scanProject(root, opts = {}) {
   const abs = path.resolve(root);
   const rootPkg = await readJson(path.join(abs, "package.json"));
   const [packageManager, workspace, ci, artifacts, tree, isRepo] = await Promise.all([
@@ -469,6 +538,7 @@ async function scanProject(root) {
   ]) : [null, null, null, null, null];
   const hooksPath = hooksPathRaw ?? void 0;
   const hooks = await detectHooks(abs, hooksPath, rootPkg);
+  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;
   return {
@@ -495,6 +565,7 @@ async function scanProject(root) {
     ci,
     hooks,
     artifacts,
+    freshness,
     tree
   };
 }

package/dist/{chunk-FXL4554F.js → chunk-WQXMJUIA.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { PACK_VERSION } from './chunk-TCWKIMCU.js';
-import { pathExists, readText } from './chunk-WVYKYPKS.js';
+import { PACK_VERSION } from './chunk-WNMA2FYM.js';
+import { pathExists, readText } from './chunk-ASKJFMSX.js';
 import { promises } from 'node:fs';
 import path from 'node:path';