etymd 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -464,12 +464,12 @@ interface AuditOptions {
     persistLedger?: boolean;
     /**
      * Fleet: the audited root is READ-ONLY — write nothing into it, not even the scan cache
-     * where `.etymd` already exists there. A corp worktree is never written, regardless of flags.
+     * where `.etymd` already exists there. A guarded worktree is never written, regardless of flags.
      */
     readOnlyRoot?: boolean;
     /**
-     * Fleet: read/write the ledger at this root instead of the audited one. Corp findings persist
-     * under the manifest's `corp/<name>/`, never inside the corp worktree.
+     * Fleet: read/write the ledger at this root instead of the audited one. Guarded findings persist
+     * under the manifest's `guarded/<name>/`, never inside the guarded worktree.
      */
     ledgerRoot?: string;
     /** Fleet: per-entry state-budget overlay (registry `staleAfterDays` / `stateBudget`). */
@@ -490,11 +490,11 @@ interface AuditResult {
 }
 declare function runAudit(root: string, opts?: AuditOptions): Promise<AuditResult>;
 
-type FleetProfile = "personal" | "corp";
+type FleetProfile = "personal" | "guarded";
 /**
  * How exposed an entry's history is, or could plausibly become. A SAFETY PREDICATE, not a label:
  * it decides whether content screening applies, so absence must never read as the permissive
- * answer. `checkManifest` treats an undeclared non-corp entry as a finding — a repo published
+ * answer. `checkManifest` treats an undeclared non-guarded entry as a finding — a repo published
  * without ever answering the question is exactly the case a default would hide.
  *
  *   `public-repo`   already public — outside-contribution surface.
@@ -503,7 +503,7 @@ type FleetProfile = "personal" | "corp";
  *                   not the visibility flip.
  *   `private`       not destined to be published. An ANSWER, not the absence of one.
  *
- * Corp entries do not carry it — `profile: "corp"` implies the answer (machine-pinned, never
+ * Guarded entries do not carry it — `profile: "guarded"` implies the answer (machine-pinned, never
  * publishable), so requiring it there would be ceremony.
  */
 type FleetTrust = "public-repo" | "public-bound" | "private";
@@ -524,6 +524,12 @@ interface FleetContract {
     state?: string;
     decisions?: string;
     goals?: string;
+    /**
+     * The project's milestones file (`MILESTONES.md` by convention), rolled up by `etymd fleet
+     * board`; its shape is checked by the sweep. `"none"` declares the project deliberately
+     * carries no milestones (a state, not a gap).
+     */
+    milestones?: string;
     /** `"none"` = the contract file is legitimately absent (a declared state, not a gap). */
     placement?: string;
 }
@@ -538,7 +544,7 @@ interface FleetEntry {
     upstream?: string;
     /**
      * How exposed this entry is — see {@link FleetTrust}. `"public-repo"` marks an
-     * outside-contribution surface (hygiene needles apply). Undeclared on a non-corp entry is a
+     * outside-contribution surface (hygiene needles apply). Undeclared on a non-guarded entry is a
      * `fleet check` finding, never a silent "private".
      */
     trust?: FleetTrust;
@@ -573,14 +579,14 @@ interface FleetManifest {
     shape: "registry" | "corpus";
     /** Absolute path of the tracked manifest file. */
     manifestPath: string;
-    /** Its directory — corp persistence roots and the sweep delta file live beside it. */
+    /** Its directory — guarded persistence roots and the sweep delta file live beside it. */
     dir: string;
     /** Resolved absolute fleet root (registry shape), when declared. */
     root?: string;
     /** Fleet-wide orientation root, when the manifest declares one. Absent = this fleet has none. */
     orientation?: FleetOrientation;
     machineProfile?: FleetProfile;
-    corpHosts: string[];
+    guardedHosts: string[];
     labels: Record<string, string>;
     localDirs: Record<string, string>;
     /** Absolute path where the gitignored local sibling is expected. */
@@ -605,18 +611,18 @@ declare const FLEET_JSON_SCHEMA = "fleet-experimental-0.2";
 interface FleetSweepOptions {
     /** Restrict to these registered names (unknown names throw — a typo must not skip silently). */
     only?: string[];
-    profile?: "personal" | "corp";
+    profile?: "personal" | "guarded";
     /** Truth lenses only per repo (the doctor subset). */
     kind?: LensKind;
     /**
      * Persist per-repo ledgers — ONLY for personal-profile entries that already carry `.etymd`.
-     * The sweep never creates `.etymd` anywhere, and corp worktrees are never written at all.
+     * The sweep never creates `.etymd` anywhere, and guarded worktrees are never written at all.
      */
     persistLedgers?: boolean;
 }
 interface FleetProjectSweep {
     name: string;
-    profile: "personal" | "corp";
+    profile: "personal" | "guarded";
     kind?: string;
     resolvedRoot?: string;
     /** Why this entry could not be audited — mirrored into `outOfScope`. */
@@ -648,15 +654,15 @@ interface RecurringClass {
     /** The `<lens>/<class>` id prefix — minted by the engine's lenses, identical across repos. */
     classId: string;
     tier: FindingTier;
-    /** Project names (corp entries by alias) where the class is currently open. */
+    /** Project names (guarded entries by alias) where the class is currently open. */
     projects: string[];
 }
 /**
- * Where a corp entry's audit state persists: beside the manifest, never in the worktree.
+ * Where a guarded entry's audit state persists: beside the manifest, never in the worktree.
  * Belt-and-braces to the loader's safe-name rule: a name that resolves anywhere but directly
- * under `<dir>/corp/` is refused — the manifest can lie, and a lie must never steer a write.
+ * under `<dir>/guarded/` is refused — the manifest can lie, and a lie must never steer a write.
  */
-declare function corpPersistenceRoot(manifest: FleetManifest, name: string): string;
+declare function guardedPersistenceRoot(manifest: FleetManifest, name: string): string;
 /**
  * Validate the manifest pair itself: parse problems, dangling mappings (the live ghost-entry
  * class), duplicate names, privacy leaks, dead links, machine paths. Pure manifest truth —
@@ -673,12 +679,94 @@ declare function collectWallFindings(manifest: FleetManifest): Promise<{
 }>;
 /**
  * The fleet sweep: one read-only audit per resolved entry + the fleet-scope wall checks.
- * Invariants (each pinned by test): never creates `.etymd` anywhere; never writes into a corp
+ * Invariants (each pinned by test): never creates `.etymd` anywhere; never writes into a guarded
  * worktree regardless of flags or a stray `.etymd` there; unresolvable entries land in
  * `outOfScope` with a disclosure, never a silent skip.
  */
 declare function sweepFleet(manifest: FleetManifest, opts?: FleetSweepOptions): Promise<FleetSweepResult>;
 
+/**
+ * `etymd propose` — the scoring step between the sweep and a filed proposal.
+ *
+ * The sweep already mints everything a proposal needs (every finding carries an action, an
+ * effort and a confidence; `recurringClasses` names the classes open in ≥2 projects). This
+ * module adds the two things that were missing: a rubric the FLEET authors (the tool ships
+ * none — with no rubric there is nothing to run) and a stable record shape (`proposal/1`)
+ * a planning surface can file mechanically.
+ *
+ * Everything here is a pure function of its inputs — no clocks, no randomness — so the same
+ * sweep plus the same rubric yields byte-identical output, and a filed proposal can be
+ * re-derived and compared later. Decision record: docs/decisions/012.
+ */
+/** The record schema marker — experimental through 0.2.x with the rest of the fleet family. */
+declare const PROPOSAL_SCHEMA = "proposal/1";
+/**
+ * The criteria the tool can compute, each mapped to a 1–3 value. The vocabulary is closed: a
+ * rubric line naming anything else is refused, because a criterion this tool cannot derive
+ * mechanically would be an opinion wearing a number — the exact product anti-pattern. The
+ * WEIGHTS are the fleet's; the tool imposes none.
+ */
+declare const RUBRIC_CRITERIA: readonly ["severity", "economy", "confidence", "breadth"];
+type RubricCriterion = (typeof RUBRIC_CRITERIA)[number];
+interface RubricLine {
+    criterion: RubricCriterion;
+    weight: number;
+}
+interface Rubric {
+    lines: RubricLine[];
+}
+/**
+ * Parse a rubric file: labeled lines, one criterion per line (`criterion: <weight>`), `#`
+ * comments and blanks ignored. The line is the unit of refusal — unknown criterion, malformed
+ * line, duplicate criterion, or a rubric with no criteria at all each name their line (or the
+ * file), never a silent skip and never a default weight.
+ */
+declare function parseRubric(text: string, file: string): Rubric;
+interface MatchedLine {
+    criterion: RubricCriterion;
+    weight: number;
+    /** The computed 1–3 value — carried beside the weight so the score is auditable. */
+    value: number;
+}
+interface Implications {
+    projects: string[];
+    files: string[];
+    gates: string[];
+    reversibility: "regenerable" | "git-reversible" | "undetermined";
+}
+interface Proposal {
+    id: string;
+    schema: typeof PROPOSAL_SCHEMA;
+    class: string;
+    kind: "finding" | "class";
+    projects: string[];
+    action: string;
+    effort: Effort;
+    confidence: Confidence;
+    score: number;
+    matched: MatchedLine[];
+    implications: Implications;
+}
+interface ProposeResult {
+    schema: typeof PROPOSAL_SCHEMA;
+    manifest: string;
+    rubric: string;
+    criteria: RubricLine[];
+    proposals: Proposal[];
+    disclosures: string[];
+}
+/**
+ * Build the proposals from a sweep result: every `kind: "improvement"` finding from every
+ * personal project, plus every recurring class recomputed over personal projects only. Guarded
+ * entries are excluded from the output entire (their findings, and their names inside class
+ * breadth) — a guarded improvement is the guarded side's backlog, not this fleet's proposal queue —
+ * and their exclusion is disclosed by name so absence is a stated policy, never a hole.
+ */
+declare function buildProposals(sweep: {
+    manifest: string;
+    projects: FleetProjectSweep[];
+}, rubricName: string, rubric: Rubric): ProposeResult;
+
 /**
  * The truth lens: does what the instruction files CLAIM still hold against the actual repo?
  * Commands must exist as scripts, paths must exist on disk, files must agree on the package
@@ -686,6 +774,188 @@ 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;
+    /** Path claims whose every mention sits behind a namespace prefix (`pc:`) — another repo's. */
+    namespacedSkipped: number;
+    /** Missing paths starting at no directory of this repo — quoted from elsewhere (task only). */
+    outsideRepoSkipped: 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;
+    /**
+     * Directories a missing path may start from and still be plausibly repo-relative — the root,
+     * workspace packages, and their src/ scripts/. Supplied by the task surface (`etymd premise`)
+     * only: a task quoting a path from ANOTHER repository (a clone in a scratchpad) starts where
+     * no directory of this repo does, and its absence here proves nothing. Instruction files keep
+     * the stricter reading — their references are written against this repo.
+     */
+    rootedFirstSegments?: ReadonlySet<string>;
+    /**
+     * Read namespace-prefixed path mentions (`pc: `src/x.ts``) as another repo's tree — the task
+     * surface only; instruction files keep every backticked span as a claim of this repo.
+     */
+    treatNamespacedPrefixes?: boolean;
+}
+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;
+    /** `pc:src/x.ts`, `lk: src/x.ts` — a namespace-prefixed mention of ANOTHER repo's tree. */
+    namespaced: 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;
@@ -719,16 +989,27 @@ interface PathClaims {
     paths: string[];
     /** Claims whose every mention sits in create-this prose — skipped, counted, disclosed. */
     prospective: string[];
+    /** Claims whose every mention sits behind a namespace prefix (`pc:`) — another repo's tree. */
+    namespaced: string[];
     /** Naming stand-ins (`my-custom-skill`) — never real claims. */
     placeholder: string[];
 }
+interface PathClaimOptions {
+    /**
+     * Read namespace-prefixed mentions (`pc: `src/x.ts``) as another repo's tree — the task
+     * surface, where prompts quote foreign repos behind a legend. Instruction files keep every
+     * backticked span as a claim of this repo.
+     */
+    namespaces?: boolean;
+}
 /**
  * Repo-relative path claims from single-token inline spans, conservatively filtered. The
  * load-bearing precision rule (learned from real corpus prose): an extensionless bare token
  * (`research/trust`, `milestone/mNN`) is prose — a dir claim must end with `/`, a file claim
- * must carry an extension.
+ * must carry an extension. With `namespaces`, a span whose every mention sits behind a
+ * namespace prefix names another repo's tree, not this one.
  */
-declare function extractPathClaims(text: string): PathClaims;
+declare function extractPathClaims(text: string, opts?: PathClaimOptions): PathClaims;
 
 /** Default total always-loaded words past which the footprint itself becomes a finding. */
 declare const TOTAL_BUDGET_WORDS: number;
@@ -825,4 +1106,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, PROPOSAL_SCHEMA, type PackageManager, type PathClaims, type PlanOptions, type PremiseEntity, type PremiseOptions, type PremiseResult, type ProjectFacts, type PromotedText, type PromotionContext, type PromotionSkips, type Proposal, type ProposeResult, RUBRIC_CRITERIA, type RefsResult, type Rubric, type RubricCriterion, type RubricLine, type StateBudgets, TOTAL_BUDGET_WORDS, type TextClaimsOptions, type TextClaimsResult, type TruthEnv, VERSION, type WorkflowProfile, type WorkspaceKind, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, buildProposals, buildTruthEnv, cacheFactsPath, checkDecisionRefs, checkDocRefs, checkManifest, checkTextClaims, collectWallFindings, configPath, contextEconomyLens, deriveProfile, emptyCounters, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, guardedPersistenceRoot, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadDecisionLedger, loadFleetManifest, measureContext, parseRubric, planWorkflow, promoteBareTokens, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, renderBrief, runAudit, runPremise, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };