etymd 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -303,6 +303,14 @@ interface PlanOptions {
     publishGate?: boolean;
     /** Recorded gate choices; absent means derive everything from the scan. */
     gateConfig?: GateConfig;
+    /**
+     * Whether `gateConfig.failOn` was PINNED by the repo's committed config, versus a default the
+     * config loader filled in. The tier derivation may only choose between defaults — a recorded
+     * tier is a decision and is never lowered (see `deriveFailOn`). Callers that read the config
+     * pass `explicit.gatesFailOn` from `readConfig`; callers planning from a bare scan leave it
+     * unset, which is the same as unpinned.
+     */
+    gateFailOnPinned?: boolean;
 }
 /** Build the file set an onboarding would write, flagging which exist and which differ. */
 declare function planWorkflow(root: string, facts: ProjectFacts, opts: PlanOptions): Promise<GeneratedFile[]>;
@@ -464,12 +472,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 +498,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 +511,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 +532,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 +552,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 +587,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 +619,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 +662,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 +687,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
@@ -716,6 +812,10 @@ interface ClaimCounters {
     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;
 /**
@@ -749,6 +849,19 @@ interface TextClaimsOptions {
     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[];
@@ -825,6 +938,8 @@ interface PromotionSkips {
     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/. */
@@ -882,16 +997,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;
@@ -988,4 +1114,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 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 };
+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 };