@mmnto/cli 1.121.0 → 1.122.0

package/dist/commands/spec.d.ts

@@ -1,4 +1,4 @@
-import type { LanceStore, SearchResult, TotemConfigError as TotemConfigErrorClass } from '@mmnto/totem';
+import type { GroundingAnchor, LanceStore, SearchResult, TotemConfigError as TotemConfigErrorClass } from '@mmnto/totem';
 import type { StandardIssue } from '../adapters/issue-adapter.js';
 export declare const MAX_LESSONS = 10;
 export declare const MAX_LESSON_CHARS = 8000;
@@ -10,15 +10,53 @@ export interface RetrievedContext {
     lessons: SearchResult[];
 }
 export declare function retrieveContext(query: string, store: LanceStore, linkedStores?: LanceStore[]): Promise<RetrievedContext>;
+/**
+ * Retrieval query for a bound record (mmnto-ai/totem#2700) — the same shape
+ * {@link buildSearchQuery} gives an issue: the record's own title (its first
+ * markdown heading) plus the head of its body, so a record retrieves the same
+ * way an issue does rather than through a hand-picked slug.
+ */
+export declare function buildRecordSearchQuery(record: SpecRecord): string;
 /**
  * Expand a spec search query with test-infrastructure keywords when the
  * original query mentions testing concepts.  This helps the vector search
  * surface existing helpers like `rule-tester.ts`.
  */
 export declare function expandSpecQuery(query: string): string;
