codecartographer-pi 0.17.1 → 0.19.0

package/.codecarto/GUIDE.md

@@ -92,7 +92,7 @@ If you are uncertain whether a file should be modified, treat it as read-only.
 ### Two things named "backlog", and neither is the other
 
 - **`BACKLOG.md` in this workspace** is *this project's* deferrals: work the project chose not to do yet. `DECISIONS.md` records what the project decided to **do**; `BACKLOG.md` records what it decided to **defer**. Deferrals get no `D` number. When a deferred item is later picked up, remove its entry here and record the decision in `DECISIONS.md`.
-- **`status.yaml`'s `post_pipeline` list** is framework-owned lifecycle state, not this file. Items there are retired by `codecarto_amend`, never by hand.
+- **`status.yaml`'s `post_pipeline` list** is framework-owned lifecycle state, not this file. Items there are retired by an amendment (`codecarto_amend` on MCP, `/codecarto-amend` on Pi), never by hand.
 - **CodeCartographer's own backlog** — deferred improvements to the *framework* — lives in the CodeCartographer repository, not in your workspace. If a phase prompt misled you or a validation criterion did not fit, that is feedback to the framework; it does not belong in this file.
 
 ## Pipeline Selection
@@ -215,7 +215,14 @@ 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.
 
-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`. 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.
+**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/skills/spec-delta-application/SKILL.md

@@ -88,7 +88,7 @@ Per the standard closeout ritual:
 
 - Append a one-line entry to `THREAD_LOG.md` pointing at the closeout file.
 - Write `closeouts/<YYYY-MM-DD>-spec-deltas.md` using `templates/closeout-template.md`.
-- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend`. It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without the MCP server, record the intended amendment file in the closeout for the next MCP-capable session to apply.
+- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend` (MCP) or `/codecarto-amend <slug>` (Pi). It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without Pi or the MCP server (drop-in mode), record the intended amendment file in the closeout for the next Pi or MCP session to apply.
 - Append numbered entries to `DECISIONS.md` for any decisions made during triage that weren't already in the deltas (e.g., "rejected Δ7 because the spec already covered the case at §X").
 
 ## What to avoid

package/.codecarto/templates/amendment.yaml

@@ -1,7 +1,7 @@
 # Post-pipeline amendment schema v1. Copy to scratch/amendments/<slug>.yaml,
-# then run codecarto_amend (MCP) with the slug. Refused while the pipeline is
-# incomplete — mid-pipeline resolutions belong in the phase handoff
-# (open_question_closures / carry_forward_closures).
+# then run codecarto_amend (MCP) or /codecarto-amend <slug> (Pi). Refused while
+# the pipeline is incomplete — mid-pipeline resolutions belong in the phase
+# handoff (open_question_closures / carry_forward_closures).
 schema_version: 1
 # Open-question ids resolved on evidence after the pipeline completed;
 # removed from every phase in workflow/status.yaml.

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/templates/spike-report.md

@@ -12,8 +12,8 @@
   phase handoff. When a spike's findings change the reimplementation spec, write
   the deltas as Recommended Deltas below and apply them with the
   spec-delta-application skill; when a spike resolves an open question after the
-  pipeline completed, close it with an amendment (templates/amendment.yaml +
-  codecarto_amend), citing this report.
+  pipeline completed, close it with an amendment (templates/amendment.yaml, then
+  codecarto_amend on MCP or /codecarto-amend on Pi), citing this report.
 
   Keep it honest: a spike that failed to answer its question is a valid result —
   record what was tried and what blocked it.

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.17.1
+scaffold_version: 0.19.0

package/README.md

@@ -92,7 +92,7 @@ Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Curso
 
 > **30-second setup for Claude Code, Cursor, Codex, and Claude Desktop: see the [MCP quickstart](docs/mcp-quickstart.md).**
 
-> **Teaching an agent to drive it:** call the `codecarto_guide` tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at `agent-skill/codecartographer/` for agents that load skills from disk.
+> **Teaching an agent to drive it:** call the `codecarto_guide` tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at `agent-skill/codecartographer/` for agents that load skills from disk, and `/codecarto-guide [topic]` reads it into a Pi session.
 
 ```bash
 npm install --global codecartographer-pi
