codecartographer-pi 0.17.0 → 0.18.0

package/README.md

@@ -35,7 +35,7 @@ Asking an LLM to "analyze this repo" loses context halfway through, hallucinates
 
 3. **The output is a spec, not a chat log.** The final `reimplementation-spec.md` is language-agnostic, module-inventoried, and carries acceptance scenarios plus known unknowns. Hand it to another agent to rebuild from.
 
-Every finding is tagged with an evidence level: `observed fact`, `strong inference`, `portability hazard`, or `open question`.
+Every finding is tagged with an evidence level: `observed fact`, `strong inference`, `portability hazard`, `external-behavior claim`, or `open question`.
 
 ---
 
@@ -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:
@@ -228,7 +228,7 @@ The porting bundle is the final intentional compression boundary. It carries a s
 | **Porting bundle** | Everything synthesized into a porting-oriented view with priority rankings |
 | **Reimplementation spec** | Language-agnostic build plan with modules, acceptance scenarios, and known unknowns |
 
-Every finding is tagged with an evidence level: `observed fact`, `strong inference`, `portability hazard`, or `open question`. Every phase output is validated against explicit completion criteria before the pipeline advances.
+Every finding is tagged with an evidence level: `observed fact`, `strong inference`, `portability hazard`, `external-behavior claim`, or `open question`. Every phase output is validated against explicit completion criteria before the pipeline advances.
 
 ---
 
@@ -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,12 +372,12 @@ 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`. The library schema is experimental and may break before v2.
+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.
 
 ---
 
@@ -584,7 +588,7 @@ The MCP server does steps 1–3 directly; the Pi extension wraps them as slash c
 - **LLM-agnostic** — works with any model that can read and write files.
 - **Phase-gated** — one phase per session, validated before advancing.
 - **Single source of truth** — `status.yaml` tracks progress; no duplicated state.
-- **Evidence-classified** — every finding tagged as observed fact, strong inference, portability hazard, or open question.
+- **Evidence-classified** — every finding tagged as observed fact, strong inference, portability hazard, external-behavior claim, or open question.
 - **Template-driven** — consistent output structure across projects and sessions.
 - **Drop-in** — lives inside your repo as `.codecarto/`. No symlinks, no copying source code, no runtime daemon.
 

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/deep-audit-synthesis.md

@@ -13,8 +13,11 @@ The common failure is treating defect reports as a separate document that the po
 | `fix before porting` | the defect would be reproduced by a faithful port | design it out; the spec states the correct behavior |
 | `port differently` | the behavior is needed but the mechanism is wrong | spec the intent, not the implementation |
 | `leave behind` | dead, vestigial, or actively harmful | name it explicitly so a later reader doesn't "restore" it |
+| `verify at runtime` | the diagnosis is an `external-behavior claim` or `open question` — about a server, engine, driver, or API this source only calls | a spike in the spec's Spike List and a `post_pipeline` `kind: spike` entry; never a design consequence, because the claim is unconfirmed |
 
-Add the acceptance-test implication alongside each row. A hazard with no test in the spec will be reintroduced by whoever implements it.
+Add the acceptance-test implication alongside each row.
+
+The fourth disposition exists because of a real run: a defect scan asserted, as `strong inference` / `fix before porting`, that an inference server expected a different `logit_bias` payload shape, and recommended a one-line reshape. Runtime testing against the pinned engine inverted it — the shape the code already sent worked, and the recommended one was silently ignored. The evidence level bounds the action: `open question` or `external-behavior claim` evidence never pairs with `fix before porting`, and validation now fails a defect report that does so. A hazard with no test in the spec will be reintroduced by whoever implements it.
 
 Close a carry-forward item only once its guidance is represented in an artifact a later phase actually consumes — not merely mentioned in the phase that raised it.
 

package/agent-skill/codecartographer/references/library.md

@@ -13,9 +13,9 @@ 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 |
+| `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 |
 
 ## When to publish
 
@@ -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/orchestration.md

@@ -8,7 +8,7 @@ All of them happen at the **phase boundary**: after one phase completes, before
 
 1. **Promote conventions and append decisions.** Phase closeouts carry "Proposed Conventions" and "Decisions Beyond Prompt" sections; handoffs carry a `decisions` array. Promotion into `CONVENTIONS.md` (when a pattern recurs or clearly generalizes) and `DECISIONS.md` (every cross-cutting decision, numbered, append-only) is your call to make at the boundary. Proposals left in closeout prose are proposals lost — a real seven-phase run stranded ~12 proposed conventions and 23 decisions this way, because nobody held the duty.
 