+/**
+ * A hand-authored design record bound with `--from` (mmnto-ai/totem#2700).
+ * Read ONCE as a Buffer at command start: `sha256` and `body` come from that
+ * same buffer, so the digest and the bytes rendered into the prompt agree by
+ * construction. The record is never written back.
+ */
+export interface SpecRecord {
+    /** Repo-relative path (forward slashes) — the anchor's `ref`; the gate reads the file at this path from the worktree top. */
+    path: string;
+    /** sha256 (hex) of the file's RAW bytes — what the pre-commit reader hashes. */
+    sha256: string;
+    /**
+     * The record's text, decoded utf-8 from the same buffer the digest was taken
+     * over, with one leading byte-order mark stripped: the mark is a decoding
+     * artifact, never part of the document, and the digest above still names the
+     * raw bytes so both sides hash the same thing.
+     */
+    body: string;
+}
 export interface ParsedInput {
     issue: StandardIssue | null;
     freeText: string | null;
+    /** The bound design record (mmnto-ai/totem#2700) — the third arm; `null` on the issue and topic arms. */
+    record: SpecRecord | null;
+    /**
+     * The ISSUE input exactly as typed — recorded for EVERY issue input, bare
+     * numbers included, because a fetched {@link StandardIssue} carries only the
+     * number and the anchor's `ref` must round-trip what the operator wrote.
+     * {@link issueAnchorRef} decides what reaches the ref: a bare number renders
+     * as `#<n>`, while a qualified `owner/repo#N` or a URL is kept as typed
+     * (sanitized). Absent on the topic / record arms, whose refs are the topic
+     * text and the record path.
+     */
+    issueRef?: string;
 }
 export declare function assemblePrompt(inputs: ParsedInput[], context: RetrievedContext, systemPrompt: string): Promise<string>;
 export interface SpecOptions {
@@ -27,12 +65,141 @@ export interface SpecOptions {
     stdout?: boolean;
     model?: string;
     fresh?: boolean;
+    /** Path to a hand-authored design record to ground the run on (mmnto-ai/totem#2700). */
+    from?: string;
 }
 /**
  * mmnto-ai/totem#1555: validate that --stdout and --out are not used together.
  * Run before any LLM call so a user-error surfaces in <50ms with no API cost.
  */
 export declare function validateOutputOptions(options: Pick<SpecOptions, 'out' | 'stdout'>, TotemConfigErrorCtor: typeof TotemConfigErrorClass): void;
+/**
+ * Refuse the two invocation shapes that carry no single grounded subject:
+ * nothing at all (commander no longer refuses it — `spec [inputs...]` is
+ * optional so `--from` is reachable, mmnto-ai/totem#2700 B2), and a record
+ * bound alongside positional inputs (two subjects, one anchor).
+ */
+export declare function validateSpecInvocation(inputs: string[], options: Pick<SpecOptions, 'from'>, TotemConfigErrorCtor: typeof TotemConfigErrorClass): void;
+export interface SpecRecordDeps {
+    resolveGitRoot: (cwd: string) => string | null;
+}
+/**
+ * Whether a root-relative record path ESCAPES the repository — the containment
+ * gate on `grounding.anchor.ref` (mmnto-ai/totem#2700).
+ *
+ * The published ref is resolved by the strict pre-commit reader from the
+ * WORKTREE TOP, so a path that leaves the root names a file the gate would
+ * read from outside the repo: `--from ../sibling/x.md` binds `../sibling/x.md`,
+ * and a record on another drive binds an absolute path (`path.relative` returns
+ * one when the two paths share no root). The hook carries the same refusal —
+ * the artifact is hand-editable, so neither half may trust the other — but a
+ * ref that escapes must never be MINTED either.
+ *
+ * Both `path` flavors are consulted because the caller normalizes to forward
+ * slashes before asking: `D:/x.md` is not a repo-relative path on ANY platform,
+ * so the answer must not depend on which one is running.
+ *
+ * Containment is decided by NORMALIZATION, not by inspecting the first segment:
+ * `a/../../x.md` escapes the root even though its first segment does not say
+ * so, while a mid-path `..` that stays inside (`a/../b.md`) is contained and
+ * legal. `path.posix.normalize` is the cwd-free equivalent of the reader's
+ * `resolve` + `relative` containment test, so both sides answer the same on the
+ * same input — the predicate is compared by path SEGMENT throughout, which is
+ * why a file named `..notes.md` inside the root stays legal.
+ *
+ * {@link loadSpecRecord} asks this TWICE: once on the lexical repo-relative
+ * spelling that becomes the ref, and once on the relative path between the two
+ * REALPATHS, so an in-repo symlink whose target lives outside the tree is
+ * refused as well. Normalization alone cannot see through a link.
+ */
+export declare function isRecordPathOutsideRoot(relativePath: string): boolean;
+export interface LoadedSpecRecord {
+    record: SpecRecord;
+    /** The record's resolved absolute path — the subject of the `--out` collision check. */
+    absolutePath: string;
+}
+/**
+ * Read and bind the `--from` record. ONE `readFileSync` produces both the
+ * digest and the prompt bytes, so `grounding.anchor.sha256` provably names
+ * what the model was shown. Every rejection names the path.
+ *
+ * Order is load-bearing. Existence is decided FIRST, so a path that names
+ * nothing keeps the "record not found" cure. CONTAINMENT is decided second —
+ * before any `statSync` or `readFileSync` — so a record outside the repository
+ * is refused as uncontained rather than by whatever the read happens to say
+ * about it (a directory outside the root must not surface as "not a file").
+ * Containment is judged twice: LEXICALLY on the spelling that becomes the
+ * published ref, and again on the REALPATHS of the record and the root, so an
+ * in-repo symlink pointing out of the tree cannot bind a file the gate would
+ * read from outside the worktree. `record.path` stays the LEXICAL
+ * repo-relative path of the file as given — the hook resolves links on its own
+ * side, and rewriting the ref to a link's target would publish a path the
+ * operator never wrote.
+ */
+export declare function loadSpecRecord(fromPath: string, cwd: string, deps: SpecRecordDeps, TotemConfigErrorCtor: typeof TotemConfigErrorClass): LoadedSpecRecord;
+/**
+ * `--out` may never resolve to the bound record: the tool BINDS a hand-authored
+ * record, it never drafts over it. Identity is decided by {@link isSameFile},
+ * so a symlink or a hardlink pointed at the record is refused with the same
+ * words a literal path collision gets — a spelling comparison alone would let
+ * either one through and clobber the record.
+ */
+export declare function assertOutDoesNotOverwriteRecord(out: string | undefined, recordAbsolutePath: string, cwd: string, TotemConfigErrorCtor: typeof TotemConfigErrorClass): void;
+/**
+ * Classify what the run is ANCHORED on (mmnto-ai/totem#2700). A record wins
+ * outright (it is the only kind carrying bytes); otherwise the kind is
+ * `issue` when every input resolved to an issue, `free-text` when every input
+ * is a topic, and the honest `mixed` when both are present — `mixed` proceeds
+ * (an issue IS grounding) but is not gate evidence, because its free-text half
+ * is the confabulation surface.
+ *
+ * The caller guarantees at least one parsed input ({@link
+ * validateSpecInvocation}); the schema's non-empty `ref` refine is the
+ * backstop if that ever stops holding. Topic text and a typed issue ref both
+ * pass through {@link sanitizeRefText} on the way into the ref, so a control
+ * character the user typed cannot cost the run its artifact.
+ */
+export declare function resolveGroundingAnchor(parsed: ParsedInput[]): GroundingAnchor;
+/** One below-floor candidate, disclosed as path + relevance only — never content. */
+export interface WithheldCandidate {
+    filePath: string;
+    sourceRepo?: string;
+    relevance: number;
+}
+export interface GroundingFloorVerdict {
+    /** True when the run must be refused before any LLM call and before any artifact is minted. */
+    refuse: boolean;
+    /** Retrieved items across all four partitions. */
+    hits: number;
+    /** The highest relevance among signal-bearing items; `null` when nothing carried a vector leg. */
+    bestRelevance: number | null;
+    /** The below-floor signal-bearing candidates the refusal withheld — empty whenever the run proceeds. */
+    withheld: WithheldCandidate[];
+    /** Items with no relevance at all (FTS-only) — floor-EXEMPT, never withheld for a weak sibling's sake. */
+    floorExempt: number;
+}
+/**
+ * Judge the retrieval against the relevance floor, over ALL items across the
+ * four partitions (mmnto-ai/totem#2700). Mirrors the MCP tool's semantics
+ * (`packages/mcp/src/tools/search-knowledge.ts`): the floor fires only when a
+ * real relevance signal exists, and judges only the hits that carry one —
+ * keyword-only hits have no comparable relevance and are floor-EXEMPT, so a
+ * mixed batch is never withheld because its vector-leg siblings scored weak.
+ *
+ * Zero items is this command's OWN rule, not an MCP mirror: nothing retrieved
+ * means nothing grounds the run, so it refuses regardless of any floor.
+ */
+export declare function evaluateGroundingFloor(context: RetrievedContext, floor: number): GroundingFloorVerdict;
+/**
+ * The refusal's text: the topic(s) refused, the measurement (`0 hits` or the
+ * best relevance), the floor's VALUE and its PLACE, and every withheld
+ * candidate as `path — relevance` (linked hits prefixed with their store).
+ * Exclusion is disclosed, never silently dropped.
+ */
+export declare function formatGroundingRefusal(topics: string, verdict: GroundingFloorVerdict, floor: number): {
+    message: string;
+    recoveryHint: string;
+};
 /**
  * Sanitize a free-form topic string for use as a filename stem. Replaces any
  * character outside `[a-zA-Z0-9_-]` with a single dash, collapses runs, and

package/dist/commands/spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/commands/spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,YAAY,EACZ,gBAAgB,IAAI,qBAAqB,EAC1C,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAQlE,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAQtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAMzD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,UAAU,EAAE,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B;AAYD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAID,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CA6CjB;AAID,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,QAAQ,CAAC,EAC5C,oBAAoB,EAAE,OAAO,qBAAqB,GACjD,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC/C,QAAQ,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,WAAW,EAAE,EAC3B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,mBAAmB,GACxB,MAAM,GAAG,IAAI,CAcf;AAID,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA4NvF"}
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/commands/spec.ts"],"names":[],"mappings":"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"}