@@ -137,7 +137,7 @@ Analysis turns repositories into reusable specifications. Synthesis runs the oth
    library:
      path: /absolute/path/to/codecarto-library
      namespace: your-namespace # omit for a single-tenant library
-     publish_confirm: true
+     publish_confirm: true # Pi asks before writing; MCP refuses a publish that lacks confirm: true
    ```
 
 2. Initialize a clean planning workspace and fill in its brief:
@@ -321,12 +321,16 @@ Beyond the slash commands, the Pi extension layers on:
 | `/codecarto-validate [phase]` | Validate a phase output against completion criteria |
 | `/codecarto-complete [phase]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |
 | `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete (or `broadside` any time, for the scout reading guide) |
+| `/codecarto-list-skills` | List the installed post-pipeline skills and the ungated `broadside` reading guide, and say when the gated ones unlock |
+| `/codecarto-guide [topic]` | Read the packaged agent guide — drive loop, handoff contract, executors, recovery, Broad-Side — into the session; tab-completes topics; needs no workspace |
 | `/codecarto-broadside [action] [lenses…]` | Batch reconnaissance (Broad-Side). Actions: `submit`, `collect`, `status`, `models`. Prices the run and asks before spending; works with or without a workspace |
 | `/codecarto-publish` | Publish the reimplementation spec to the configured library after reviewing an explicit confirmation preview |
 | `/codecarto-library-init <path> [--namespace <name>]` | Create a library directory with marker and write the config — fixes the first-publish dead end |
 | `/codecarto-config` | Show the effective merged configuration (global + workspace) and library marker status |
 | `/codecarto-usage` | Cumulative + per-phase token usage |
 | `/codecarto-dashboard [--narrate]` | Regenerate `.codecarto/dashboard.html`; `--narrate` for the LLM executive summary |
+| `/codecarto-refresh-scaffold` | Refresh the framework-owned `.codecarto/` files (GUIDE.md, templates/, workflow/ pipelines and VALIDATE.md) from the packaged template after a confirmation that lists the exact file set; project state, config, findings outputs, scratch, closeouts, and `broadside/` are never touched |
+| `/codecarto-amend <name>` | Apply a post-pipeline amendment from `scratch/amendments/<name>.yaml` after a confirmation that previews which open questions and post-pipeline items it closes; refused while the pipeline is incomplete |
 
 ### End-to-end auto mode (0.8.0+)
 
@@ -360,7 +364,7 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_validate` | `/codecarto-validate` |
 | `codecarto_complete` | `/codecarto-complete` |
 | `codecarto_skill` | `/codecarto-skill` |
