codecartographer-pi 0.18.0 → 0.19.0

package/.codecarto/GUIDE.md

@@ -215,6 +215,13 @@ post_pipeline:
 
 `kind` is one of: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`, or a post-pipeline work kind such as `spike` or `amendment`. Every new `carry_forward.target_phase` must be an ID in the active pipeline. Every `post_pipeline` entry requires a stable ID. Open questions should carry a stable `id` (e.g. `q-loadconfig-ambiguity`); if omitted, the framework auto-assigns one. When a later phase resolves an open question, list its id in `open_question_closures` to remove it from all phases. The downstream phase records resolved carry-forward IDs in `carry_forward_closures`; completion removes those entries atomically.
 
+**Closing a routed item does not settle the question it came from.** A phase routinely registers an open question and routes one of its candidate answers onward in the same handoff; addressing the routed item later is not the same as answering the question. Two optional fields make that distinction enforceable:
+
+- A `carry_forward` entry may name `derives_from: <open-question-id>`, meaning "this routed item is one candidate answer to that question." Fill it in the handoff that registers the question, when both entries are in front of you. Completion then refuses a `carry_forward_closures` entry for that item while its question is still open and is not closed by the same handoff, naming both ids. Close the question with evidence in that handoff, or leave the item routed and give the finding an unsettled action (`verify at runtime`). Entirely opt-in: a `carry_forward` entry without `derives_from` closes exactly as it always has.
+- An `open_question_closures` entry may be written as `{ id, evidence }` instead of a bare id, where `evidence` names what settled the question. For a question whose `kind` is `needs-runtime-test`, non-empty `evidence` is **required** — such a question closes on a spike report or an observation against the running system, not on another read of the same source — and that requirement holds however the closure is written, so a bare id no longer closes a runtime question. Questions of every other kind are unaffected, and a bare id stays valid for them. The requirement follows the scaffold: a workspace at scaffold version 0.19.0 or newer has the closure refused, while an older scaffold — which never documented the rule — gets a non-gating note, and refreshing the scaffold opts it in.
+
+Completed phases' declared coverage gaps travel too: the `Skipped scope` and `Known blind spots` bullets of every completed phase's `## Coverage and limits` section are surfaced in the next phase's orchestrator duties. A finding that lands inside one of those gaps must either close it with cited new evidence of its own or inherit its uncertainty.
+
 After the pipeline completes, the handoff channel closes with it. Post-pipeline resolutions — an open question answered on evidence, a finished `post_pipeline` backlog item — are applied with an **amendment**: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) and run `codecarto_amend` (MCP) or `/codecarto-amend <slug>` (Pi). It updates `workflow/status.yaml` under the same lock completion uses and writes an amendment closeout plus THREAD_LOG entry. Never hand-edit `status.yaml` for this; amendments are refused while the pipeline is still running, so the two channels cannot race.
 
 ## Phase Selection Logic

package/.codecarto/templates/phase-handoff.yaml

@@ -4,9 +4,28 @@ schema_version: 1
 phase_id: <phase-id>
 owner_notes: []
 open_questions: []
+# Items a specific later phase closes. Every entry needs a target_phase naming a
+# downstream phase in the active pipeline. Optional derives_from names the
+# open_questions id this item is one candidate answer to:
+#   - id: mech-CF3
+#     kind: defer-to-phase
+#     target_phase: defect-scan-semantic
+#     derives_from: q-logit-bias-root-cause
+#     description: <the routed item>
+# Fill derives_from in the handoff that registers the question — that is the one
+# moment both entries are in front of you. Closing the routed item later does not
+# settle the question it came from, and completion refuses such a closure while
+# the question is still open and unclosed by the same handoff.
 carry_forward: []
 carry_forward_closures: []
-# Resolved open questions: their IDs are removed from all phases.
+# Resolved open questions: their IDs are removed from all phases. Either a bare
+# id, or an object naming the evidence that settled it:
+#   - q-loadconfig-ambiguity
+#   - id: q-logit-bias-root-cause
+#     evidence: <the spike report or runtime observation that answered it>
+# A question of kind needs-runtime-test requires non-empty evidence — it closes
+# on runtime evidence, not on another read of the same source. Refused from
+# scaffold version 0.19.0; older scaffolds get a non-gating note instead.
 open_question_closures: []
 # Work after the active pipeline: spikes, amendments, deltas, maintainer rulings,
 # or opinionated reruns. Every entry requires a stable id.

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.18.0
+scaffold_version: 0.19.0

