opencode-matrixx-v2 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,109 @@
+/**
+ * Task 2 — data shapes for the deterministic completion-review gatherer.
+ *
+ * Types only. Every value here is a FACT, never a verdict: the gatherer
+ * reports what it read and how soft it is, and the rubric (T5) and the report
+ * writer (T6) decide what a fact means.
+ */
+import type { PlanProgress } from "../mission-state/types";
+import type { PlanTask } from "../plan-contract/types";
+/**
+ * Why an input is soft.
+ *
+ * `kind` guarantees the ARITHMETIC is code. It says nothing about whether the
+ * INPUTS are grounded. Purity and provenance are orthogonal; `attribution`
+ * below is what supplies provenance.
+ */
+export type Provenance = "heuristic" | "measured" | "recorded";
+export interface GatherProvenance {
+    /** Task→plan linkage is a convention, not a foreign key. */
+    linkage: Provenance;
+    /** `checkboxOverlap` reconciliation is best-effort, never ground truth. */
+    checkboxSync: Provenance;
+}
+export interface ProgressFacts extends PlanProgress {
+    remaining: number;
+}
+/**
+ * Attribution completeness — the REQUIRED provenance check.
+ *
+ * `linkedTerminal` comes from the 6-rule resolver at
+ * `plan-persister/task-link.ts`; `planTasks` is the plan's own numbered task
+ * count. When they disagree, the caller DEGRADES the attribution-dependent
+ * dimensions to `unscorable`. It never scores them on partial evidence.
+ */
+export interface AttributionFacts {
+    linkedTotal: number;
+    linkedTerminal: number;
+    planTasks: number;
+    /** `linkedTerminal / planTasks`, or 0 when the plan has no tasks. */
+    ratio: number;
+    /** True only when `linkedTerminal` accounts for every plan task. */
+    matches: boolean;
+}
+export interface LinkedTerminalTask {
+    id: string;
+    status: string;
+    terminal: boolean;
+}
+export interface NotepadRecord {
+    taskId: string | null;
+    file: string;
+    hasCompletionStamp: boolean;
+    results: string;
+}
+/**
+ * Admission corroboration — two INDEPENDENT inputs for T10's gate, gathered
+ * here so the gate is a pure conjunction over collected facts and never a
+ * second, divergent gatherer. Never derived from `isComplete`.
+ */
+export interface AdmissionFacts {
+    linkedTerminalTasks: LinkedTerminalTask[];
+    notepadCompletionStamps: string[];
+    notepads: NotepadRecord[];
+    corroborationCount: number;
+}
+export interface ChangedFile {
+    status: string;
+    path: string;
+}
+export interface DriftFacts {
+    startCommit: string | null;
+    stat: string | null;
+    nameStatus: ChangedFile[];
+    /** True when the plan records no start commit — dimension 5 is unscorable. */
+    unscorable: boolean;
+    unscorableReason: string | null;
+}
+export interface DegradationFacts {
+    unscorableDimensions: number[];
+    reasons: Record<string, string>;
+}
+export interface GatheredReviewInputs {
+    planPath: string;
+    planName: string;
+    bytes: number;
+    provenance: GatherProvenance;
+    progress: ProgressFacts;
+    tasks: PlanTask[];
+    dod: string[];
+    attribution: AttributionFacts;
+    admission: AdmissionFacts;
+    drift: DriftFacts;
+    degradation: DegradationFacts;
+}
+/** Read-only command runner for `git`. Injected so the gatherer stays pure. */
+export type GitRunner = (args: string[]) => string;
+export interface GatherSources {
+    /** Project root. Everything else is resolved beneath it. */
+    directory: string;
+    /** Defaults to the newest reviewable plan. */
+    planPath?: string;
+    /** Defaults to `.matrixx/notepads/<planName>`. */
+    notepadDir?: string;
+    /** Session ids the plan has been worked under; a linkage signal. */
+    sessionIds?: string[];
+    /** Overrides the recorded start commit (used by tests). */
+    startCommit?: string;
+    runGit?: GitRunner;
+}

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

@@ -0,0 +1,18 @@
+import type { GatheredReviewInputs, GatherSources } from "./gather-types";
+export declare const NOTEPADS_DIR = ".matrixx/notepads";
+export { ATTRIBUTION_DEPENDENT_DIMENSIONS, ATTRIBUTION_INCOMPLETE_REASON, computeAttribution, computeDegradation, scanLinkedTasks, } from "./gather-attribution";
+export { defaultGitRunner, gatherDrift, NO_START_COMMIT_REASON, readStartCommit } from "./gather-drift";
+export { gatherNotepads, matchNotepadsByTaskId, readNotepad } from "./gather-notepads";
+export type * from "./gather-types";
+/**
+ * Every `.matrixx/plans/*.md` a reviewer may consider. `_archive/` is filtered
+ * out by the shared lister, so a stale archived plan can never be scored.
+ */
+export declare function gatherReviewablePlans(directory: string): string[];
+/**
+ * Assemble every code-computable input the rubric needs. Library only — this
+ * has no hook, idle, or event-handler caller by design.
+ */
+export declare function gatherCompletionReviewInputs(sources: GatherSources): GatheredReviewInputs;
+/** Concatenated comment lines of every `gather*` source file. */
+export declare function readGatherSourceComments(dir: string): string;

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

@@ -0,0 +1,35 @@
+/**
+ * Completion-review barrel.
+ *
+ * This file previously claimed "T8 owns the `evidence*` prefix and adds its own
+ * re-exports here". T8 did not touch it, so that comment was false and
+ * `resolveDoDEvidence`, `EVIDENCE_PROVENANCE` and `DoDEvidence` were unreachable
+ * from the barrel. The re-exports are here now, and the comment is corrected
+ * rather than left to mislead the next reader.
+ *
+ * The `report*` and `calibration*` re-exports are now here (T10 added them once
+ * both modules had shipped and QA passed).
+ *
+ * Two things are deliberately named rather than `export *`:
+ *
+ * 1. `ReviewInput` exists TWICE under two unrelated meanings — T6's evaluator
+ *    input and T4's renderer input — so forwarding both would make the barrel's
+ *    `ReviewInput` ambiguous. The evaluator's is the one the barrel exposes.
+ * 2. `calibration-corpus` re-exported wholesale: its surface (`readCalibrationCorpus`,
+ *    `CorpusReport` and friends) collides with nothing else in this barrel, so
+ *    there is no reason to name it piecemeal.
+ */
+export * from "./calibration";
+export * from "./calibration-corpus";
+export * from "./degradation";
+export * from "./evidence-capture";
+export * from "./evidence-notepad";
+export * from "./evidence-resolve";
+export * from "./evidence-types";
+export * from "./gather";
+export { renderReviewReport } from "./report";
+export { buildReviewSidecar } from "./report-sidecar";
+export { classifyFindings } from "./report-taxonomy";
+export { ADVISORY_NOTICE, type CoverageClass, type DimensionOutcome, type FindingCode, type GateEvidence, type GateState, REVIEW_SIDECAR_VERSION, type ReviewCalibration, type ReviewDimension, type ReviewFinding, type ReviewGate, type ReviewProvenance, type ReviewScoreHeadline, type ReviewSidecar, type ReviewSidecarDimension, } from "./report-types";
+export { buildReviewDirCommand, REVIEWS_DIR, type ReviewWriteResult, reviewReportPath, reviewSidecarPath, writeReviewReport } from "./report-write";
+export * from "./rubric";

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