-| `codecarto_list_skills` | MCP-only ([#161](https://github.com/HuginnIndustries/CodeCartographer/issues/161)); Pi lists skills when `/codecarto-skill` runs with no argument |
+| `codecarto_list_skills` | `/codecarto-list-skills` |
 | `codecarto_publish` | `/codecarto-publish` |
 | `codecarto_library_init` | `/codecarto-library-init` |
 | `codecarto_library_list` | MCP-only library listing |
@@ -368,9 +372,9 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_config` | `/codecarto-config` |
 | `codecarto_usage` | `/codecarto-usage` |
 | `codecarto_dashboard` | `/codecarto-dashboard` |
-| `codecarto_guide` | MCP-only ([#160](https://github.com/HuginnIndustries/CodeCartographer/issues/160)) |
-| `codecarto_amend` | MCP-only ([#157](https://github.com/HuginnIndustries/CodeCartographer/issues/157)) |
-| `codecarto_refresh_scaffold` | MCP-only ([#159](https://github.com/HuginnIndustries/CodeCartographer/issues/159)) |
+| `codecarto_guide` | `/codecarto-guide` |
+| `codecarto_amend` | `/codecarto-amend` (Pi previews the closures and asks first) |
+| `codecarto_refresh_scaffold` | `/codecarto-refresh-scaffold` (Pi lists the file set and asks first) |
 | `codecarto_broadside` | `/codecarto-broadside` |
 
 Each workflow tool accepts an absolute `cwd` for the target repository. `codecarto_init` requires `force: true` to overwrite an existing `.codecarto/` (instead of Pi's interactive confirmation). The library tools accept an explicit absolute `library_path` or resolve `library.path` from `.codecarto/workflow/config.yaml` / `~/.codecarto/config.yaml`. `codecarto_library_reindex` and `codecarto_library_list` also report entries whose versions disagree about `source_repo` — the shape a slug collision left behind before v0.17.0's publish guard — and leave the repair manual, since splitting an entry changes paths the library format treats as ABI. The library schema is experimental and may break before v2.

package/agent-skill/codecartographer/SKILL.md

@@ -117,7 +117,7 @@ A PARTIAL row's evidence must name what is missing and which `open_questions` or
 - `codecarto_next` returns a prompt. Something still has to *do* the phase.
 - Never hand-edit `workflow/status.yaml`, append `THREAD_LOG.md`, or write a second closeout. Propose through the handoff.
 - Do not force phases out of DAG order unless the user asked.
-- If `codecarto_status` reports a scaffold-staleness warning, refresh the workspace's framework-owned files before trusting anything written inside `.codecarto/`; a stale scaffold's `GUIDE.md` can contradict this contract.
+- If `codecarto_status` reports a scaffold-staleness warning, refresh the workspace's framework-owned files (`codecarto_refresh_scaffold`; `/codecarto-refresh-scaffold` on the Pi extension) before trusting anything written inside `.codecarto/`; a stale scaffold's `GUIDE.md` can contradict this contract. The refresh never touches project state, findings outputs, or session directories.
 - A delegated run that times out may still have written its artifact. Check for the file and validate before retrying.
 - The drop-in `.codecarto/` template works without MCP, but the server is preferred: it owns atomic state updates, validation parsing, and the completion gate.
 

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/agent-skill/codecartographer/references/library.md

@@ -13,7 +13,7 @@ A CodeCartographer **library** is a directory of published reimplementation-spec
 | Tool | Does | Notes |
 |---|---|---|
 | `codecarto_library_init` | Create the directory, write the marker, record `library.path` in user-global config | Idempotent; pass `namespace` to create a namespaced library |
-| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown` |
+| `codecarto_publish` | Publish a spec as a library entry | Required: `source_repo`, `headline`, and `spec` (inline) or `spec_path` (absolute). Content-hash idempotent: identical bytes update metadata in place, no version bump. `slug` derives from `source_repo` if omitted; namespaced libraries require `namespace` (or inherit via `cwd`). Provenance (`source_commit`, `source_branch`, `source_dirty`, `analyzed_at`, `pipeline`, `model_metadata`) is recorded; omitted generation fields default to `unknown`. `confirm: true` acknowledges the `publish_confirm` gate (below) |
 | `codecarto_library_list` | List entries | Filter by `namespace`, `tag`, `slug`, or `source_repo` |
 | `codecarto_library_reindex` | Regenerate `index.yaml` + `INDEX.md` from filesystem state | For manual edits and index merge conflicts. Also reports entries whose versions disagree about `source_repo` (merged by a slug collision before publish refused cross-project appends; `codecarto_library_list` flags them too) — repair is manual, split the entry by hand |
 
@@ -25,7 +25,7 @@ The moment `reimplementation-spec` completes and validates is the publish moment
 codecarto_publish cwd:<workspace repo> source_repo:<repo URL or path> headline:"<one line>" spec_path:<abs path to reimplementation-spec.md>
 ```
 
-Set `publish_confirm` in config if you want an explicit confirmation gate before writes. **Pi-only today:** the Pi extension asks for interactive confirmation before `/codecarto-publish` writes; the MCP `codecarto_publish` tool does not act on the key (an MCP host has no one to ask — [#162](https://github.com/HuginnIndustries/CodeCartographer/issues/162) tracks whether it should refuse-unless-forced instead), so on MCP treat it as advisory.
+Set `publish_confirm` in config if you want an explicit confirmation gate before writes. It means something on both executable surfaces, in the only way each can ask. The Pi extension shows a preview and asks interactively before `/codecarto-publish` writes. The MCP `codecarto_publish` tool has no one to ask, so when the key is set — in `~/.codecarto/config.yaml`, or in the workspace's `.codecarto/workflow/config.yaml` when `cwd` is passed — it refuses a call that lacks `confirm: true` and returns the preview instead: library, entry, whether this would be a new version or a metadata-only update, `source_repo`, headline, confidentiality. Nothing is written by the refusal. Show the preview, then re-invoke with the same arguments plus `confirm: true` to publish. The gate applies only when the key is actually set in a config file (`codecarto_library_init` writes `publish_confirm: true`, so a library initialized through the tool has it on); a host that never configured the key is not gated, and `publish_confirm: false` drops the gate.
 
 ## What this is not
 

package/agent-skill/codecartographer/references/phase-recovery.md

@@ -39,7 +39,7 @@ If two reduced-scope attempts fail, the problem is usually scope, not the execut
 
 - Split the reading. Use scoped pre-passes over individual subsystems, save the notes under `.codecarto/scratch/`, and give the retry those notes as evidence.
 - Consider whether the pipeline variant is right. A repository too large for one `architecture` pass may want `architecture-only` first, reviewed, then a switch.
-- Check for a scaffold-staleness warning in `codecarto_status`. A workspace whose framework-owned files predate the running version can carry instructions that contradict the current contract, which produces artifacts that fail validation for reasons the executor cannot see.
+- Check for a scaffold-staleness warning in `codecarto_status`. A workspace whose framework-owned files predate the running version can carry instructions that contradict the current contract, which produces artifacts that fail validation for reasons the executor cannot see. `codecarto_refresh_scaffold` (`/codecarto-refresh-scaffold` on the Pi extension) refreshes those files without touching project state.
 
 ## What not to do
 

package/dist/core/amendment.d.ts

@@ -27,6 +27,11 @@ export type AmendmentResult = {
 };
 /** Same charset rule as phase ids: the slug becomes file names, so path shapes are refused. */
 export declare function assertSafeAmendmentSlug(slug: string): void;
+/**
+ * Slugs of the amendment files staged under scratch/amendments/, sorted.
+ * Discovery only — nothing here is validated; {@link loadAmendmentFile} does that.
+ */
+export declare function listAmendmentNames(workspaceDir: string): Promise<string[]>;
 /**
  * Load and validate one amendment file.
  * @param name - the amendment slug, with or without a `.yaml` suffix.

package/dist/core/amendment.js

@@ -5,8 +5,8 @@
 // carry_forward_closures); an amendment is the post-pipeline counterpart, so
 // spec-delta sessions, spikes, and maintainer rulings no longer end with
 // "record for a later explicit amendment" that nothing can perform.
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
 import { getNextEligiblePhase } from "./pipeline.js";
 import { buildTerminalNextActions, ensureArray, normalizeStatus } from "./status.js";
 import { dateOnly, newlineIfUnterminated, pathExists } from "./utils.js";
@@ -18,6 +18,25 @@ export function assertSafeAmendmentSlug(slug) {
         throw new Error(`Invalid amendment name: ${slug}`);
     }
 }
+/**
+ * Slugs of the amendment files staged under scratch/amendments/, sorted.
+ * Discovery only — nothing here is validated; {@link loadAmendmentFile} does that.
+ */
+export async function listAmendmentNames(workspaceDir) {
+    const amendmentsDir = join(workspaceDir, "scratch", "amendments");
+    if (!(await pathExists(amendmentsDir)))
+        return [];
+    try {
+        const entries = await readdir(amendmentsDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
+            .map((entry) => basename(entry.name).replace(/\.ya?ml$/i, ""))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Load and validate one amendment file.
  * @param name - the amendment slug, with or without a `.yaml` suffix.

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[]>;