etymd 0.14.0 → 0.15.0

package/dist/{chunk-HWC6PKJM.js → chunk-Y6RZRED3.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-623W6KVC.js';
+import { VERSION } from './chunk-DBWDMIYO.js';
 import { PACK_VERSION } from './chunk-YQZDYDAK.js';
 import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-4VPBP6K6.js';
 import path from 'path';

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-623W6KVC.js';
+import { VERSION } from './chunk-DBWDMIYO.js';
 import path from 'path';
 import { Command } from 'commander';
 import pc from 'picocolors';
@@ -21,7 +21,7 @@ ${pc.red("\u2716")} ${message}
 }
 var program = new Command();
 program.name("etymd").description(
-  "Keep your agent instructions true \u2014 verify AGENTS.md & friends against the actual repo, on a budget, with drift caught over time."
+  "Keep your agent instructions true \u2014 verify AGENTS.md & friends, and the task you hand an agent, against the actual repo, on a budget, with drift caught over time."
 ).version(VERSION, "-v, --version").option("--cwd <dir>", "run against a different project directory", process.cwd());
 program.command("audit").description("Verify every instruction claim against the repo: ranked findings + ledger diff").option("--json", "print the machine-stable audit result as JSON").option("--truth", "truth lenses only (the doctor subset)").option(
   "--lens <id>",
@@ -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-42OHF7ON.js');
+    const { run } = await import('./audit-YSALDC2L.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 asked").option("-y, --yes", "accept defaults without prompting (never overwrites)").option("--with-agents", "also scaffold a minimal AGENTS.md where none exists (off by default)").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./init-AHA7VRRI.js');
+    const { run } = await import('./init-H57H2JBE.js');
     await run({ cwd: resolveCwd(cmd), yes: opts.yes, withAgents: opts.withAgents });
   })
 );
@@ -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-QDOH2E7V.js');
+    const { run } = await import('./approve-MA4Z3TBT.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-TVX3FKK4.js');
+    const { run } = await import('./scan-XBOHDXAH.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-CE5SD4JW.js');
+    const { run } = await import('./doctor-Y3DWDEBT.js');
     await run({ cwd: resolveCwd(cmd), json: opts.json });
   })
 );
@@ -76,10 +76,31 @@ 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-ZUQK3CFL.js');
+    const { run } = await import('./brief-DPZYSAMC.js');
     await run({ cwd: resolveCwd(cmd), human: opts.human });
   })
 );