@@ -0,0 +1,29 @@
+/**
+ * Task 4 — the admission gate, as a PURE function over two gathered facts.
+ *
+ * LOCKED decision #2 applies to this file most sharply: the gate has NO
+ * consumer in code. It is rendered because the DoD mandates it, and it must
+ * therefore never become a control-flow branch. `deriveGateState` returns data;
+ * nothing branches on it, nothing exits non-zero, nothing blocks.
+ *
+ * The two independent signals are `progress.isComplete` (the plan's own
+ * checkboxes) and `admission.corroborationCount` (task-store terminal records
+ * plus machine-written notepad completion stamps). `corroborationCount >= 2`
+ * means they were corroborated by both.
+ *
+ * The two failure modes are kept APART on purpose:
+ *
+ * - `disagree` — one signal says the work is finished and the other does not.
+ *   That is a finding about the plan, and it is rendered by name.
+ * - `unavailable` — corroboration is STRUCTURALLY absent (0 or 1 of 2 signals),
+ *   so there is nothing to disagree with. This is the vacuous case T2 calls out:
+ *   a zero-task plan reports `isComplete: true` with zero corroboration.
+ *
+ * Collapsing them would be a lie: "unavailable" is not "the signals conflict",
+ * it is "the signals were never there".
+ */
+import type { AdmissionFacts, ProgressFacts } from "./gather-types";
+import type { ReviewGate } from "./report-types";
+export declare function deriveGateState(progress: ProgressFacts, admission: AdmissionFacts): ReviewGate;
+/** The vacuous case T2 calls out: a zero-task plan reports complete with nothing to back it. */
+export declare function needsTriageNote(progress: ProgressFacts): string;

package/dist/features/completion-review/report-sidecar.d.ts

@@ -0,0 +1,2 @@
+import { type ReviewInput, type ReviewSidecar } from "./report-types";
+export declare function buildReviewSidecar(input: ReviewInput): ReviewSidecar;

package/dist/features/completion-review/report-summary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Task 4 — the Summary section, built from FACTS.
+ *
+ * 3–5 sentences, no adjectives the facts do not support. The sentences are
+ * assembled by concatenation from the gathered counters, which keeps the whole
+ * renderer pure: no model call, no clock, no randomness. A wording change is a
+ * diff a reviewer can read; a model paraphrase is not.
+ */
+import type { ReviewInput } from "./report-types";
+export declare function renderSummary(input: ReviewInput): string[];

package/dist/features/completion-review/report-taxonomy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Task 4 — the E1–E6 error taxonomy.
+ *
+ * Six codes, six DISTINCT causes, each attached to the dimension it belongs to.
+ * The point of a code is that a corpus reader can count causes across hundreds
+ * of reports without a model reading prose — so the mapping must be a total,
+ * deterministic function of the dimension results, not a judgement call.
+ *
+ * The invariant this file exists to keep: EVERY dimension scored down carries a
+ * code. A dimension that scored below 1 with no code would be a silent finding
+ * the reader cannot count, which is the failure mode the taxonomy was invented
+ * to prevent.
+ *
+ * Codes are derived, never supplied. `classifyFindings` reads the dimension
+ * `signals` T5 already computes, so this file adds no judgement of its own.
+ */
+import type { AttributionFacts } from "./gather-types";
+import type { ReviewDimension, ReviewFinding } from "./report-types";
+export declare function classifyFindings(dimensions: readonly ReviewDimension[]): ReviewFinding[];
+/** Attribution mismatch is a plan-level observation, not a scored dimension. */
+export declare function attributionMismatch(attribution: AttributionFacts): boolean;

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

@@ -0,0 +1,142 @@
+/**
+ * Task 4 — the shapes the report renderer consumes, and the versioned `.json`
+ * sidecar contract T9 reads.
+ *
+ * WHY THE FOUR PARTS EXIST: Summary, Score, Complexity and Required Effort are
+ * the USER'S EXPLICIT format requirement (plan step 4). They are not this
+ * module's invention and the renderer emits all four unconditionally, each
+ * under its own `##` heading. If one is missing the report is wrong regardless
+ * of what else it says.
+ *
+ * WHY THE REPORT IS WRITTEN OUT OF THE PLAN FILE: the plan is a record of
+ * INTENT AND PROGRESS. A report appended to it corrupts both — the plan stops
+ * describing what was planned, and the progress counters absorb prose they were
+ * never meant to count. Every mature precedent splits the two: create-plan /
+ * ravdeepss writes `plans/{NAME}_PROGRESS.json`, Goose writes a separate
+ * `PROGRESS.md`, precisely to avoid parallel-subagent write conflicts on the
+ * file agents edit. Splitting also removes the write-headroom problem that
+ * motivated Plan A. Nothing in this feature may open the plan for writing.
+ *
+ * WHY A `.json` SIDECAR: the corpus reader (T9) must aggregate hundreds of
+ * reviews without parsing prose. A regex over markdown is a contract that
+ * breaks on the first reworded sentence; a versioned object does not.
+ *
+ * RECONCILIATION NOTE (T6, concurrent): `not_scorable` rendering is owned by
+ * T6's degradation module. The renderer here consumes a *structural* union —
+ * `outcome: "scored" | "unscorable" | "unverifiable"` — and renders every arm,
+ * emitting no number whenever `outcome !== "scored"`. T6's `not_scorable`
+ * result maps onto `outcome: "unscorable"` with its `reason` as the rationale,
+ * so the two agree by construction; T10 must pass T6's reasons through as
+ * `rationale`, not invent its own.
+ */
+import type { EvidenceProvenance } from "./evidence-types";
+import type { AdmissionFacts, AttributionFacts, GatherProvenance, ProgressFacts } from "./gather-types";
+import type { ApbGrade } from "./rubric-score";
+/** Semver of the `.json` sidecar shape. Bump on ANY breaking field change. */
+export declare const REVIEW_SIDECAR_VERSION = "1.0.0";
+/** Rendered verbatim near the top of every report. See LOCKED decision #2. */
+export declare const ADVISORY_NOTICE = "**A low score is advisory, not a gate.** This report has no exit code, no blocking error and no contract rule; nothing in the pipeline halts, retries or rejects a plan because of the number below.";
+/** `post-capture` plans have machine-written evidence; `legacy` ones predate it. */
+export type CoverageClass = "post-capture" | "legacy";
+/**
+ * A dimension's outcome. `unscorable` and `unverifiable` are DISTINCT and both
+ * emit no number: the first means the dimension could not be computed, the
+ * second means it was computed and the evidence behind it was absent.
+ */
+export type DimensionOutcome = "scored" | "unscorable" | "unverifiable";
+export interface ReviewDimension {
+    index: number;
+    id: string;
+    title: string;
+    kind: "DETERMINISTIC" | "MODEL";
+    weight: number;
+    outcome: DimensionOutcome;
+    /** 0..1, or `null` for any non-`scored` outcome. */
+    score: number | null;
+    /** One line. For a non-`scored` outcome this is the `reason`. */
+    rationale: string;
+    /** The dimension's own counters (T5's `DimensionSignals`), when it reported any. */
+    signals?: Readonly<Record<string, number | boolean | string | undefined>>;
+}
+/** T7 owns the CONTENT of these two; this module only renders them. */
+export interface ReviewCalibration {
+    /** Plan-time estimate, verbatim. `null` when the plan recorded none. */
+    planned: string | null;
+    /** Observed effort, verbatim. `null` when nothing observed it. */
+    observed: string | null;
+    /** `under` / `over` / `on-target`, or `null` when not comparable. */
+    comparison: string | null;
+    note: string;
+}
+export type GateState = "agree" | "disagree" | "unavailable";
+export type GateEvidence = "corroborated" | "unavailable";
+export interface ReviewGate {
+    state: GateState;
+    evidence: GateEvidence;
+    corroborationCount: number;
+    detail: string;
+}
+export type FindingCode = "E1" | "E2" | "E3" | "E4" | "E5" | "E6";
+export interface ReviewFinding {
+    code: FindingCode;
+    dimensionId: string;
+    detail: string;
+}
+export interface ReviewProvenance {
+    gather: GatherProvenance;
+    evidence: readonly EvidenceProvenance[];
+}
+export interface ReviewScoreHeadline {
+    value: number;
+    grade: ApbGrade;
+    /** Sum of weights that produced a number; below 1 means partial measurement. */
+    scoredWeight: number;
+    dimensionCount: number;
+}
+export interface ReviewInput {
+    planPath: string;
+    planName: string;
+    /**
+     * ISO-8601, supplied by the caller. NEVER `new Date()` inside the renderer —
+     * a clock read in a pure function makes two renders of identical input
+     * differ, which is exactly the diff T9 needs to be able to make.
+     */
+    generatedAt: string;
+    coverageClass: CoverageClass;
+    progress: ProgressFacts;
+    admission: AdmissionFacts;
+    attribution: AttributionFacts;
+    provenance: ReviewProvenance;
+    score: ReviewScoreHeadline;
+    /** ALL 8 dimensions, in index order. A missing row shrinks the rubric. */
+    dimensions: readonly ReviewDimension[];
+    complexity: ReviewCalibration;
+    effort: ReviewCalibration;
+    findings: readonly ReviewFinding[];
+}
+/** Per-dimension row of the sidecar. Same discriminants as the markdown table. */
+export interface ReviewSidecarDimension {
+    index: number;
+    id: string;
+    kind: "DETERMINISTIC" | "MODEL";
+    weight: number;
+    outcome: DimensionOutcome;
+    score: number | null;
+    rationale: string;
+    codes: FindingCode[];
+}
+export interface ReviewSidecar {
+    sidecarVersion: typeof REVIEW_SIDECAR_VERSION;
+    plan: string;
+    planPath: string;
+    generatedAt: string;
+    coverageClass: CoverageClass;
+    advisory: true;
+    score: ReviewScoreHeadline;
+    dimensions: ReviewSidecarDimension[];
+    findings: ReviewFinding[];
+    gate: ReviewGate;
+    complexity: ReviewCalibration;
+    effort: ReviewCalibration;
+    provenance: ReviewProvenance;
+}

package/dist/features/completion-review/report-write.d.ts

@@ -0,0 +1,22 @@
+import type { ReviewInput } from "./report-types";
+export declare const REVIEWS_DIR = ".matrixx/reviews";
+/** A shell one-liner for the bash tool. Never executed from TypeScript. */
+export declare function buildReviewDirCommand(directory?: string): string;
+export declare function reviewReportPath(planName: string): string;
+export declare function reviewSidecarPath(planName: string): string;
+export interface ReviewWriteResult {
+    ok: boolean;
+    reportPath: string;
+    sidecarPath: string;
+    /** The markdown as written, so a caller can log or test it without re-reading. */
+    markdown: string;
+    sidecarJson: string;
+    /** Non-null only when a write failed; the plan is never implicated. */
+    error: string | null;
+}
+/**
+ * Render and write both artefacts. The markdown and the sidecar are built from
+ * the SAME `ReviewInput` in one call, so the two can never disagree about the
+ * score — the failure mode of writing them from separate passes.
+ */
+export declare function writeReviewReport(input: ReviewInput): ReviewWriteResult;

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

@@ -0,0 +1,9 @@
+import { type ReviewInput } from "./report-types";
+/** Render the full report. Pure: same input, byte-identical output. */
+export declare function renderReviewReport(input: ReviewInput): string;
+export { deriveGateState } from "./report-gate";
+export { buildReviewSidecar } from "./report-sidecar";
+export { renderSummary } from "./report-summary";
+export { classifyFindings } from "./report-taxonomy";
+export type { ReviewInput, ReviewSidecar, ReviewSidecarDimension } from "./report-types";
+export { ADVISORY_NOTICE, REVIEW_SIDECAR_VERSION } from "./report-types";

package/dist/features/completion-review/rubric-dimensions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Task 5 — the eight dimensions, as a tagged table.
+ *
+ * Weights sum to exactly 1.0 so the weighted mean is a mean. The `kind` on each
+ * entry is checked by `checkRubricStructure` and, more importantly, by the type
+ * system: a DETERMINISTIC entry here is only expressible WITH a `compute`.
+ */
+import type { RubricDimension } from "./rubric-types";
+export declare const RUBRIC_DIMENSIONS: readonly RubricDimension[];
+/** The `kind` split as declared, for the structure gate and for tests. */
+export declare const RUBRIC_KIND_PATTERN: readonly RubricDimension["kind"][];

package/dist/features/completion-review/rubric-dod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Task 5 — dimension 1, DoD coverage, with the all-pass / avg-pass GAP.
+ *
+ * PlanningBench's finding is that the two metrics diverge sharply: a plan can
+ * pass every check or pass most of them, and only the mean hides how close a
+ * plan came to a total miss. The gap is therefore computed and returned here,
+ * not left for a caller to re-derive from `allPass` and `avgPass`.
+ */
+import type { DeterministicInputs, DoDCoverageResult } from "./rubric-types";
+export declare function computeDoDCoverage(input: DeterministicInputs): DoDCoverageResult;

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

@@ -0,0 +1,6 @@
+/**
+ * Task 5 — dimension 5, deliverable drift: the plan's Concrete Deliverables
+ * H3 against the actual `git diff` the gatherer already collected.
+ */
+import type { DeterministicInputs, DimensionResult } from "./rubric-types";
+export declare function computeDeliverableDrift(input: DeterministicInputs): DimensionResult;

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

@@ -0,0 +1 @@
+export declare function checkRubricStructure(dimensions: readonly unknown[]): string[];

package/dist/features/completion-review/rubric-score.d.ts

@@ -0,0 +1,16 @@
+import type { DeterministicInputs, DimensionResult, RubricDimension } from "./rubric-types";
+/** The APB discrete ladder. A grade is always one of these. */
+export type ApbGrade = 0 | 0.2 | 0.4 | 0.6 | 0.8 | 1;
+export interface RubricScore {
+    /** Weighted mean over the SCORED dimensions, 0..1. */
+    score: number;
+    /** Sum of the weights that actually produced a score. Below 1 means partial. */
+    scoredWeight: number;
+    grade: ApbGrade;
+    unscorable: string[];
+    results: Record<string, DimensionResult>;
+}
+/** Round UP to the next rung on the ladder, except that 0 stays 0. */
+export declare function apbGrade(score: number): ApbGrade;
+export declare function totalWeight(dimensions?: readonly RubricDimension[]): number;
+export declare function scoreRubric(dimensions: readonly RubricDimension[], input: DeterministicInputs, modelScores?: Partial<Record<string, number>>): RubricScore;

package/dist/features/completion-review/rubric-test-decision.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Task 5 — dimension 7, whether the plan's own Test Decision held in execution.
+ *
+ * A plan that declared TDD required and produced no test file has broken its
+ * own decision. A plan that declared no TDD has nothing to honour, which is a
+ * pass on the DECISION, not a pass on quality — the signal records which.
+ */
+import type { DeterministicInputs, DimensionResult } from "./rubric-types";
+export declare function computeTestDecisionHonored(input: DeterministicInputs): DimensionResult;

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