package/agent-skill/codecartographer/references/handoff-contract.md

@@ -17,7 +17,7 @@ owner_notes: []                 # 2-3 durable observations; appended to the phas
 open_questions: []              # genuinely unknown, no later phase will close them
 carry_forward: []               # deferred to a specific later phase in this pipeline
 carry_forward_closures: []      # ids of carry_forward entries this phase resolved
-open_question_closures: []      # ids of open questions this phase resolved, removed everywhere
+open_question_closures: []      # open questions this phase resolved, removed everywhere; bare id or {id, evidence}
 post_pipeline: []               # work after the pipeline; every entry needs a stable id
 decisions: []                   # choices made beyond what the prompt specified; completion appends them to DECISIONS.md
 proposed_conventions: []        # patterns proposed for promotion; completion stages them in CONVENTIONS.md
@@ -41,7 +41,7 @@ Omitted arrays default to empty. A malformed collection fails completion without
   deferred_reason: Distinguishing them needs a runtime probe this phase cannot run.
 ```
 
-`carry_forward` entries add `target_phase`:
+`carry_forward` entries add `target_phase`, and optionally `derives_from`:
 
 ```yaml
 - id: arch-CF2
@@ -49,10 +49,18 @@ Omitted arrays default to empty. A malformed collection fails completion without
   target_phase: protocols
   description: MCP endpoints listed by name only; schemas not extracted.
   deferred_reason: Wire-format extraction is the protocols phase's rubric.
+
+- id: mech-CF3
+  kind: defer-to-phase
+  target_phase: defect-scan-semantic
+  derives_from: q-logit-bias-root-cause   # optional: the open question this is one candidate answer to
+  description: The client sends logit_bias as a map; the documented shape is an array.
 ```
 
 Allowed `kind` values: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`.
 
+`derives_from` names an `open_questions` id. Fill it in the handoff that registers the question — a phase that routes a candidate answer onward usually writes both entries at once, which is the one moment both are in front of you. It is optional and additive: a handoff that omits it behaves exactly as before.
+
 `proposed_conventions` entries (optional; omitted defaults to empty):
 
 ```yaml
@@ -81,6 +89,26 @@ Completion then removes the entry atomically. Resolving an open question works t
 
 Re-deferring instead of closing means writing a fresh `carry_forward` entry naming a later `target_phase`.
 
+### Closing a routed item does not settle the question it came from
+
+Addressing what was routed to you is not the same as answering the question that produced it. Two rules make that enforceable:
+
+- **A closure whose `derives_from` question is still open is refused.** If the item you are closing declares `derives_from: <question-id>`, that question is still in `status.yaml`, and this same handoff does not close it, completion refuses and names both ids. Either close the question here with the evidence that settles it, or leave the item routed and give the finding an unsettled action (`verify at runtime`) so it inherits the question's uncertainty. This rule is entirely opt-in — an entry without `derives_from` closes as it always has.
+- **A `needs-runtime-test` question closes on runtime evidence.** Write the closure as an object and say where that evidence lives:
+
+```yaml
+open_question_closures:
+  - q-loadconfig-ambiguity                   # bare id: still valid for any other kind
+  - id: q-logit-bias-root-cause
+    evidence: scratch/spikes/logit-bias.md — probe against llama-server b4321
+```
+
+Non-empty `evidence` is required when the question's `kind` is `needs-runtime-test`, whether the closure is written as a bare id or as an object. It is checked for presence, not judged — a spike report or an observation against the running system is what belongs there, and another read of the same source is not. Questions of every other kind close on a bare id exactly as before.
+
+The requirement is scoped to the scaffold that documents it. A workspace whose `workflow/scaffold-version.yaml` is 0.19.0 or newer has completion refuse such a closure; an older or unversioned scaffold — whose own templates never stated the rule — gets a non-gating `NOTE:` instead, so an in-flight run written against the older contract cannot be stopped by a rule it was never told. Refreshing the scaffold (`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi) opts a workspace in.
+
+Upstream coverage gaps travel the same way, without gating: the `Skipped scope` and `Known blind spots` bullets of every completed phase's `## Coverage and limits` section appear in your phase prompt's orchestrator duties. A finding of yours inside one of those gaps must either close it with cited new evidence or inherit its uncertainty.
+
 ## The failure this prevents
 
 Before completion required a handoff, a phase could finish with empty state and no signal. A real seven-phase run documented five cross-phase routings in its report prose, wrote no handoffs, and completed all seven phases with `carry_forward: []` throughout. Every downstream phase's routed-item intake was empty. The findings survived only because each phase happened to re-read the previous phase's full markdown.

package/dist/core/completion.d.ts

@@ -24,4 +24,19 @@ export declare const CONVENTIONS_PENDING_HEADING = "## Pending proposals";
  * @param content - the file content, or null to read from disk (null when the file is absent).
  */
 export declare function countPendingProposals(workspaceDir: string, content?: string): Promise<number>;
+/**
+ * First scaffold version whose handoff template documents the `{id, evidence}`
+ * closure shape and the runtime-evidence rule (#122, #186).
+ *
+ * A workspace scaffolded before it was never told that closing a
+ * `needs-runtime-test` question requires evidence, so refusing its completion
+ * would apply a rule its own templates do not carry — and could stop an
+ * in-flight `--auto` run on a handoff written against the older contract.
+ * Those workspaces get a warning instead; refreshing the scaffold
+ * (`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi)
+ * opts them in. Same treatment Stage 2's findings pairing check uses.
+ */
+export declare const CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION = "0.19.0";
+/** Whether the runtime-evidence requirement refuses (current scaffold) or warns (older). */
+export declare function closureEvidenceGateActive(scaffoldVersion: string | undefined | null): boolean;
 export declare function completeValidatedPhase(cwd: string, validation: ValidationResult, sourceLabel: string): Promise<CompletionResult>;

package/dist/core/completion.js

@@ -2,7 +2,7 @@ import { appendFile, copyFile, mkdir, readFile, readdir, writeFile } from "node:
 import { join } from "node:path";
 import { getNextEligiblePhase, resolvePhase, validatePhaseOutput } from "./pipeline.js";
 import { applyHandoff, autoAssignIds, buildTerminalNextActions, loadHandoffFile, normalizeStatus } from "./status.js";
-import { dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
+import { compareDottedVersions, dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
  * The Markdown a reader sees: content inside `<!-- -->` blocks removed by a
@@ -233,6 +233,26 @@ async function writeCompletionArtifacts(workspaceDir, phaseId, validation, times
     const { totalPending: totalPendingProposals } = await stageProposedConventions(workspaceDir, phaseId, timestamp, handoff?.proposed_conventions ?? []);
     return { closeoutPath: `.codecarto/closeouts/${closeoutFile}`, decisionsAppended, totalPendingProposals };
 }
+/**
+ * First scaffold version whose handoff template documents the `{id, evidence}`
+ * closure shape and the runtime-evidence rule (#122, #186).
+ *
+ * A workspace scaffolded before it was never told that closing a
+ * `needs-runtime-test` question requires evidence, so refusing its completion
+ * would apply a rule its own templates do not carry — and could stop an
+ * in-flight `--auto` run on a handoff written against the older contract.
+ * Those workspaces get a warning instead; refreshing the scaffold
+ * (`codecarto_refresh_scaffold` on MCP, `/codecarto-refresh-scaffold` on Pi)
+ * opts them in. Same treatment Stage 2's findings pairing check uses.
+ */
+export const CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION = "0.19.0";
+/** Whether the runtime-evidence requirement refuses (current scaffold) or warns (older). */
+export function closureEvidenceGateActive(scaffoldVersion) {
+    if (!scaffoldVersion)
+        return false;
+    const comparison = compareDottedVersions(scaffoldVersion, CLOSURE_EVIDENCE_GATE_SCAFFOLD_VERSION);
+    return comparison !== null && comparison >= 0;
+}
 export async function completeValidatedPhase(cwd, validation, sourceLabel) {
     const initialState = await getWorkspaceState(cwd);
     if (!initialState)
@@ -254,6 +274,7 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 + `plus closeout_summary and optional closeout_content. Then re-run completion.`);
         }
     }
+    const warnings = [];
     if (handoff) {
         const activePhases = new Set(initialState.pipeline.phase_order);
         const sourceIndex = initialState.pipeline.phase_order.indexOf(validation.phaseId);
@@ -267,14 +288,70 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
             if (!entry.id?.trim())
                 throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
         }
+        // Closure integrity, gating (#122, #186). Both checks are deterministic
+        // reads of ids the model wrote itself, so neither can wedge an --auto run
+        // on a heuristic; both sit here, before the lock, alongside the
+        // target_phase check, so a refusal mutates nothing.
+        const questionsById = new Map();
+        const derivesFromById = new Map();
+        for (const phaseState of Object.values(initialState.status.phases)) {
+            for (const entry of phaseState.open_questions ?? []) {
+                if (entry.id)
+                    questionsById.set(entry.id, entry);
+            }
+            for (const entry of phaseState.carry_forward ?? []) {
+                if (entry.id && entry.derives_from)
+                    derivesFromById.set(entry.id, entry.derives_from);
+            }
+        }
+        const closingQuestionIds = new Set(handoff.open_question_closures.map((closure) => closure.id).filter(Boolean));
+        // D1: a routed item that declares `derives_from` is one candidate answer
+        // to that question. Closing it while the question stands is exactly the
+        // contradiction #122 reported — the routed candidate shipped as settled
+        // while the question that said "source alone cannot determine which" was
+        // still open. A derives_from naming an id that no longer exists is fine:
+        // the question was already resolved.
+        for (const closureId of handoff.carry_forward_closures) {
+            const questionId = derivesFromById.get(closureId);
+            if (!questionId || !questionsById.has(questionId))
+                continue;
+            if (closingQuestionIds.has(questionId))
+                continue;
+            throw new Error(`Refusing to complete ${validation.phaseId}: the handoff closes carry_forward ${closureId}, which derives_from open question ${questionId} — and ${questionId} is still unresolved and is not in this handoff's open_question_closures. `
+                + `A routed item is one candidate answer to the question it came from; closing it does not settle the question. `
+                + `Either close ${questionId} in this same handoff with the evidence that settles it, or leave ${closureId} routed and give the finding an unsettled action ("verify at runtime") instead.`);
+        }
+        // D3: a `needs-runtime-test` question closes on runtime evidence, not on
+        // another source read. Requiring the evidence string to be non-empty is
+        // the whole gate — judging what it says stays prose guidance.
+        //
+        // Unlike D1, this one can fire on a handoff that uses none of the new
+        // fields: a bare-string closure was the only shape before this release.
+        // Gating it unconditionally would apply a rule to workspaces whose own
+        // templates never state it, so it is version-gated exactly like Stage
+        // 2's pairing check — refuse on a scaffold that documents the rule, warn
+        // on one that predates it.
+        const evidenceGateActive = closureEvidenceGateActive(initialState.scaffoldVersion);
+        for (const closure of handoff.open_question_closures) {
+            if (questionsById.get(closure.id)?.kind !== "needs-runtime-test")
+                continue;
+            if (closure.evidence?.trim())
+                continue;
+            const detail = `open_question_closures closes ${closure.id}, whose kind is needs-runtime-test, without evidence. `
+                + `A runtime question closes on runtime evidence — a spike report or an observation against the running system — not on a source read. `
+                + `Write the closure as an object: { id: ${closure.id}, evidence: <where that evidence lives> }. If you do not have it, leave the question open.`;
+            if (evidenceGateActive)
+                throw new Error(`Refusing to complete ${validation.phaseId}: ${detail}`);
+            warnings.push(`${detail} Warning only: this workspace's scaffold predates the requirement — refresh it `
+                + `(codecarto_refresh_scaffold on MCP, /codecarto-refresh-scaffold on Pi) to make this gating.`);
+        }
     }
     // Closure integrity (#122, warning only): a handoff can close a carry-forward
     // or open question the report never addressed — "closed in the handoff,
     // resolved nowhere." The id of every claimed closure should appear somewhere
     // in the primary output that claims to resolve it.