+program.command("premise").argument("[task]", "the task you are about to hand an agent, quoted").description(
+  "Before acting on a task: verify what it names against the repo, then brief the agent on what only it can verify"
+).option(
+  "--file <path>",
+  "read the task from a file (a plan, an issue, a prompt); `-` reads stdin"
+).option("--json", "print the machine-stable result as JSON (schema premise/1)").option("--no-brief", "do not write or print the agent brief").option(
+  "--fail-on <tier>",
+  "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
+).action(
+  (task, opts, cmd) => action(async () => {
+    const { run } = await import('./premise-VMC3UUIB.js');
+    await run({
+      cwd: resolveCwd(cmd),
+      task,
+      file: opts.file,
+      json: opts.json,
+      brief: opts.brief,
+      failOn: opts.failOn
+    });
+  })
+);
 program.command("ledger").description("List every tracked finding grouped by status (open \xB7 accepted \xB7 dismissed \xB7 \u2026)").option("--json", "print the raw ledger as JSON").action(
   (opts, cmd) => action(async () => {
     const { list } = await import('./ledger-T54JDHGP.js');
@@ -111,7 +132,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-F3XDEDCV.js');
+    const { sweep } = await import('./fleet-4FYZ3GBK.js');
     await sweep({
       cwd: resolveCwd(cmd),
       manifest: opts.manifest,
@@ -126,7 +147,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-F3XDEDCV.js');
+    const { check } = await import('./fleet-4FYZ3GBK.js');
     const opts = cmd.optsWithGlobals();
     await check({ cwd: resolveCwd(cmd), manifest: opts.manifest, json: opts.json });
   })
@@ -136,7 +157,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-F3XDEDCV.js');
+    const { add } = await import('./fleet-4FYZ3GBK.js');
     const shared = cmd.optsWithGlobals();
     await add({
       cwd: resolveCwd(cmd),
@@ -159,7 +180,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-F3XDEDCV.js');
+    const { dismiss } = await import('./fleet-4FYZ3GBK.js');
     const opts = cmd.optsWithGlobals();
     await dismiss({
       cwd: resolveCwd(cmd),
@@ -174,7 +195,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-F3XDEDCV.js');
+    const { accept } = await import('./fleet-4FYZ3GBK.js');
     const opts = cmd.optsWithGlobals();
     await accept({ cwd: resolveCwd(cmd), manifest: opts.manifest, name, id, reason: opts.reason });
   })
@@ -200,7 +221,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-F4YPKWJR.js');
+    const { run } = await import('./gates-IBQ7HCAN.js');
     await run({ cwd: resolveCwd(cmd), ci: opts.ci, yes: opts.yes });
   })
 );

package/dist/{doctor-CE5SD4JW.js → doctor-Y3DWDEBT.js}

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { run } from './chunk-PAMWS665.js';
-import './chunk-LT7JMVV3.js';
+import { run } from './chunk-CEO3BXQB.js';
+import './chunk-2RNQ6OLV.js';
+import './chunk-IWG77WV3.js';
 import './chunk-3E2IPCRY.js';
 import './chunk-HI7NWPRA.js';
-import './chunk-HWC6PKJM.js';
-import './chunk-623W6KVC.js';
+import './chunk-Y6RZRED3.js';
+import './chunk-DBWDMIYO.js';
 import './chunk-P6ATKV2R.js';
 import './chunk-YQZDYDAK.js';
 import './chunk-4VPBP6K6.js';

package/dist/{fleet-F3XDEDCV.js → fleet-4FYZ3GBK.js}

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { dismiss, accept } from './chunk-HOR4M6EC.js';
-import { parseFailOnTier, meetsFailOn, runAudit } from './chunk-LT7JMVV3.js';
+import { runAudit } from './chunk-2RNQ6OLV.js';
+import { parseFailOnTier, meetsFailOn } from './chunk-IWG77WV3.js';
 import { readLedger } from './chunk-3E2IPCRY.js';
 import { print, theme, section, renderFleetRows, renderFleetNotes, renderFindings, TIER_BADGE, glyph } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-HWC6PKJM.js';
-import './chunk-623W6KVC.js';
+import { scanProject } from './chunk-Y6RZRED3.js';
+import './chunk-DBWDMIYO.js';
 import { DEFAULT_CONFIG, ETYMD_DIR } from './chunk-P6ATKV2R.js';
 import './chunk-YQZDYDAK.js';
 import { readText, pathExists, git, isDirectory } from './chunk-4VPBP6K6.js';
@@ -686,7 +687,7 @@ async function checkCorpEmails(manifest, findings, disclosures) {
 }
 async function checkGateDrift(manifest, findings, disclosures) {
   const { planWorkflow } = await import('./generate-KEX75XNG.js');
-  const { scanProject: scanProject2 } = await import('./scan-QRTH6HAP.js');
+  const { scanProject: scanProject2 } = await import('./scan-W4US23MU.js');
   const { readConfig } = await import('./config-724Y3IOB.js');
   for (const entry of manifest.entries) {
     const root = entry.resolvedRoot;

package/dist/{gates-F4YPKWJR.js → gates-IBQ7HCAN.js}

@@ -2,8 +2,8 @@
 import { applyFiles } from './chunk-GWGKEPRX.js';
 import { deriveFailOn, derivedCommands, planWorkflow, runPrefix, isSafeGateCommand } from './chunk-UFNETE6P.js';
 import { section, print, glyph, theme, renderPlan } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-HWC6PKJM.js';
-import './chunk-623W6KVC.js';
+import { scanProject } from './chunk-Y6RZRED3.js';
+import './chunk-DBWDMIYO.js';
 import { readConfig, CONFIG_FILE, configPath } from './chunk-P6ATKV2R.js';
 import './chunk-YQZDYDAK.js';
 import { readText, git } from './chunk-4VPBP6K6.js';

package/dist/index.d.ts

@@ -686,6 +686,169 @@ declare function sweepFleet(manifest: FleetManifest, opts?: FleetSweepOptions):
  */
 declare const instructionTruthLens: Lens;
 
+/** Everything a truth check needs from the repo, resolved once per run. */
+interface TruthEnv {
+    root: string;
+    facts: ProjectFacts;
+    /** Package scripts across the root and every workspace manifest. */
+    knownScripts: Set<string>;
+    nodeModulesInstalled: boolean;
+    /** A manifest exists somewhere, so a script claim is checkable even without an install. */
+    manifestExists: boolean;
+    /** The root plus every workspace package dir — where claims are resolved. */
+    bases: string[];
+    /** A repo-relative claim resolves in the root, any workspace package, or their src/ scripts/. */
+    pathResolves(claim: string): Promise<boolean>;
+    /** `yarn X` / `pnpm X` may legitimately run an installed node_modules/.bin binary. */
+    binResolves(name: string): Promise<boolean>;
+}
+declare function buildTruthEnv(root: string, facts: ProjectFacts): Promise<TruthEnv>;
+/** Skip-class tallies — every class a check declines to accuse is counted, then disclosed. */
+interface ClaimCounters {
+    filteredSkipped: number;
+    tildeSkipped: number;
+    binaryResolved: number;
+    unverifiableCommands: number;
+    gitignoredSkipped: number;
+    prospectiveSkipped: number;
+    placeholderSkipped: number;
+    /** Decision references naming another record (a fleet-level ledger) — not this repo's. */
+    qualifiedRefsSkipped: number;
+    /** Decision references with no `## D-NNN` ledger to resolve against. */
+    unresolvableRefs: number;
+}
+declare function emptyCounters(): ClaimCounters;
+/**
+ * One thing a check looked for, and what it found. `null` = could not be checked from the repo
+ * (counted and disclosed), never a guess. The honest-coverage half of a report: what was
+ * examined, not only what failed.
+ */
+interface ExaminedClaim {
+    kind: "script" | "path" | "doc" | "decision";
+    value: string;
+    exists: boolean | null;
+}
+/** A piece of text making claims about the repo: an instruction file, a state doc, a task. */
+interface ClaimText {
+    /** Repo-relative path, or a label such as `task` — becomes part of every finding id. */
+    path: string;
+    text: string;
+}
+interface TextClaimsOptions {
+    /** The lens the findings report under (`instruction-truth`, `premise`). */
+    lensId: string;
+    /** How the text is named in a claim sentence — a file path, or "The task". */
+    subject?: string;
+    /**
+     * A missing path is `gap` for an instruction file (a dead reference among many) and `risk` for
+     * a task (the task is ABOUT the path — an agent acting on it does the wrong thing).
+     */
+    missingPathTier: FindingTier;
+    maxPathFindings: number;
+    whyCommand?: string;
+    actionCommand?: string;
+    whyPath?: string;
+    actionPath?: string;
+}
+interface TextClaimsResult {
+    findings: Finding[];
+    disclosures: string[];
+    /** Every script and path claim the text made, found or not. */
+    examined: ExaminedClaim[];
+}
+/**
+ * Command and path claims in one text, verified against the repo. Precision over recall: every
+ * class it declines to accuse is counted in `counters` for the caller to disclose.
+ */
+declare function checkTextClaims(env: TruthEnv, file: ClaimText, opts: TextClaimsOptions, counters: ClaimCounters): Promise<TextClaimsResult>;
+interface RefsResult {
+    findings: Finding[];
+    examined: ExaminedClaim[];
+}
+/** Cross-references to well-known docs (AGENTS.md, CLAUDE.md, …) must resolve to real files. */
+declare function checkDocRefs(env: TruthEnv, file: ClaimText, lensId: string, counters: ClaimCounters, subject?: string): Promise<RefsResult>;
+/** The repo's own decision record: every `## D-NNN` id, and which files carried them. */
+interface DecisionLedger {
+    /** Null when no decisions file with parseable `## D-NNN` entries exists. */
+    ids: Set<number> | null;
+    sources: string[];
+}
+declare function loadDecisionLedger(root: string, facts: ProjectFacts): Promise<DecisionLedger>;
+interface DecisionRefsOptions {
+    lensId: string;
+    /** How the text is named in a claim sentence — a file path, or "The task". */
+    subject?: string;
+    why?: string;
+    action?: string;
+}
+/**
+ * `D-NNN` references in one text, resolved against the repo's own decision record. A citation
+ * the record cannot back is stale in a way age cannot reveal. Qualified refs (another record's)
+ * and refs with no ledger to resolve against are counted, never accused.
+ */
+declare function checkDecisionRefs(file: ClaimText, ledger: DecisionLedger, opts: DecisionRefsOptions, counters: ClaimCounters): RefsResult;
+
+declare const PREMISE_LENS = "premise";
+declare const PREMISE_BRIEF_FILE: string;
+/** One thing the task named, found or not — the checked half of the brief. */
+type PremiseEntity = ExaminedClaim;
+interface PremiseResult {
+    /** The `--json` schema version. */
+    schema: "premise/1";
+    task: string;
+    /** Where the task came from: `argument`, `stdin`, or the file path it was read from. */
+    source: string;
+    /** The project name from the reckoning. */
+    name: string;
+    findings: Finding[];
+    disclosures: string[];
+    /** Everything the task named that etymd could look for — found or not. */
+    entities: PremiseEntity[];
+    brief: string;
+    /** Repo-relative path the brief was written to, or `null` when the repo never opted in. */
+    briefPath: string | null;
+}
+interface PremiseOptions {
+    root: string;
+    task: string;
+    source?: string;
+    /** Write the brief under `.etymd/` when that directory exists (default true). */
+    writeBrief?: boolean;
+}
+/** What the prose promotion declined to read as a claim — counted, then disclosed. */
+interface PromotionSkips {
+    /** `pnpm X` / `yarn X` / `bun X` in prose without `run` — a phrase as often as an invocation. */
+    bareInvocations: number;
+    /** `… run the`, `… run X` — a function word or a one-letter stand-in where a script would be. */
+    proseScripts: number;
+    /** `github.com/org/repo/…` — a scheme-less URL, not a repo path. */
+    hostnameLike: number;
+    /** `input/output/` — a slash-joined phrase whose first segment is no directory here. */
+    unrootedDirs: number;
+}
+interface PromotionContext {
+    /** Directory names that exist at the root, in a workspace package, or under their src/ scripts/. */
+    rootedDirs: ReadonlySet<string>;
+}
+interface PromotedText {
+    text: string;
+    skips: PromotionSkips;
+}
+/**
+ * People do not backtick paths in a prompt. Promote the bare mentions the claim extractors would
+ * otherwise treat as prose — `src/x.ts`, `docs/design/`, `npm run lint` — into code spans, leaving
+ * anything already in a code span untouched. Precision over recall: only what an instruction
+ * file's extractor would accept is promoted, and every class left as prose is counted.
+ */
+declare function promoteBareTokens(text: string, ctx: PromotionContext): PromotedText;
+declare function runPremise(opts: PremiseOptions): Promise<PremiseResult>;
+/**
+ * The half of the premise check only an agent can do, written as a brief it reads before acting.
+ * Deterministic: it lists what etymd verified and hands over the three questions reading files
+ * cannot answer. It never speculates about what the task "really" means.
+ */
+declare function renderBrief(task: string, findings: Finding[], entities: PremiseEntity[]): string;
+
 interface InstructionFile {
     /** Repo-relative path. */
     path: string;
@@ -825,4 +988,4 @@ declare const PACK_VERSION = "12";
 declare const VERSION: string;
 declare const NAME: string;
 
-export { type ApplyResult, type ArtifactFreshness, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ContextBudget, type ContextBudgets, type ContextFile, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, FLEET_JSON_SCHEMA, FLEET_LENS, type Finding, type FleetContract, type FleetEntry, type FleetManifest, type FleetProfile, type FleetProjectSweep, type FleetSweepOptions, type FleetSweepResult, type FreshnessFacts, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, type ManifestProblem, NAME, PACK_VERSION, type PackageManager, type PathClaims, type PlanOptions, type ProjectFacts, type StateBudgets, TOTAL_BUDGET_WORDS, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, checkManifest, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadFleetManifest, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };
+export { type ApplyResult, type ArtifactFreshness, type AuditOptions, type AuditResult, type Baseline, CONFIG_FILE, type ClaimCounters, type ClaimText, type ContextBudget, type ContextBudgets, type ContextFile, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, type DecisionLedger, type DecisionRefsOptions, type DetectedArtifact, type DiscoveredCommands, EXTRACTION_THRESHOLD, type EtymdConfig, type ExaminedClaim, FLEET_JSON_SCHEMA, FLEET_LENS, type Finding, type FleetContract, type FleetEntry, type FleetManifest, type FleetProfile, type FleetProjectSweep, type FleetSweepOptions, type FleetSweepResult, type FreshnessFacts, type GateInventory, type GateTool, type GeneratedFile, type HookFacts, type InstructionFileSet, type InstructionScope, LENSES, type Ledger, type LedgerDiff, type LedgerEntry, type Lens, type LensReport, type LoadedConfig, type ManifestProblem, NAME, PACK_VERSION, PREMISE_BRIEF_FILE, PREMISE_LENS, type PackageManager, type PathClaims, type PlanOptions, type PremiseEntity, type PremiseOptions, type PremiseResult, type ProjectFacts, type PromotedText, type PromotionContext, type PromotionSkips, type RefsResult, type StateBudgets, TOTAL_BUDGET_WORDS, type TextClaimsOptions, type TextClaimsResult, type TruthEnv, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, buildTruthEnv, cacheFactsPath, checkDecisionRefs, checkDocRefs, checkManifest, checkTextClaims, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, emptyCounters, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadDecisionLedger, loadFleetManifest, measureContext, planWorkflow, promoteBareTokens, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, renderBrief, runAudit, runPremise, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };