opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/features/completion-review/calibration-types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Task 7 — shapes for the calibration comparison.
+ *
+ * Types only, and every one of them is deliberately incapable of carrying a
+ * fabricated score: there is no numeric field anywhere on a plan-time baseline,
+ * because a tier string has no scale to convert it with.
+ */
+/** Where a plan-time baseline was STORED. Nothing here is re-derived. */
+export type CalibrationBaselineSource = "ESTIMATED_EFFORT_LINE" | "COMPLEXITY_LINE";
+/** One recorded plan-time estimate, reproduced exactly as the plan wrote it. */
+export interface PlanTimeBaselineField {
+    source: CalibrationBaselineSource;
+    /** The plan's own words, untouched. Never coerced to a level or a number. */
+    verbatim: string;
+    /** 1-based plan line the value was read from; `null` when absent. */
+    line: number | null;
+}
+export interface PlanTimeBaseline {
+    effort: PlanTimeBaselineField | null;
+    complexity: PlanTimeBaselineField | null;
+}
+/** What execution actually did, as far as code could read it. */
+export interface ObservedExecutionFacts {
+    tasksExecuted: number;
+    filesTouched: number;
+    notepadBlockerEntries: number;
+}
+/**
+ * The ONLY code-computable part of dimension 8.
+ *
+ * Presence is arithmetic-free and needs no judgement. The over/under DIRECTION
+ * is an ordinal-vs-ordinal read and belongs to the model, which is why this
+ * carries no `score`: emitting one here is exactly the fabrication the task
+ * forbids.
+ */
+export type CalibrationBaselineCheck = {
+    status: "baseline_present";
+    baseline: PlanTimeBaseline;
+} | {
+    status: "unscorable";
+    reason: string;
+};
+export interface CalibrationRenderInput {
+    baseline: PlanTimeBaseline;
+    observed: ObservedExecutionFacts;
+}
+/** The two report sections this module owns the CONTENT of. */
+export interface CalibrationComparison {
+    complexity: string;
+    requiredEffort: string;
+}

package/dist/features/completion-review/calibration.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Task 7 — report sections (c) Complexity and (d) Required Effort, as
+ * CALIBRATION COMPARISONS.
+ *
+ * The question these sections answer is not "how hard was this?" but "was the
+ * plan's own estimate right, given what actually happened?" That makes the
+ * completion reviewer an INSTRUMENT rather than a gate: every completed plan
+ * contributes a row to a corpus of estimate accuracy, and that corpus is the
+ * only way to find out whether the plan-generation heuristic runs wide. One
+ * review's comparison is noise; fifty of them are a signal — and the signal is
+ * about the PLAN GENERATOR, not the executor.
+ *
+ * Three rules make the corpus trustworthy, and each is a hard constraint rather
+ * than a style preference:
+ *
+ * 1. **The baseline is STORED, never re-derived.** It is read from the
+ *    `**Estimated Effort**` line the plan skeleton already emits (the PRIMARY
+ *    source, carried by 33 of the corpus plans — but only 20 of those are a bare
+ *    enum word, so the parser preserves free-form prose verbatim). There is no
+ *    optional front-matter estimate field yet and nothing that would write one;
+ *    when one lands it is a SECONDARY source, below the line, never a substitute
+ *    for it.
+ * 2. **The observed side is OBSERVED, not modelled** — tasks executed, files
+ *    touched, notepad `## Blockers` entries, all already collected by the
+ *    gatherer. The routing-only C-level heuristic is deliberately not imported
+ *    here: it feeds Seraph gating, and borrowing it as a quality signal would
+ *    quietly change that gate.
+ * 3. **No arithmetic delta is ever computed from a tier string.** A word like
+ *    "Large" has no scale, so "under-estimated by 30%" would be a number the
+ *    plan never asserted. The comparison is directional and qualitative, and
+ *    the direction is dimension 8's call.
+ *
+ * Dimension 8 (`estimate-calibration`) is a MODEL dimension for exactly that
+ * reason. Its one code-computable sub-part — "does a plan-time baseline exist at
+ * all" — is `checkCalibrationBaseline`, and it returns presence without a
+ * `score`. With no baseline, the answer is `unscorable`: never 0, never 1, and
+ * never a synthesised level. A missing estimate is a gap in the PLAN, and
+ * scoring it as a bad estimate would blame the executor for it.
+ *
+ * T4 owns the section headings; this module owns the content behind them, so
+ * the renderer returns the two body lines and the caller places them under (c)
+ * and (d).
+ */
+export { parsePlanTimeBaseline } from "./calibration-baseline";
+export { checkCalibrationBaseline } from "./calibration-baseline-check";
+export type { ObservedFactSources } from "./calibration-observed";
+export { collectObservedExecutionFacts } from "./calibration-observed";
+export { renderCalibrationComparison } from "./calibration-render";
+export type { CalibrationBaselineCheck, CalibrationBaselineSource, CalibrationComparison, CalibrationRenderInput, ObservedExecutionFacts, PlanTimeBaseline, PlanTimeBaselineField, } from "./calibration-types";

package/dist/features/completion-review/degradation-evaluate.d.ts

@@ -0,0 +1,17 @@
+import { missingSectionReason } from "./degradation-model";
+import type { NotScorableReview, ReviewOutcome } from "./degradation-types";
+import type { ProgressFacts } from "./gather-types";
+import type { DeterministicInputs, RubricDimension } from "./rubric-types";
+export interface ReviewInput {
+    progress: ProgressFacts;
+    deterministicInputs: DeterministicInputs;
+    modelScores: Partial<Record<string, number>>;
+    /** MODEL dimension ids whose plan section is absent. Empty when none are. */
+    missingModelSections?: readonly string[];
+    dimensions?: readonly RubricDimension[];
+}
+/** The `not_scorable` verdict for a plan that must not be scored, or `null`. */
+export declare function planGateVerdict(progress: ProgressFacts, dimensions?: readonly RubricDimension[]): NotScorableReview | null;
+/** The whole review. `kind` decides whether a number exists — see the union. */
+export declare function evaluateReview(input: ReviewInput): ReviewOutcome;
+export { missingSectionReason };

package/dist/features/completion-review/degradation-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Task 6 — the compile-time gate for the four-outcome vocabulary.
+ *
+ * WHY THIS LIVES IN `src/` AND NOT IN THE TEST FILE: `tsconfig.json` EXCLUDES
+ * `tests/`, so a type-level assertion written in a test is silently unchecked
+ * and `tsc` still exits 0. These gates are the runtime twin of assertions the
+ * test file makes about BEHAVIOUR, and they are the only place TypeScript
+ * actually checks the three claims below. Same pattern, same reason as T5's
+ * `rubric-gate.ts` and T1's `precondition-gate.ts`.
+ *
+ * The three claims:
+ *   1. `not_scorable` is a SEPARATE VARIANT, not a `DimensionResult["status"]`.
+ *      Proof that it is not interchangeable: a `NotScorableReview` is not
+ *      assignable to `DimensionResult`, so a renderer written against the
+ *      per-dimension union cannot accept one by accident.
+ *   2. A `NotScorableReview` has NO `score` key. Enforced by the absence of the
+ *      field, checked here with a runtime `hasOwnProperty` assertion over a
+ *      real verdict — reading `verdict.score` would not compile at all.
+ *   3. The union is CLOSED: adding a `kind` to `ReviewOutcome` without handling
+ *      it here is a build error.
+ */
+import type { NotScorableReview, ReviewOutcome, ScoredReview } from "./degradation-types";
+import type { DimensionResult } from "./rubric-types";
+export type DegradationGateFailure = string;
+/**
+ * Claim 1 — the two families are not assignable to one another.
+ *
+ * Declared as a parameter, never a value: this compiles only while a
+ * `NotScorableReview` genuinely fails to satisfy `DimensionResult`. It is the
+ * cheapest statement in the file and does the most work.
+ */
+export declare function acceptsDimensionResult(_result: DimensionResult): void;
+/**
+ * Claim 2 — a `not_scorable` verdict exposes no numeric score. Runtime check,
+ * because the compile-time version is simply the field not existing.
+ */
+export declare function notScorableEmitsNoNumber(verdict: NotScorableReview): DegradationGateFailure | null;
+/**
+ * A scored review must always carry its denominator, so a report can never
+ * present a mean without saying what it was a mean OF.
+ */
+export declare function scoredStatesDenominator(review: ScoredReview): DegradationGateFailure | null;
+/** Narrow a union to the arm that may carry a number. */
+export declare function scoreOf(outcome: ReviewOutcome): number | null;

package/dist/features/completion-review/degradation-items.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Task 6 — `unverifiable` is a PER-ITEM outcome, and this is where it collapses.
+ *
+ * The rule, stated once: a DETERMINISTIC dimension yields a number **iff at least
+ * one item is scored**. Items with no evidence are excluded INDIVIDUALLY, and
+ * the count of exclusions is reported. If exclusion leaves nothing computable,
+ * the dimension degrades to `unscorable` — never to `0`, because a 0 would
+ * charge a legacy plan for evidence it never promised to produce.
+ *
+ * `unverifiable` and `unscorable` are different levels, not synonyms:
+ * `unverifiable` is what a DoD ITEM is; `unscorable` is what a DIMENSION becomes
+ * when it has no item left to measure. Only the second one touches the weighted
+ * mean, by being excluded from it.
+ */
+import type { DoDEvidence } from "./evidence-types";
+/**
+ * `unscorable` carries no `score` field. The absence of the key is what makes
+ * "never render `unscorable` as 0" a type-checkable claim rather than a habit.
+ */
+export type CollapsedItems = {
+    kind: "scored";
+    scored: DoDEvidence[];
+    excluded: number;
+} | {
+    kind: "unscorable";
+    reason: string;
+    excluded: number;
+};
+/**
+ * Drop the `unverifiable` items, then decide whether anything is left.
+ *
+ * An EMPTY input is a different case from an all-`unverifiable` one and is
+ * reported with its own wording: a plan that declared no DoD lines is not a plan
+ * whose lines went unevidenced, and the report should say which it is.
+ */
+export declare function collapseUnverifiable(items: readonly DoDEvidence[]): CollapsedItems;
+/** How many items a collapse dropped. Reported, never folded into a 0. */
+export declare function excludedCount(collapsed: CollapsedItems): number;

package/dist/features/completion-review/degradation-model.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Task 6 — a MODEL dimension whose plan section is ABSENT is `unscorable`.
+ *
+ * Absence is detected through `resolveSectionSelector`, never by matching
+ * heading text. The plan's own headings are turned into a registry and the
+ * canonical selector is resolved against it, which is precisely the escape
+ * hatch Plan A built: a heading with no registry match returns `kind: "custom"`,
+ * and `custom` here means ABSENT rather than "not a failure". `ambiguous` is
+ * also treated as absent, because two candidate sections means the reviewer
+ * cannot say which one the plan meant.
+ *
+ * String matching would be wrong here for a reason the corpus demonstrates: two
+ * live plans spell the same section `"Must NOT Have (guardrails)"` and
+ * `"Must NOT have (Guardrails)"`. A text comparison splits those; the
+ * normalizer the registry already uses does not. (T1's correction, restated.)
+ *
+ * The consequence of absence is EXCLUSION from the weighted mean, not a 0.
+ */
+import type { PlanSectionIndexEntry } from "../../tools/plan/types";
+/**
+ * MODEL dimensions that read one specific plan section. A dimension absent from
+ * this table is not section-gated: the model judges it from the plan as a whole,
+ * so no heading can make it `unscorable`. Only genuine section dependencies are
+ * listed — claiming a dependency that does not exist would silently drop a
+ * dimension from the mean for every plan.
+ */
+export declare const MODEL_SECTION_SOURCES: Readonly<Record<string, string>>;
+/** Dimension ids whose required section is not present in the plan. */
+export declare function detectMissingModelSections(sections: readonly PlanSectionIndexEntry[]): string[];
+/** The reason a section-gated MODEL dimension reports when its section is absent. */
+export declare function missingSectionReason(dimensionId: string): string;

package/dist/features/completion-review/degradation-types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Task 6 — the four degradation outcomes, and why three of them are not one.
+ *
+ * The vocabulary is a DISCRIMINATED UNION on `kind`, and the split is not
+ * cosmetic. Three of the four outcomes are answers about a DIMENSION; the
+ * fourth is an answer about the PLAN, and conflating the two is the bug this
+ * module exists to make impossible.
+ *
+ * - `scored`       — the dimension was computed. A number exists.
+ * - `unscorable`   — a dimension with no computable input: a MODEL dimension
+ *                    whose section is absent, or a DETERMINISTIC one with no
+ *                    item left to measure. No number is invented, and the
+ *                    dimension is EXCLUDED from the weighted mean — scoring it
+ *                    0 would punish a plan for omitting a section it never
+ *                    promised.
+ * - `unverifiable` — a per-ITEM outcome (T8's `EvidenceOutcome`). It is NOT a
+ *                    dimension status: items are excluded individually, and
+ *                    only the collapse of an all-`unverifiable` set produces a
+ *                    dimension-level `unscorable`.
+ * - `not_scorable` — a PLAN-LEVEL gate. Structurally a SEPARATE VARIANT with
+ *                    no `score` field at all, so a caller cannot read a number
+ *                    off it even by accident.
+ *
+ * WHY `not_scorable` IS STRUCTURALLY DISTINCT RATHER THAN A STATUS STRING:
+ * if it were `DimensionResult["status"] = "not_scorable"`, then any
+ * `if (r.status === "unscorable")` — written for the much milder
+ * "excluded from the mean" case — would silently admit a plan that must emit
+ * no number whatsoever. Making it a variant of `ReviewOutcome` instead means
+ * narrowing on `kind` is what admits a score, and the compiler rejects the
+ * read. That is the whole argument, and it is checkable.
+ *
+ * LOCKED DECISION #2: a low score and an unscorable plan are ADVISORY. Nothing
+ * in this file throws, blocks, or returns an exit code.
+ */
+import type { ProgressFacts } from "./gather-types";
+import type { ApbGrade } from "./rubric-score";
+import type { DimensionResult, RubricDimension } from "./rubric-types";
+/** Why a plan is not scorable at all. Two causes, both plan-level. */
+export type NotScorableCause = "vacuous_completeness" | "execution_incomplete";
+export declare const NOT_SCORABLE_REASONS: {
+    readonly vacuousCompleteness: "plan declares zero checkbox items — isComplete is true by vacuity, so no dimension is measurable";
+    readonly executionIncomplete: "plan execution is not complete — a post-execution review does not score a plan that is still running";
+};
+/** The reason text for a cause. Exhaustive by construction over the union. */
+export declare function notScorableReason(cause: NotScorableCause): string;
+/** A dimension's state inside a scored review. `unscorable` is never a 0. */
+export interface DimensionState {
+    index: number;
+    id: string;
+    kind: RubricDimension["kind"];
+    weight: number;
+    result: DimensionResult;
+    /** Items dropped as `unverifiable`. 0 for every dimension but DoD coverage. */
+    excludedItems: number;
+}
+/**
+ * How much of the rubric actually produced a number. The report states this
+ * explicitly, because a mean over an unstated denominator is a lie by omission.
+ */
+export interface ScoringDenominator {
+    totalDimensions: number;
+    scoredDimensions: number;
+    excludedDimensions: number;
+    /** Sum of the weights that produced a score — consumed, never recomputed. */
+    scoredWeight: number;
+}
+/** The review produced a number. */
+export interface ScoredReview {
+    kind: "scored";
+    score: number;
+    grade: ApbGrade;
+    denominator: ScoringDenominator;
+    results: Record<string, DimensionResult>;
+    dimensions: DimensionState[];
+}
+/**
+ * The plan itself is not scorable. NOT a `DimensionResult` and NOT carrying a
+ * `score`: the absence of the field is the guarantee, and `degradation-gate.ts`
+ * makes TypeScript enforce it.
+ */
+export interface NotScorableReview {
+    kind: "not_scorable";
+    cause: NotScorableCause;
+    reason: string;
+    /** Every dimension, each explicitly `not_scorable` — never a placeholder 0. */
+    dimensions: {
+        index: number;
+        id: string;
+        outcome: "not_scorable";
+    }[];
+    progress: ProgressFacts;
+}
+/**
+ * The four outcomes, in their two families. Narrow on `kind`:
+ * `scored` carries a number, `not_scorable` does not.
+ */
+export type ReviewOutcome = ScoredReview | NotScorableReview;
+/** Compile-time closure: adding an outcome to either family is a build error. */
+export type ReviewOutcomeKind = ReviewOutcome["kind"];

package/dist/features/completion-review/degradation-vacuity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Task 6 — the plan-level `not_scorable` gate: the vacuous-completeness trap
+ * and the unfinished-plan rule.
+ *
+ * Two plan-level causes, checked in a fixed order, and BOTH are terminal for the
+ * whole review:
+ *
+ * 1. **Vacuous completeness** — `needsTriage` is set by
+ *    `countPlanProgressFromContent` exactly when `total === 0`
+ *    (`src/features/mission-state/storage.ts:187`). It arrives with
+ *    `isComplete: true`, so a naive scorer divides completed by total and emits
+ *    a perfect 1.0 for a plan that contains nothing at all. `needsTriage` is
+ *    therefore consulted BEFORE `isComplete`, not after: reading `isComplete`
+ *    first is precisely the bug.
+ * 2. **Execution incomplete** — `isComplete: false`. A post-execution reviewer
+ *    that scored a still-running plan would emit a partial score, which reads
+ *    as a verdict on work nobody finished. There is no partial score.
+ *
+ * The root cause of (1) is a genuine defect in `storage.ts:186`
+ * (`isComplete: total === 0 || completed === total`) and this plan deliberately
+ * does NOT repair it: `isComplete` has consumers far outside a review
+ * (`src/hooks/niobe/event-handler.ts:110-113` clears mission state on it).
+ * The fix belongs downstream, here, where the consequence is a number.
+ */
+import { type NotScorableCause } from "./degradation-types";
+import type { ProgressFacts } from "./gather-types";
+/** Which plan-level rule fired, or `null` when the plan may be scored at all. */
+export declare function planGateCause(progress: ProgressFacts): NotScorableCause | null;
+/** True when the plan must not be scored, for any plan-level reason. */
+export declare function isPlanNotScorable(progress: ProgressFacts): boolean;
+/** The reason text a not_scorable plan carries, or `null` when scorable. */
+export declare function planGateReason(progress: ProgressFacts): string | null;

package/dist/features/completion-review/degradation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Task 6 — the degradation semantics layer: `scored` / `unscorable` /
+ * `unverifiable` / `not_scorable`.
+ *
+ * Read the types first (`degradation-types.ts`): the fourth outcome is a
+ * separate variant of `ReviewOutcome` precisely so no caller can treat a plan
+ * that must emit no number as a dimension that was merely excluded from the
+ * mean.
+ */
+export type { ReviewInput } from "./degradation-evaluate";
+export { evaluateReview, planGateVerdict } from "./degradation-evaluate";
+export type { DegradationGateFailure } from "./degradation-gate";
+export { notScorableEmitsNoNumber, scoredStatesDenominator, scoreOf, } from "./degradation-gate";
+export type { CollapsedItems } from "./degradation-items";
+export { collapseUnverifiable, excludedCount } from "./degradation-items";
+export { detectMissingModelSections, MODEL_SECTION_SOURCES } from "./degradation-model";
+export type { DimensionState, NotScorableCause, NotScorableReview, ReviewOutcome, ReviewOutcomeKind, ScoredReview, ScoringDenominator, } from "./degradation-types";
+export { NOT_SCORABLE_REASONS, notScorableReason } from "./degradation-types";
+export { isPlanNotScorable, planGateCause, planGateReason } from "./degradation-vacuity";

package/dist/features/completion-review/evidence-capture.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Minimal programmatic evidence capture.
+ *
+ * DESIGN — reconciling two constraints that look opposed:
+ *   (1) the helper must be invocable from a QA scenario via bash, and
+ *   (2) the repo forbids `mkdir`/`touch`/`writeFileSync`/`rmSync` in TypeScript
+ *       (AGENTS.md, "File ops in code — use bash tool").
+ *
+ * Resolution: option (i). This module contains NO filesystem primitives at all.
+ * `buildCaptureCommand` returns a *shell one-liner* — the agent pastes it into
+ * the bash tool, and the SHELL performs the mkdir and the redirect. The
+ * TypeScript side only does string building and parsing, both pure.
+ *
+ * The record header (`command:` / `exit:` / `output_bytes:`) is what makes a
+ * future evidence file MACHINE-WRITTEN, so `parseCaptureRecord` can tell it
+ * apart from the pre-existing convention-only corpus. This is a command
+ * recorder, deliberately not a test-runner framework.
+ *
+ * Output size is measured in bytes by the shell (`wc -c`), and the TS parser
+ * re-derives nothing — it only reads the recorded number.
+ */
+export interface CaptureRecord {
+    command: string;
+    exitCode: number;
+    outputBytes: number;
+}
+export interface CaptureInput {
+    /** Plan bucket, i.e. the plan's file name without `.md`. */
+    plan: string;
+    /** Task identifier, e.g. `task-8`. */
+    task: string;
+    /** Kebab-case slug describing what the command proves. */
+    slug: string;
+    /** The command to run, e.g. `bun run typecheck`. */
+    command: string;
+}
+export declare function evidenceFileName(input: Pick<CaptureInput, "plan" | "task" | "slug">): string;
+export declare function buildCaptureCommand(input: CaptureInput): string;
+export declare function parseCaptureRecord(content: string): CaptureRecord | null;

package/dist/features/completion-review/evidence-notepad.d.ts

@@ -0,0 +1,15 @@
+export interface ParsedNotepad {
+    /** Value of the `**Task ID**` marker, or null when the marker is absent. */
+    taskId: string | null;
+    /** True only when a `## Completion` stamp carries `status: completed`. */
+    completed: boolean;
+    /** `completed_at` from the stamp, or null when unreadable. */
+    completedAt: string | null;
+}
+/**
+ * Parse notepad content into the facts a reviewer needs. Total: any string
+ * parses, and a file with neither marker yields `{ taskId: null, completed:
+ * false }` rather than throwing — a truncated notepad is missing evidence, not
+ * a crash.
+ */
+export declare function parseNotepad(content: string): ParsedNotepad;

package/dist/features/completion-review/evidence-resolve.d.ts

@@ -0,0 +1,18 @@
+import type { DoDEvidence } from "./evidence-types";
+/**
+ * Resolve one DoD line to an outcome plus its provenance.
+ *
+ * The honesty rule lives here: only a machine-written completion yields `pass`.
+ * No evidence — or evidence that is merely a file's existence — yields
+ * `unverifiable`, never `pass` and never `fail`. `fail` stays in the union for
+ * callers that can observe a negative terminal state, but this function has no
+ * way to distinguish one and deliberately emits no fabricated failures.
+ */
+export declare function resolveDoDEvidence(input: {
+    itemId: string;
+    notepad: {
+        taskId: string | null;
+        completed: boolean;
+    } | null;
+    evidenceFiles: readonly string[];
+}): DoDEvidence;

package/dist/features/completion-review/evidence-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Evidence vocabulary for the completion reviewer (dimension 1).
+ *
+ * The corpus in `.matrixx/evidence/` predates any capture helper — no program
+ * in this repo writes there, so every pre-existing file is convention only.
+ * The three provenance classes below are deliberately distinct strings so a
+ * report can state, per DoD item, exactly how strong the backing is.
+ */
+export declare const EVIDENCE_PROVENANCE: {
+    /** A notepad written by `task-notepad-writer` carrying a `## Completion` stamp. */
+    readonly NOTEPAD: "notepad (machine-written)";
+    /** A file exists, but nothing proves a program wrote or validated it. */
+    readonly CONVENTION_FILE: "file presence only (convention)";
+    /** Nothing at all backs the item. */
+    readonly NONE: "none";
+};
+export type EvidenceProvenance = (typeof EVIDENCE_PROVENANCE)[keyof typeof EVIDENCE_PROVENANCE];
+/**
+ * `unverifiable` is a first-class outcome, distinct from both `pass` and
+ * `fail`. It means the reviewer found no evidence either way and refuses to
+ * manufacture confidence. A DETERMINISTIC rubric dimension must therefore be
+ * able to express "no evidence" as data rather than by throwing.
+ */
+export type EvidenceOutcome = "pass" | "fail" | "unverifiable";
+export interface DoDEvidence {
+    /** Identifier of the DoD line this resolves. */
+    itemId: string;
+    outcome: EvidenceOutcome;
+    provenance: EvidenceProvenance;
+    /** Task ID from the notepad marker, when a machine-written notepad backs it. */
+    taskId: string | null;
+    /** Evidence file names considered, in input order. */
+    evidenceFiles: readonly string[];
+}

package/dist/features/completion-review/gather-attribution.d.ts

@@ -0,0 +1,36 @@
+import type { MatrixxConfig } from "../../config/schema";
+import type { MissionState } from "../mission-state/types";
+import type { AttributionFacts, LinkedTerminalTask } from "./gather-types";
+/**
+ * Dimensions whose INPUT is task-level attribution. On an incomplete
+ * attribution these degrade to `unscorable` — they are never scored.
+ */
+export declare const ATTRIBUTION_DEPENDENT_DIMENSIONS: readonly number[];
+export declare const ATTRIBUTION_INCOMPLETE_REASON = "attribution incomplete \u2014 linked terminal tasks do not account for the plan's tasks";
+export interface LinkedTaskScan {
+    linkedTerminalTasks: LinkedTerminalTask[];
+    linkedTotal: number;
+}
+/**
+ * The 6-rule resolver is the shipped algorithm and is imported, never
+ * reimplemented. The file scan around it is the only local logic: task files
+ * come from `listTaskFiles` and are strict-parsed by `TaskObjectSchema`, so a
+ * malformed file is invisible rather than a silent vote.
+ */
+export declare function scanLinkedTasks(directory: string, mission: MissionState, config?: Partial<MatrixxConfig>): LinkedTaskScan;
+/**
+ * The attribution-completeness arithmetic. Data, not a verdict: the caller
+ * decides what an incomplete ratio means, and the required behaviour on
+ * mismatch is DEGRADE (see `ATTRIBUTION_DEPENDENT_DIMENSIONS`).
+ */
+export declare function computeAttribution(linkedTerminal: number, planTasks: number): AttributionFacts;
+/**
+ * Degrade — never score. Every attribution-dependent dimension is marked
+ * `unscorable` when linked terminal tasks do not account for the plan's tasks.
+ * A ratio of 0 degrades exactly the same set; there is no partial credit
+ * because a partially-grounded dimension is an ungrounded dimension.
+ */
+export declare function computeDegradation(attribution: AttributionFacts): {
+    unscorableDimensions: number[];
+    reasons: Record<string, string>;
+};

package/dist/features/completion-review/gather-drift.d.ts

@@ -0,0 +1,16 @@
+import type { DriftFacts, GitRunner } from "./gather-types";
+export declare const NO_START_COMMIT_REASON = "plan records no start commit";
+/** Default runner. Read-only commands only; nothing here mutates the worktree. */
+export declare const defaultGitRunner: GitRunner;
+/**
+ * The plan's recorded start commit, from the `plan-persister` metadata comment
+ * written by `upsertMetadataComment`. Read through the shipped parser so the
+ * tag format has one owner.
+ */
+export declare function readStartCommit(content: string): string | null;
+/**
+ * Diff the plan's start commit against the worktree. When the plan records no
+ * start commit the result is EXPLICITLY unscorable — not an empty diff, which
+ * would read as "no drift" and silently pass dimension 5.
+ */
+export declare function gatherDrift(content: string, directory: string, runGit: GitRunner, startCommitOverride?: string): DriftFacts;

package/dist/features/completion-review/gather-notepads.d.ts

@@ -0,0 +1,13 @@
+import { taskIdMarkerLine } from "../../hooks/task-notepad-writer/constants";
+import type { NotepadRecord } from "./gather-types";
+export declare function readNotepad(file: string): NotepadRecord | null;
+/**
+ * Read every notepad in `<notepadDir>/`. A missing directory yields `[]` — the
+ * bucket for a plan is only created once a notepad is written, so "no bucket"
+ * is the normal case, not an error.
+ */
+export declare function gatherNotepads(notepadDir: string): NotepadRecord[];
+/** Notepads whose `**Task ID**` marker matches, keyed by that marker. */
+export declare function matchNotepadsByTaskId(records: NotepadRecord[]): Map<string, NotepadRecord>;
+/** The marker line itself, exported so a test can pin the exact contract. */
+export { taskIdMarkerLine };