-    const warnings = [];
     if (handoff && validation.outputPath) {
-        const closures = [...handoff.carry_forward_closures, ...handoff.open_question_closures].filter((id) => id?.trim());
+        const closures = [...handoff.carry_forward_closures, ...handoff.open_question_closures.map((closure) => closure.id)].filter((id) => id?.trim());
         if (closures.length > 0) {
             const output = await readFile(validation.outputPath, "utf8").catch(() => "");
             const unmentioned = closures.filter((id) => !output.includes(id));

package/dist/core/coverage.d.ts

@@ -0,0 +1,45 @@
+import type { WorkspaceState } from "./types.ts";
+/** The section heading whose bullets this module reads. */
+export declare const COVERAGE_SECTION_HEADING = "Coverage and limits";
+/** The ledger's five fixed bullets, verbatim values with the label stripped. */
+export type CoverageLedger = {
+    inspected_scope: string;
+    skipped_scope: string;
+    evidence_basis: string;
+    known_blind_spots: string;
+    coverage_disposition: string;
+};
+/** One declared gap from one completed phase's ledger. */
+export type CoverageGap = {
+    /** The phase that declared it. */
+    phaseId: string;
+    /** Which bullet it came from: "skipped scope" or "known blind spots". */
+    label: string;
+    /** The bullet's text, sub-bullets folded onto one line. */
+    detail: string;
+    /** `.codecarto/`-relative path of the output the ledger was read from. */
+    output: string;
+};
+/**
+ * Read a phase output's `## Coverage and limits` ledger.
+ *
+ * Returns null when the document has no such section. A bullet the author left
+ * blank comes back as an empty string, as does a label the section omits, so a
+ * caller never has to distinguish "absent" from "empty" — both mean nothing to
+ * carry forward.
+ *
+ * Sub-bullets and wrapped continuation lines under a label belong to that
+ * label: a real report writes its blind spots as a nested list, and dropping
+ * them would silence exactly the case this exists for. They fold onto one line
+ * (sub-bullets joined with "; ") because the consumer is a prompt bullet.
+ */
+export declare function parseCoverageAndLimits(content: string): CoverageLedger | null;
+/**
+ * Every declared gap from every completed phase whose primary output exists.
+ *
+ * Walks `phase_order` so the list is deterministic and reads upstream-first.
+ * Only `Skipped scope` and `Known blind spots` are collected: those are the
+ * two bullets that bind a later phase's claims. Unreadable or unparsable
+ * outputs contribute nothing.
+ */
+export declare function collectCoverageGaps(state: WorkspaceState): Promise<CoverageGap[]>;

package/dist/core/coverage.js

@@ -0,0 +1,131 @@
+// The coverage-gap ledger every primary output carries (#122, #186).
+//
+// Each phase output ends with a `## Coverage and limits` section whose bullet
+// labels are fixed across every template — `- Inspected scope:`, `- Skipped
+// scope:`, `- Evidence basis:`, `- Known blind spots:`, `- Coverage
+// disposition:` — which is what makes reading it a parse and not a guess.
+//
+// The ledger was carried nowhere: not into the next phase's prompt, not into
+// status.yaml, not into validation. So an upstream phase could declare "the
+// encoded search-proxy command was not fully decoded" and the next phase could
+// assert an `observed fact` about that exact component, with nothing in the
+// framework comparing the two. The contradiction sweep could not have caught
+// it either: that sweep compares against `owner_notes`, and a declared blind
+// spot is not an owner note.
+//
+// Everything here is non-gating and read-only. A missing file, a missing
+// section, or an empty bullet yields nothing; nothing throws.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+/** The section heading whose bullets this module reads. */
+export const COVERAGE_SECTION_HEADING = "Coverage and limits";
+/** Bullet label (normalized) to ledger field. */
+const LEDGER_LABELS = new Map([
+    ["inspected scope", "inspected_scope"],
+    ["skipped scope", "skipped_scope"],
+    ["evidence basis", "evidence_basis"],
+    ["known blind spots", "known_blind_spots"],
+    ["coverage disposition", "coverage_disposition"],
+]);
+/** The two ledger bullets a downstream phase is bound by, in render order. */
+const GAP_FIELDS = [
+    { field: "skipped_scope", label: "skipped scope" },
+    { field: "known_blind_spots", label: "known blind spots" },
+];
+function emptyLedger() {
+    return {
+        inspected_scope: "",
+        skipped_scope: "",
+        evidence_basis: "",
+        known_blind_spots: "",
+        coverage_disposition: "",
+    };
+}
+function normalizeLabel(label) {
+    return label.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * Read a phase output's `## Coverage and limits` ledger.
+ *
+ * Returns null when the document has no such section. A bullet the author left
+ * blank comes back as an empty string, as does a label the section omits, so a
+ * caller never has to distinguish "absent" from "empty" — both mean nothing to
+ * carry forward.
+ *
+ * Sub-bullets and wrapped continuation lines under a label belong to that
+ * label: a real report writes its blind spots as a nested list, and dropping
+ * them would silence exactly the case this exists for. They fold onto one line
+ * (sub-bullets joined with "; ") because the consumer is a prompt bullet.
+ */
+export function parseCoverageAndLimits(content) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^##\s+Coverage and limits\s*$/i.test(line.replace(/[`*_]/g, "")));
+    if (start < 0)
+        return null;
+    const ledger = emptyLedger();
+    let current = null;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^##\s/.test(line))
+            break;
+        const bullet = /^[-*]\s+(.*)$/.exec(line);
+        if (bullet) {
+            const separator = bullet[1].indexOf(":");
+            const field = separator >= 0 ? LEDGER_LABELS.get(normalizeLabel(bullet[1].slice(0, separator))) : undefined;
+            // An unrecognized top-level bullet ends the previous label's block
+            // rather than absorbing text that belongs to neither.
+            current = field ?? null;
+            if (field)
+                ledger[field] = bullet[1].slice(separator + 1).trim();
+            continue;
+        }
+        if (!line.trim())
+            continue; // a blank line does not end a label's block
+        if (!current || !/^\s/.test(line)) {
+            current = null; // unindented prose is not part of any bullet
+            continue;
+        }
+        const continuation = line.trim();
+        const nested = /^[-*]\s+(.*)$/.exec(continuation);
+        const text = (nested ? nested[1] : continuation).trim();
+        if (!text)
+            continue;
+        ledger[current] = ledger[current] ? `${ledger[current]}${nested ? "; " : " "}${text}` : text;
+    }
+    return ledger;
+}
+/**
+ * Every declared gap from every completed phase whose primary output exists.
+ *
+ * Walks `phase_order` so the list is deterministic and reads upstream-first.
+ * Only `Skipped scope` and `Known blind spots` are collected: those are the
+ * two bullets that bind a later phase's claims. Unreadable or unparsable
+ * outputs contribute nothing.
+ */
+export async function collectCoverageGaps(state) {
+    const configs = new Map(state.pipeline.phases.map((phase) => [phase.id, phase]));
+    const gaps = [];
+    for (const phaseId of state.pipeline.phase_order ?? []) {
+        if (state.status.phases[phaseId]?.status !== "complete")
+            continue;
+        const output = configs.get(phaseId)?.primary_output;
+        if (!output)
+            continue;
+        const outputPath = join(state.workspaceDir, output);
+        if (!(await pathExists(outputPath)))
+            continue;
+        const content = await readFile(outputPath, "utf8").catch(() => null);
+        if (content === null)
+            continue;
+        const ledger = parseCoverageAndLimits(content);
+        if (!ledger)
+            continue;
+        for (const { field, label } of GAP_FIELDS) {
+            const detail = ledger[field];
+            if (detail)
+                gaps.push({ phaseId, label, detail, output });
+        }
+    }
+    return gaps;
+}

package/dist/core/index.d.ts

@@ -5,6 +5,7 @@ export * from "./status.ts";
 export * from "./amendment.ts";
 export * from "./pipeline.ts";
 export * from "./findings.ts";
+export * from "./coverage.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
 export * from "./completion.ts";

package/dist/core/index.js

@@ -8,6 +8,7 @@ export * from "./status.js";
 export * from "./amendment.js";
 export * from "./pipeline.js";
 export * from "./findings.js";
+export * from "./coverage.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
 export * from "./completion.js";

package/dist/core/prompts.js

@@ -4,12 +4,17 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { pathExists } from "./utils.js";
+import { collectCoverageGaps } from "./coverage.js";
 import { countPendingProposals } from "./completion.js";
 import { describeScaffoldStaleness } from "./workspace.js";
 import { runPhasePreflight } from "./synthesis.js";
 /** Open-question kinds whose label the orchestrator re-tests at each phase boundary. */
 const RETRIAGE_KINDS = new Set(["needs-maintainer-decision", "needs-runtime-test"]);
-/** Cap on individually listed re-triage questions; the rest collapse to a count. */
+/**
+ * Cap on the individually listed entries of a mechanically surfaced duty list
+ * — re-triage questions and upstream coverage gaps alike; the rest collapse to
+ * a count naming where the full list lives.
+ */
 const RETRIAGE_LIST_LIMIT = 10;
 /**
  * Build the "Orchestrator duties" prompt block (issue #98): the cross-phase
@@ -47,6 +52,19 @@ async function buildOrchestratorDuties(state, phase, auto) {
             lines.push(`  - .codecarto/${output.path} (${exists ? "exists" : "missing"})`);
         }
     }
+    // The coverage-gap ledger (#122, #186). The contradiction sweep below
+    // compares against `owner_notes` only, and a declared blind spot is not an
+    // owner note — so a phase could assert an observed fact about a component
+    // the upstream phase had recorded as not decoded, and nothing compared the
+    // two. Non-gating: this is a duty in the prompt, not a validation rule.
+    const coverageGaps = await collectCoverageGaps(state);
+    if (coverageGaps.length > 0) {
+        lines.push("- Upstream phases declared these coverage gaps in their `## Coverage and limits` sections. A finding of yours that lands inside one must either close the gap with cited new evidence of its own or inherit its uncertainty — an upstream `not inspected` or `not decoded` does not license an `observed fact` about that scope:");
+        for (const gap of coverageGaps.slice(0, RETRIAGE_LIST_LIMIT))
+            lines.push(`  - ${gap.phaseId} (${gap.label}): ${gap.detail}`);
+        if (coverageGaps.length > RETRIAGE_LIST_LIMIT)
+            lines.push(`  - (+${coverageGaps.length - RETRIAGE_LIST_LIMIT} more in completed phases' Coverage and limits sections)`);
+    }
     const anyCompleted = Object.values(state.status.phases).some((phaseState) => phaseState.status === "complete");
     if (anyCompleted) {
         lines.push("- Contradiction sweep: compare this phase's required reads against completed phases' owner_notes; a measured fact that contradicts a summarized claim is a gap to route through the handoff, not a nuance to smooth over.");

package/dist/core/status.d.ts

@@ -1,9 +1,16 @@
-import type { NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
+import type { ClosureEntry, NormalizedStatus, OpenQuestionEntry, PostPipelineEntry, PhaseHandoff, PipelineFile, ProposedConventionEntry, StatusFile, StatusPhase } from "./types.ts";
 export declare const LOCK_RETRY_MS = 125;
 export declare const LOCK_TIMEOUT_MS = 5000;
 export declare const STALE_LOCK_MS = 60000;
 export declare function assertSafePhaseId(phaseId: string): void;
 export declare function ensureArray(value: unknown): string[];
+/**
+ * Normalize a handoff's `open_question_closures` (#122, #186). Accepts both
+ * the original bare-string shape and `{ id, evidence }`; a string becomes
+ * `{ id }`, and an entry with no usable id is dropped rather than resolving
+ * nothing under the lock. Values are trimmed.
+ */
+export declare function ensureClosureArray(value: unknown): ClosureEntry[];
 export declare function ensureEntryArray<T extends OpenQuestionEntry>(value: unknown, allowTargetPhase?: boolean): T[];
 export declare function autoAssignIds(entries: OpenQuestionEntry[], prefix: string, phaseId: string): void;
 export declare function ensurePostPipelineArray(value: unknown): PostPipelineEntry[];

package/dist/core/status.js

@@ -36,8 +36,42 @@ function coerceEntry(value, allowTargetPhase) {
         entry.deferred_reason = raw.deferred_reason.trim();
     if (allowTargetPhase && typeof raw.target_phase === "string" && raw.target_phase.trim())
         entry.target_phase = raw.target_phase.trim();
+    // derives_from rides the same flag as target_phase: it is a carry-forward
+    // concept only — the id of the open question this routed item answers one
+    // candidate of (#122, #186). An open_questions entry has nothing to derive
+    // from, so the field is dropped there rather than silently carried.
+    if (allowTargetPhase && typeof raw.derives_from === "string" && raw.derives_from.trim())
+        entry.derives_from = raw.derives_from.trim();
     return Object.keys(entry).length > 0 ? entry : null;
 }
+/**
+ * Normalize a handoff's `open_question_closures` (#122, #186). Accepts both
+ * the original bare-string shape and `{ id, evidence }`; a string becomes
+ * `{ id }`, and an entry with no usable id is dropped rather than resolving
+ * nothing under the lock. Values are trimmed.
+ */
+export function ensureClosureArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const item of value) {
+        if (typeof item === "string") {
+            const id = item.trim();
+            if (id)
+                result.push({ id });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const raw = item;
+        const id = typeof raw.id === "string" ? raw.id.trim() : "";
+        if (!id)
+            continue;
+        const evidence = typeof raw.evidence === "string" && raw.evidence.trim() ? raw.evidence.trim() : undefined;
+        result.push({ id, ...(evidence !== undefined && { evidence }) });
+    }
+    return result;
+}
 export function ensureEntryArray(value, allowTargetPhase = false) {
     if (!Array.isArray(value))
         return [];
@@ -218,7 +252,7 @@ export function parseHandoff(value) {
         open_questions: openQuestions,
         carry_forward: carryForward,
         carry_forward_closures: ensureArray(raw.carry_forward_closures),
-        open_question_closures: ensureArray(raw.open_question_closures),
+        open_question_closures: ensureClosureArray(raw.open_question_closures),
         post_pipeline: ensurePostPipelineArray(raw.post_pipeline),
         decisions: ensureArray(raw.decisions),
         proposed_conventions: ensureProposedConventionArray(raw.proposed_conventions),
@@ -335,7 +369,8 @@ export function applyHandoff(status, handoff) {
         }
     }
     // Apply open_question_closures: remove resolved questions from ALL phases by id
-    for (const closureId of handoff.open_question_closures) {
+    for (const closure of handoff.open_question_closures) {
+        const closureId = closure?.id;
         if (!closureId)
             continue;
         for (const ph of Object.values(status.phases)) {

package/dist/core/types.d.ts

@@ -9,6 +9,16 @@ export type OpenQuestionEntry = {
 };
 export type CarryForwardEntry = OpenQuestionEntry & {
     target_phase?: string;
+    /**
+     * Optional id of the `open_questions` entry this routed item is one
+     * candidate answer to (#122, #186). The upstream phase usually registers
+     * the question and routes the candidate onward in the same handoff, which
+     * is the cheapest moment to record the link. Completion refuses a closure
+     * of this entry while that question is still open and is not closed by the
+     * same handoff: closing a routed item does not settle the question it came
+     * from. Omitted on every entry that predates the field.
+     */
+    derives_from?: string;
 };
 export type PostPipelineEntry = OpenQuestionEntry & {
     source_phase?: string;
@@ -114,6 +124,18 @@ export type ProposedConventionEntry = {
     /** Optional: where the pattern showed up (file, phase, incident). */
     evidence?: string;
 };
+/**
+ * One claimed closure in a handoff's `open_question_closures` (#122, #186).
+ * A bare string — the only shape before this field grew — normalizes to
+ * `{ id }`; the object form adds the evidence that settles the question.
+ * Completion requires non-empty `evidence` when the closed question's `kind`
+ * is `needs-runtime-test`, because such a question closes on runtime evidence
+ * rather than on another source read.
+ */
+export type ClosureEntry = {
+    id: string;
+    evidence?: string;
+};
 export type PhaseHandoff = {
     phase_id: string;
     /**
@@ -126,7 +148,8 @@ export type PhaseHandoff = {
     open_questions: OpenQuestionEntry[];
     carry_forward: CarryForwardEntry[];
     carry_forward_closures: string[];
-    open_question_closures: string[];
+    /** ids to resolve and remove from all phases; a bare string parses to `{ id }`. */
+    open_question_closures: ClosureEntry[];
     post_pipeline: PostPipelineEntry[];
     decisions: string[];
     /** Conventions proposed for promotion; completion stages them in CONVENTIONS.md. Omitted defaults to empty. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",