@@ -0,0 +1,87 @@
+/**
+ * Task 5 — rubric types. The `kind` tag is enforced HERE, by the type system.
+ *
+ * The canonical shape is a discriminated union on `kind`: the DETERMINISTIC
+ * variant REQUIRES `compute`, the MODEL variant FORBIDS it. There is therefore
+ * no shape that can be tagged deterministic without a code implementation, and
+ * no shape that can smuggle a model-informed observed side in under a MODEL
+ * tag. Both errors are compile errors, not conventions.
+ *
+ * Purity is enforced the same way: `compute` accepts `DeterministicInputs`,
+ * which is a Pick over the gatherer's FACT types only. No prose field, no
+ * judgement callback and no model read is reachable from it. A dimension that
+ * wants one is a MODEL dimension — the sanctioned fix is a RE-TAG, never a
+ * widened `compute`.
+ */
+import type { DoDEvidence } from "./evidence-types";
+import type { GatheredReviewInputs } from "./gather-types";
+/** The Test Decision H3, reduced to a fact. `null` when the section is absent. */
+export interface TestDecisionFacts {
+    plannedTdd: boolean;
+    declaredTaskCount: number;
+}
+/** Test files observed in the diff. `null` when the caller gathered nothing. */
+export interface TestObservationFacts {
+    testFiles: number;
+    tddMarkedTests: number;
+}
+/**
+ * Everything a deterministic dimension is allowed to read.
+ *
+ * A `Pick` of the gatherer's fact types plus two caller-supplied structural
+ * extracts. `tasks` and `admission` are deliberately absent — dimension 1 uses
+ * `dod` and `evidence`, and a dimension needing a free-text field cannot be
+ * spelled here, which is the point.
+ */
+export type DeterministicInputs = Pick<GatheredReviewInputs, "dod" | "progress" | "attribution" | "drift" | "degradation"> & {
+    evidence: readonly DoDEvidence[];
+    /** File paths named in the Concrete Deliverables H3; `null` when absent. */
+    declaredDeliverables: readonly string[] | null;
+    testDecision: TestDecisionFacts | null;
+    tests: TestObservationFacts | null;
+};
+/** Extra counters a dimension reports next to its score. Never a verdict. */
+export interface DimensionSignals {
+    [key: string]: number | boolean | string | undefined;
+}
+export interface ScoredResult {
+    status: "scored";
+    /** 0..1, continuous. */
+    score: number;
+    signals?: DimensionSignals;
+}
+export interface UnscorableResult {
+    status: "unscorable";
+    reason: string;
+}
+/** A `compute` never throws; inability to measure is a value, not an exception. */
+export type DimensionResult = ScoredResult | UnscorableResult;
+/** Dimension 1's precise return: the all-pass / avg-pass GAP is a first-class field. */
+export type DoDCoverageResult = UnscorableResult | (ScoredResult & {
+    allPass: boolean;
+    avgPass: number;
+    gap: number;
+    dodTotal: number;
+    passed: number;
+    failed: number;
+    unverifiable: number;
+});
+interface DimensionBase {
+    /** 1-based plan dimension number. */
+    index: number;
+    id: string;
+    title: string;
+    weight: number;
+    description: string;
+}
+export interface DeterministicDimension extends DimensionBase {
+    kind: "DETERMINISTIC";
+    compute: (input: DeterministicInputs) => DimensionResult;
+}
+export interface ModelDimension extends DimensionBase {
+    kind: "MODEL";
+    /** Forbidden: a model read cannot be code-computed. */
+    compute?: undefined;
+}
+export type RubricDimension = DeterministicDimension | ModelDimension;
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * Task 5 — the 8-dimension completion-review rubric.
+ *
+ * Three benchmarks shape this rubric, and each owns a different part of it:
+ *
+ * - **PlanBench** decomposes planning quality PER CAPABILITY rather than into a
+ *   single verdict, and asks whether acceptance criteria are checkable at all
+ *   (dimension 6) and whether the plan's own guardrails survived execution
+ *   (dimension 2). It is the reason this is eight dimensions and not a score.
+ * - **PlanningBench** found that **All-pass and Avg-pass diverge sharply**: a
+ *   plan can pass most checks while failing the one that mattered, and only the
+ *   mean hides that. Dimension 1 therefore returns `allPass`, `avgPass` and the
+ *   GAP between them as first-class fields. The gap is the finding, not the mean.
+ * - **APB** grades a plan on a DISCRETE ladder. `apbGrade` emits the coarse
+ *   companion {0, .2, .4, .6, .8, 1} next to the continuous 0..1 score, so a
+ *   reader who rounds 0.83 by hand still lands on the same rung.
+ *
+ * The `kind` tag is load-bearing and is enforced by the TYPE SYSTEM, not by
+ * convention. `RubricDimension` is a discriminated union: the DETERMINISTIC
+ * variant REQUIRES `compute`, the MODEL variant FORBIDS it. A dimension cannot
+ * be mis-tagged without a `tsc` error, and a `compute` cannot reach a prose
+ * field because its parameter type is a `Pick` over the gatherer's fact types.
+ * The sanctioned fix for a dimension that cannot be made pure is a RE-TAG to
+ * MODEL — never a widened `compute`, and never an unimplemented deterministic
+ * dimension. Dimension 8 was re-tagged that way during the review pass.
+ *
+ * Degradation is data. `EvidenceOutcome` includes `unverifiable`, so a DoD item
+ * with no machine-written evidence is never scored as a failure: dimension 1
+ * counts it separately and, when NOTHING is verifiable, returns `unscorable`
+ * with a reason instead of a fabricated 0. T6 renders these; T5 declares them.
+ *
+ * A low score is a finding, never a blocking failure. This module has no
+ * process.exit, no threshold that halts anything, and no side effect at all.
+ */
+export { RUBRIC_DIMENSIONS, RUBRIC_KIND_PATTERN } from "./rubric-dimensions";
+export { computeDoDCoverage } from "./rubric-dod";
+export { computeDeliverableDrift } from "./rubric-drift";
+export { checkRubricStructure } from "./rubric-gate";
+export type { ApbGrade, RubricScore } from "./rubric-score";
+export { apbGrade, scoreRubric, totalWeight } from "./rubric-score";
+export { computeTestDecisionHonored } from "./rubric-test-decision";
+export type { DeterministicDimension, DeterministicInputs, DimensionResult, DimensionSignals, DoDCoverageResult, ModelDimension, RubricDimension, ScoredResult, TestDecisionFacts, TestObservationFacts, UnscorableResult, } from "./rubric-types";