-2. **Re-triage open-question labels.** An `open_questions` entry's `kind` is itself a claim that needs evidence. Before accepting `needs-maintainer-decision` or `needs-runtime-test` into the next phase, re-test: *has this become answerable by reading?* Labels are sticky — the routing machinery faithfully carries a question forward, but nothing re-examines whether the label was right, so a mislabel suppresses verification for the rest of the pipeline.
+2. **Re-triage open-question labels.** An `open_questions` entry's `kind` is itself a claim that needs evidence. Before accepting `needs-maintainer-decision` or `needs-runtime-test` into the next phase, re-test: *has this become answerable by reading?* Labels are sticky — the routing machinery faithfully carries a question forward, but nothing re-examines whether the label was right, so a mislabel suppresses verification for the rest of the pipeline. The duty cuts both ways: when the answer is genuinely *no, this still needs a runtime test*, no finding in the next phase may assert one of the question's candidate answers with a settled action (`fix before porting`, `fix now`). The finding inherits the question's uncertainty — evidence `external-behavior claim` or `open question`, action `verify at runtime` — until runtime evidence closes the question. A real `full-with-deep-audit` run broke this: the mechanical phase wrote "source alone cannot determine which" and routed one candidate onward; the semantic phase closed it as `strong inference` / `fix before porting`; runtime testing showed the recommended fix would have converted working behavior into the one shape the engine silently ignores.
 
 3. **Sweep for contradictions.** Compare the incoming phase's required reads against earlier phases' `owner_notes`. A measured fact that contradicts a summarized claim (a line count that belies "this layer is pure configuration", a schema that admits a value a doc says is impossible) is a gap to route — into the next phase's work, an `open_questions` entry, or a correction — not a nuance to smooth over.
 

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,11 +5,11 @@
 // 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, pathExists } from "./utils.js";
+import { dateOnly, newlineIfUnterminated, pathExists } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 import { loadYamlFile } from "./yaml.js";
 /** Same charset rule as phase ids: the slug becomes file names, so path shapes are refused. */
@@ -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.
@@ -134,7 +153,7 @@ export async function applyAmendment(cwd, name) {
             // Created below when absent.
         }
         if (!current.split(/\r?\n/).some((line) => line.includes(`[closeout](closeouts/${closeoutFile})`))) {
-            await appendFile(threadLogPath, `${entry}\n`, "utf8");
+            await appendFile(threadLogPath, `${newlineIfUnterminated(current)}${entry}\n`, "utf8");
         }
         closeoutNotice = `Closeout: .codecarto/closeouts/${closeoutFile}`;
         return { state: { ...lockedState, status: nextStatus } };

package/dist/core/completion.d.ts

@@ -2,6 +2,11 @@ import type { ValidationResult, WorkspaceState } from "./types.ts";
 export type CompletionResult = {
     updatedState: WorkspaceState;
     closeoutNotice?: string;
+    /**
+     * Non-gating closure-integrity observations (#122): closures the handoff
+     * claims that the primary output never mentions. Empty when clean.
+     */
+    warnings: string[];
     /**
      * One-line phase-boundary reminder covering what completion just mechanized
      * (decisions appended, proposals staged) and what still needs orchestrator

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, pathExists, uniqueStrings } from "./utils.js";
+import { dateOnly, newlineIfUnterminated, pathExists, uniqueStrings } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
 /**
  * The Markdown a reader sees: content inside `<!-- -->` blocks removed by a
@@ -223,7 +223,7 @@ async function writeCompletionArtifacts(workspaceDir, phaseId, validation, times
     }
     const link = `[closeout](closeouts/${closeoutFile})`;
     if (!current.split(/\r?\n/).some((line) => line.includes(link))) {
-        await appendFile(threadLogPath, `${entry}\n`, "utf8");
+        await appendFile(threadLogPath, `${newlineIfUnterminated(current)}${entry}\n`, "utf8");
     }
     // Mechanize the orchestrator loop's bookkeeping half (issue #98): decisions
     // reach DECISIONS.md and proposals reach CONVENTIONS.md at completion, so a
@@ -268,6 +268,21 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
                 throw new Error("Invalid handoff: post_pipeline entries require a canonical id");
         }
     }
+    // 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());
+        if (closures.length > 0) {
+            const output = await readFile(validation.outputPath, "utf8").catch(() => "");
+            const unmentioned = closures.filter((id) => !output.includes(id));
+            if (unmentioned.length > 0) {
+                warnings.push(`The handoff closes ${unmentioned.join(", ")} but .codecarto/${validation.primaryOutput} never mentions ${unmentioned.length === 1 ? "that id" : "those ids"} — a closure should be visible in the report that claims to resolve it, not only in the handoff.`);
+            }
+        }
+    }
     const completionTimestamp = new Date().toISOString();
     let closeoutPath;
     let orchestratorCheckpoint;
@@ -343,5 +358,6 @@ export async function completeValidatedPhase(cwd, validation, sourceLabel) {
         updatedState,
         closeoutNotice: closeoutPath ? `Closeout: ${closeoutPath}` : undefined,
         orchestratorCheckpoint,
+        warnings,
     };
 }

package/dist/core/dashboard.js

@@ -452,7 +452,9 @@ function usagePhaseNote(phaseId, status) {
 function renderActivityTimeline(runs) {
     if (runs.length === 0)
         return "";
-    const sorted = [...runs].sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1));
+    // Newest first. The comparator must return 0 for equal keys: returning -1
+    // in both directions left same-timestamp order implementation-defined (#134).
+    const sorted = [...runs].sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : 0));
     const visible = sorted.slice(0, TIMELINE_VISIBLE_COUNT);
     const overflow = sorted.slice(TIMELINE_VISIBLE_COUNT);
     const hasSessionLinks = sorted.some((run) => Boolean(run.session_file && safeRelativeHref(run.session_file)));
@@ -507,7 +509,7 @@ function renderCloseoutsList(inputs) {
     const closeouts = inputs.closeouts;
     if (closeouts.length === 0)
         return [`<section class="cc-card cc-closeouts" id="closeouts" aria-label="Closeouts" data-section>`, `<h2>Closeouts</h2>`, `<p class="cc-empty">No closeouts yet.</p>`, `</section>`].join("\n");
-    const sorted = [...closeouts].sort((a, b) => (a.date < b.date ? 1 : -1));
+    const sorted = [...closeouts].sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
     const rows = sorted.map((c) => {
         const phase = getPhase(inputs.pipeline, c.phaseOrModule);
         const outputs = inputs.outputsPresent.get(c.phaseOrModule);
@@ -646,7 +648,7 @@ function getPhase(pipeline, phaseId) {
     return pipeline.phases.find((p) => p.id === phaseId);
 }
 function closeoutForPhase(closeouts, phaseId) {
-    return [...closeouts].filter((c) => c.phaseOrModule === phaseId).sort((a, b) => (a.date < b.date ? 1 : -1))[0];
+    return [...closeouts].filter((c) => c.phaseOrModule === phaseId).sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0))[0];
 }
 function phaseAnchor(phaseId) {
     return `phase-${phaseId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;

package/dist/core/findings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * First scaffold version whose defect templates offer `verify at runtime`.
+ * A workspace scaffolded before it had no honest action for an unsettled
+ * finding, so the pairing violation is reported as a warning there instead
+ * of failing a phase mid-run.
+ */
+export declare const FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION = "0.17.1";
+/** Evidence levels that mean "not settled by reading this source". */
+export declare const UNSETTLED_EVIDENCE_LEVELS: ReadonlySet<string>;
+/** Actions that assert the diagnosis is settled enough to act on. */
+export declare const SETTLED_FIX_ACTIONS: ReadonlySet<string>;
+/** The pre-porting action an unsettled finding takes. */
+export declare const RUNTIME_VERIFY_ACTION = "verify at runtime";
+export type FindingRow = {
+    /** The `## Pass N` heading the table sits under, when there is one. */
+    pass: string | null;
+    /** The `#` cell, verbatim. */
+    number: string;
+    /** Normalized Evidence Level cell (lowercase, markup stripped). */
+    evidence: string;
+    /** Normalized Action cell. */
+    action: string;
+    /** 1-based line of the row in the document. */
+    line: number;
+};
+export type FindingsCrossCheck = {
+    /** Violations that fail validation on a current scaffold. */
+    errors: string[];
+    /** Non-gating observations, rendered as NOTE lines. */
+    warnings: string[];
+    findings: FindingRow[];
+};
+/**
+ * Every data row of every table whose header carries both an Evidence Level
+ * and an Action column. Placeholder rows (both cells empty) are skipped so an
+ * untouched template section contributes nothing.
+ */
+export declare function parseFindingsTables(content: string): FindingRow[];
+/** Whether the report has an `## Open Questions` table, and how many filled rows it holds. */
+export declare function parseOpenQuestionsTable(content: string): {
+    present: boolean;
+    rows: number;
+};
+/**
+ * Whether the pairing violation fails validation for this workspace. True from
+ * the scaffold version that introduced `verify at runtime`; an unversioned or
+ * older scaffold only warns.
+ */
+export declare function findingsPairingGateActive(scaffoldVersion: string | undefined | null): boolean;
+/**
+ * Run the cross-checks over a phase output. Returns empty results for any
+ * document without findings tables, so non-defect phases are untouched.
+ *
+ * @param content - The primary output's markdown.
+ * @param opts.gate - Whether the pairing violation is an error (current scaffold) or a warning.
+ */
+export declare function crossCheckFindings(content: string, opts: {
+    gate: boolean;
+}): FindingsCrossCheck;

package/dist/core/findings.js

@@ -0,0 +1,145 @@
+// Mechanical cross-checks over a defect report's findings tables (issue #122).
+//
+// A run can register an open question saying "source alone cannot determine
+// which" and, in the same run, ship one of that question's candidates as
+// `strong inference` / `fix before porting`. Both artifacts validate on their
+// own criteria because nothing reads what the evidence and action cells SAY.
+// The checks here do: they are deterministic reads of two cells the model
+// wrote itself, so the gating one cannot wedge an --auto run on a heuristic.
+//
+// The findings tables are header-identical across the three defect templates
+// (`| # | Location | Defect | Severity | Evidence Level | Action |`, with an
+// optional trailing Spec Reference), which is what makes a header-driven parse
+// a parse and not a guess. Any table without both an Evidence Level and an
+// Action column is left alone.
+import { compareDottedVersions } from "./utils.js";
+/**
+ * First scaffold version whose defect templates offer `verify at runtime`.
+ * A workspace scaffolded before it had no honest action for an unsettled
+ * finding, so the pairing violation is reported as a warning there instead
+ * of failing a phase mid-run.
+ */
+export const FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION = "0.17.1";
+/** Evidence levels that mean "not settled by reading this source". */
+export const UNSETTLED_EVIDENCE_LEVELS = new Set(["open question", "external-behavior claim"]);
+/** Actions that assert the diagnosis is settled enough to act on. */
+export const SETTLED_FIX_ACTIONS = new Set(["fix before porting", "fix now"]);
+/** The pre-porting action an unsettled finding takes. */
+export const RUNTIME_VERIFY_ACTION = "verify at runtime";
+function normalizeCell(cell) {
+    return cell.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
+}
+function isTableRow(line) {
+    return line.trim().startsWith("|");
+}
+function isSeparatorRow(line) {
+    return /^\s*\|?\s*:?-{3,}/.test(line);
+}
+function splitRow(line) {
+    const trimmed = line.trim();
+    const inner = trimmed.slice(1, trimmed.endsWith("|") ? -1 : undefined);
+    return inner.split("|").map((cell) => cell.trim());
+}
+/**
+ * Every data row of every table whose header carries both an Evidence Level
+ * and an Action column. Placeholder rows (both cells empty) are skipped so an
+ * untouched template section contributes nothing.
+ */
+export function parseFindingsTables(content) {
+    const lines = content.split(/\r?\n/);
+    const rows = [];
+    let pass = null;
+    for (let i = 0; i < lines.length; i++) {
+        const heading = /^##\s+Pass\s+(\d+)\b/i.exec(lines[i]);
+        if (heading) {
+            pass = heading[1];
+            continue;
+        }
+        if (!isTableRow(lines[i]) || !isSeparatorRow(lines[i + 1] ?? ""))
+            continue;
+        const header = splitRow(lines[i]).map(normalizeCell);
+        const evidenceIdx = header.indexOf("evidence level");
+        const actionIdx = header.indexOf("action");
+        const numberIdx = header.indexOf("#");
+        if (evidenceIdx < 0 || actionIdx < 0)
+            continue;
+        for (let j = i + 2; j < lines.length && isTableRow(lines[j]); j++) {
+            const cells = splitRow(lines[j]);
+            const evidence = normalizeCell(cells[evidenceIdx] ?? "");
+            const action = normalizeCell(cells[actionIdx] ?? "");
+            if (!evidence && !action)
+                continue;
+            rows.push({ pass, number: numberIdx >= 0 ? (cells[numberIdx] ?? "").trim() : "", evidence, action, line: j + 1 });
+            i = j;
+        }
+    }
+    return rows;
+}
+/** Whether the report has an `## Open Questions` table, and how many filled rows it holds. */
+export function parseOpenQuestionsTable(content) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^##\s+Open Questions\s*$/i.test(line));
+    if (start < 0)
+        return { present: false, rows: 0 };
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i]))
+            break; // next section, no table
+        if (!isTableRow(lines[i]) || !isSeparatorRow(lines[i + 1] ?? ""))
+            continue;
+        let rows = 0;
+        for (let j = i + 2; j < lines.length && isTableRow(lines[j]); j++) {
+            if (splitRow(lines[j]).some((cell) => cell.length > 0))
+                rows++;
+        }
+        return { present: true, rows };
+    }
+    return { present: true, rows: 0 };
+}
+/**
+ * Whether the pairing violation fails validation for this workspace. True from
+ * the scaffold version that introduced `verify at runtime`; an unversioned or
+ * older scaffold only warns.
+ */
+export function findingsPairingGateActive(scaffoldVersion) {
+    if (!scaffoldVersion)
+        return false;
+    const comparison = compareDottedVersions(scaffoldVersion, FINDINGS_PAIRING_GATE_SCAFFOLD_VERSION);
+    return comparison !== null && comparison >= 0;
+}
+function describe(row) {
+    const where = row.pass ? `Pass ${row.pass} finding #${row.number || "?"}` : `finding #${row.number || "?"}`;
+    return `${where} (line ${row.line})`;
+}
+/**
+ * Run the cross-checks over a phase output. Returns empty results for any
+ * document without findings tables, so non-defect phases are untouched.
+ *
+ * @param content - The primary output's markdown.
+ * @param opts.gate - Whether the pairing violation is an error (current scaffold) or a warning.
+ */
+export function crossCheckFindings(content, opts) {
+    const findings = parseFindingsTables(content);
+    const errors = [];
+    const warnings = [];
+    if (findings.length === 0)
+        return { errors, warnings, findings };
+    for (const row of findings) {
+        if (UNSETTLED_EVIDENCE_LEVELS.has(row.evidence) && SETTLED_FIX_ACTIONS.has(row.action)) {
+            const message = `${describe(row)}: evidence level "${row.evidence}" cannot carry the settled action "${row.action}" — ` +
+                `use "${RUNTIME_VERIFY_ACTION}" or "port differently" ("investigate" on maintenance pipelines), and list the finding under ## Open Questions.`;
+            if (opts.gate)
+                errors.push(message);
+            else
+                warnings.push(`${message} Warning only: this workspace's scaffold predates the verify-at-runtime vocabulary — refresh it to make this gating.`);
+        }
+        if (row.evidence === "observed fact" && row.action === RUNTIME_VERIFY_ACTION) {
+            warnings.push(`${describe(row)}: "observed fact" paired with "${RUNTIME_VERIFY_ACTION}" contradicts itself — a settled label with an unsettled action. Pick the one that is true.`);
+        }
+    }
+    const unsettled = findings.filter((row) => UNSETTLED_EVIDENCE_LEVELS.has(row.evidence) || row.action === RUNTIME_VERIFY_ACTION);
+    const openQuestions = parseOpenQuestionsTable(content);
+    if (unsettled.length > 0 && openQuestions.present && openQuestions.rows === 0) {
+        warnings.push(`${unsettled.length} unsettled finding(s) but the ## Open Questions table is empty — each open question / external-behavior claim finding needs a row there so the hedge travels with the finding, not only with the handoff.`);
+    }
+    return { errors, warnings, findings };
+}

package/dist/core/index.d.ts

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

package/dist/core/index.js

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