peaks-loop 4.0.44 → 4.0.46

package/dist/services/final-review/index.d.ts

@@ -1,2 +1,3 @@
-export { prepareFinalReview, type PrepareFinalReviewOptions, type LlmRunner, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, } from './final-review-service.js';
+export { prepareFinalReview, type PrepareFinalReviewOptions, type LlmRunner, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, assertFloorReservationAffordable, undeliverableDimensions, type UndeliverableDimensionEvidence, } from './final-review-service.js';
+export { classifyPrePostDiffVerdict, type PrePostDiffConclusion, } from './pre-post-diff.js';
 export type { DimensionKind, DimensionVerdict, EvidenceKind, DimensionConfidence, EvidenceItem, DimensionEvidence, FinalReviewOutput, } from './final-review-types.js';

package/dist/services/final-review/index.js

@@ -1 +1,2 @@
-export { prepareFinalReview, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, } from './final-review-service.js';
+export { prepareFinalReview, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, assertFloorReservationAffordable, undeliverableDimensions, } from './final-review-service.js';
+export { classifyPrePostDiffVerdict, } from './pre-post-diff.js';

package/dist/services/final-review/pre-post-diff.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `pre-post-diff` producer — the missing evidence source for the
+ * `existing-functionality-intact` dimension of `peaks prepare-final-review`.
+ *
+ * THE GAP THIS CLOSES. The dimension's own contract
+ * (`skills/peaks-final-review/references/4-dimensions.md`) asks for "a pre/post
+ * baseline diff [showing] no unintended drift in the test surface, public API,
+ * or key behavior" — an `EvidenceItem` of kind `pre-post-diff`. Nothing in
+ * peaks-loop produced one: the sources mapped to that dimension were
+ * `rd/tech-doc.md` (design intent) and `prd/handoff.md` (approved scope), and
+ * the reviewer LLM itself reported the mismatch ("the only FOUND source is a
+ * design-intent document, not a regression assessment"). `allPass === true`
+ * was therefore unreachable by construction, on every workflow.
+ *
+ * WHAT IT DOES. Compares a base ref against the working tree with git (no new
+ * dependency; `git` is already the repo's baseline tool) and records two
+ * structural surfaces:
+ *   1. test surface  — the test FILE lists, and `it(` / `test(` case counts,
+ *      before/after;
+ *   2. public API surface — the `.ts` / `.tsx` SOURCE FILE lists, the top-level
+ *      `export` statement count, and the ADDED/REMOVED export NAMES over the
+ *      changed files.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It never invents a baseline. When no base
+ * ref resolves — or the project is not a git work tree at all, or the base
+ * resolves to HEAD itself so the compared range is empty — it returns
+ * `unavailable` with a reason and writes NO artifact, so the dimension has no
+ * `pre-post-diff` evidence and cannot be reported `pass` on the strength of a
+ * fabricated (or empty) diff.
+ *
+ * HONESTY BOUNDARY (also written into the artifact itself). Export detection is
+ * a line-anchored REGEX, not a type checker. It detects a structural loss — an
+ * export that was removed or renamed — and it CANNOT detect a signature change,
+ * a narrowed type, or a behaviour change inside a function body. It is a drift
+ * detector, not proof that the API is unchanged. File-level deletion IS visible,
+ * because it is read from the file lists rather than inferred from the counts.
+ *
+ * THE VERDICT COMES FIRST. The artifact opens with its `VERDICT:` line, above
+ * the metadata and the counts. The consumer may legitimately receive only the
+ * head of this file (it is an evidence source under a per-file byte cap), and
+ * with the conclusion at the end every such truncation dropped exactly the part
+ * the dimension has to judge — so a partially delivered artifact was
+ * indistinguishable from a clean comparison. Conclusion-first makes "the
+ * reviewer got the answer" a property of the bytes received.
+ */
+/** Path segments (under `.peaks/_runtime/<sessionId>/`) the artifact lands at. */
+export declare const API_DIFF_ARTIFACT_SEGMENTS: readonly ["final-review", "api-diff.txt"];
+/**
+ * The literal that opens the artifact's conclusion line.
+ *
+ * Exported because the consumer must be able to test for the CONCLUSION, not
+ * for a byte count (F-BLOCK-1BYTE): one byte of `api-diff.txt` satisfied
+ * "status: found" while conveying nothing, and the delivery gate it fed then let
+ * a `pass` stand on a comparison nobody saw. The producer writes the line this
+ * marker opens and `final-review-service.ts` requires it in the delivered
+ * bytes, so the two cannot drift apart into the same hole again.
+ */
+export declare const PRE_POST_DIFF_VERDICT_MARKER = "VERDICT: ";
+/**
+ * The three conclusions the artifact may open with, exported as the same
+ * literals the writer interpolates below.
+ *
+ * They are constants because reading the conclusion is now part of the
+ * consumer's job (F2): the pre/post-diff source is the one source whose
+ * conclusion had a machine-readable form all along, and the envelope threw it
+ * away — a delivered `STRUCTURAL DRIFT DETECTED` produced `allPass: true` with
+ * an empty `needsAttention`. A consumer that must classify the conclusion may
+ * only do so against the producer's own literals, never against a re-typed
+ * copy of them.
+ */
+export declare const PRE_POST_DIFF_NO_DRIFT = "NO STRUCTURAL DRIFT";
+export declare const PRE_POST_DIFF_ADDITIONS_ONLY = "ADDITIONS ONLY";
+export declare const PRE_POST_DIFF_DRIFT_DETECTED = "STRUCTURAL DRIFT DETECTED";
+/**
+ * What the artifact's conclusion LINE says, read from the bytes a consumer
+ * actually received.
+ *
+ * `indeterminate` is not "nothing to report": it is "the line is there (or is
+ * not) and this consumer cannot classify it", which for a drift DETECTOR is a
+ * fact a human has to see — see `enforceStructuralDriftAttention`.
+ */
+export type PrePostDiffConclusion = 'no-drift' | 'additions-only' | 'drift-detected' | 'indeterminate';
+/**
+ * Classify the delivered conclusion. Pure and total: a caller passes the bytes
+ * it received (possibly a head slice) and gets back what the artifact says.
+ *
+ * Only the FIRST `VERDICT:` line is read. The artifact's header promises the
+ * verdict "is repeated nowhere" and that it is the file's conclusion, so a
+ * later line cannot be the answer, and reading further would let a document's
+ * prose masquerade as its conclusion.
+ */
+export declare function classifyPrePostDiffVerdict(content: string): PrePostDiffConclusion;
+/** Test-file globs — the single definition both the file count and the case
+ *  count use, so the two can never disagree about what a "test file" is. */
+export declare const TEST_FILE_GLOBS: readonly ["*.test.ts", "*.test.tsx", "*.spec.ts", "*.spec.tsx"];
+/** Source globs for the public-API surface. */
+export declare const API_SOURCE_GLOBS: readonly ["*.ts", "*.tsx"];
+export interface PrePostDiffComputed {
+    readonly status: 'computed';
+    readonly summary: string;
+    readonly relativePath: string;
+    readonly absolutePath: string;
+    readonly content: string;
+}
+export interface PrePostDiffUnavailable {
+    readonly status: 'unavailable';
+    /** Why no baseline exists, in the operator's terms. */
+    readonly reason: string;
+    /**
+     * `true` when the project root IS a git work tree — i.e. a baseline was
+     * expected to be computable and was not. That distinction shapes the REASON
+     * the operator is given (a tooling failure to fix, versus a project that has
+     * no baseline to offer), and the service refuses a `pass` on this dimension
+     * either way: "not a git repository" is the CAUSE of the missing evidence,
+     * never a licence to trust the claim the evidence was supposed to support.
+     */
+    readonly inGitWorkTree: boolean;
+}
+export type PrePostDiffResult = PrePostDiffComputed | PrePostDiffUnavailable;
+export interface ProducePrePostDiffOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** Explicit base ref. Unset ⇒ merge-base with the upstream default branch. */
+    readonly baseRef?: string;
+}
+/**
+ * The exported NAMES bound by one source line. Approximate by design: the
+ * column-0 anchor is what keeps it to top-level declarations, and
+ * `export { a as b }` binds `b` (the name importers get).
+ */
+export declare function extractExportedNames(line: string): readonly string[];
+/**
+ * Produce the diff, or say why it could not be produced. Total: it never
+ * throws, because a final review must not die on a missing git binary — it
+ * must report a dimension it could not assess.
+ */
+export declare function producePrePostDiff(opts: ProducePrePostDiffOptions): PrePostDiffResult;