package/dist/features/context-injector/collector.d.ts

@@ -0,0 +1,13 @@
+import type { PendingContext, RegisterContextOptions } from "./types";
+export declare const MAX_MERGED_CHARS = 6000;
+export declare const MAX_PER_SOURCE_CHARS = 2000;
+export declare class ContextCollector {
+    private sessions;
+    register(sessionID: string, options: RegisterContextOptions): void;
+    getPending(sessionID: string): PendingContext;
+    consume(sessionID: string): PendingContext;
+    clear(sessionID: string): void;
+    hasPending(sessionID: string): boolean;
+    private sortEntries;
+}
+export declare const contextCollector: ContextCollector;

package/dist/features/context-injector/index.d.ts

@@ -0,0 +1,3 @@
+export { ContextCollector, contextCollector, MAX_MERGED_CHARS, MAX_PER_SOURCE_CHARS } from "./collector";
+export { createContextInjectorMessagesTransformHook, } from "./injector";
+export type { ContextEntry, ContextPriority, ContextSourceType, InjectionStrategy, MessageContext, OutputParts, PendingContext, RegisterContextOptions, } from "./types";

package/dist/features/context-injector/injector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Local legacy `{info, parts}` shapes (Task 27: the V1 `experimental.chat.messages.transform`
+ * fan-out is deleted, so `legacy V1 SDK` message types are no longer imported).
+ * The live native port operates on flat `Message[]` in `src/plugin/message-hooks/`.
+ */
+type Message = {
+    id?: string;
+    sessionID?: string;
+    role?: string;
+    [key: string]: unknown;
+};
+type Part = {
+    type?: string;
+    text?: string;
+    [key: string]: unknown;
+};
+import type { ContextCollector } from "./collector";
+interface MessageWithParts {
+    info: Message;
+    parts: Part[];
+}
+type MessagesTransformHook = {
+    "experimental.chat.messages.transform"?: (input: Record<string, never>, output: {
+        messages: MessageWithParts[];
+    }) => Promise<void>;
+};
+export declare function createContextInjectorMessagesTransformHook(collector: ContextCollector): MessagesTransformHook;
+export {};