codecartographer-pi 0.17.0 → 0.17.1

package/.codecarto/GUIDE.md

@@ -17,7 +17,7 @@ CodeCartographer distinguishes two roles. They are different jobs — but they a
 **Orchestrator.** The persistent chat driving the run — normally the very session reading this guide. The role is defined by its **duties**, not by who executes phases:
 
 - **Curate `CONVENTIONS.md` and `DECISIONS.md`**: promote patterns when they recur; append cross-cutting decisions as they land.
-- **Re-triage open questions at every phase boundary.** A question's `kind` label is itself a claim that needs evidence: before accepting `needs-maintainer-decision` or `needs-runtime-test`, re-test whether the question has become answerable by reading. A mislabeled question suppresses verification for every later phase (the `orchestration` guide topic records a real four-phase failure).
+- **Re-triage open questions at every phase boundary.** A question's `kind` label is itself a claim that needs evidence: before accepting `needs-maintainer-decision` or `needs-runtime-test`, re-test whether the question has become answerable by reading. A mislabeled question suppresses verification for every later phase (the `orchestration` guide topic records a real four-phase failure). The duty has a counterpart: when re-triage concludes a question genuinely still needs a runtime test, no finding in the next phase may assert one of that question's candidate answers with a settled action (`fix before porting`, `fix now`) — it inherits the question's uncertainty (`verify at runtime`) until runtime evidence closes the question.
 - **Sweep for contradictions** between the incoming phase's required reads and earlier phases' `owner_notes`. A measured fact that contradicts a summarized claim is a gap to route, not a nuance to smooth over.
 - **Route gaps**: confirm each completed phase's declared secondary outputs were written or explicitly routed, and that handoff `decisions` deferring work landed somewhere a later phase will actually see.
 - **Gate strategic forks** with the user: pipeline switches, opinionated-vs-agnostic specs, scope changes.

package/.codecarto/findings/architecture/SKILL.md

@@ -84,6 +84,7 @@ Write the output in seven sections:
 Mark every conclusion with one of these evidence levels:
 - `observed fact`: direct statement from docs, tests, schemas, types, or code.
 - `strong inference`: architectural conclusion drawn from multiple facts.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS); unverifiable by reading this code, so it stays unsettled until a runtime probe or that system's own source confirms it.
 - `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
 - `open question`: missing or conflicting behavior that still needs evidence.
 

package/.codecarto/findings/contracts/SKILL.md

@@ -79,6 +79,7 @@ End with a black-box acceptance list:
 Mark every finding with one of these evidence levels:
 - `observed fact`: direct statement from docs, tests, schemas, types, or code.
 - `strong inference`: behavioral conclusion drawn from multiple facts.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS); unverifiable by reading this code, so it stays unsettled until a runtime probe or that system's own source confirms it.
 - `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
 - `open question`: missing or conflicting behavior that still needs evidence.
 

package/.codecarto/findings/defect-scan/SKILL.md

@@ -45,8 +45,11 @@ Not every pass applies to every codebase. Use the architecture map to decide emp
 Mark every finding with one of these evidence levels:
 - `observed fact`: the defect is directly visible in the code.
 - `strong inference`: the defect is highly likely based on multiple code observations.
+- `external-behavior claim`: the claim is about a component outside the analyzed source tree — a server, engine, driver, third-party API, or OS — including how it parses a payload, what it silently ignores, and version-dependent behavior. Not obtainable at any read depth of this source: settling it needs a runtime probe against the pinned version, or that system's own source at that version. This is not a weaker `strong inference`; it is a claim about a different artifact. "The client sends a map where the server's API documents an array" is an `external-behavior claim` about the server, even when both halves of the sentence are observed facts.
 - `open question`: the code is suspicious but would need runtime testing to confirm.
 
+**Cite or hedge quantities.** Any number in a finding — a file size, a default value, a call-site count, a version, a timeout — cites the file and line or the command output it was read from, or is written as an explicit estimate ("~300 MB, not measured"). A plausible specific stated in the same register as a read one is how a 32.8 MB artifact gets recorded as ~300 MB and a default of -20 as -5.
+
 ## Severity Classification
 
 Assign one severity per finding:
@@ -59,10 +62,11 @@ Assign one severity per finding:
 
 Tag each finding with a recommended action. Use the set that matches your pipeline:
 
-**Pre-porting pipelines** (full-with-audit, full-with-deep-audit):
+**Pre-porting pipelines** (full-with-audit, full-with-deep-audit, scout-first):
 - `fix before porting`: the defect would carry into a new implementation if not addressed first.
 - `port differently`: the new implementation should handle this case differently by design.
 - `leave behind`: the defect is specific to the source implementation and won't survive porting.
+- `verify at runtime`: the diagnosis names behavior of a system outside the analyzed source, or otherwise cannot be settled by reading; a runtime probe must confirm it before any fix is designed. Its destination is the spec's Spike List plus a `post_pipeline` entry of `kind: spike` — not a design change.
 
 **Maintenance pipelines** (defect-scan):
 - `fix now`: the defect is actively causing or risking problems.
@@ -72,6 +76,16 @@ Tag each finding with a recommended action. Use the set that matches your pipeli
 
 Determine which action set to use by checking the `pipeline` field in `workflow/status.yaml`.
 
+### Pairing rules — the evidence level bounds the action
+
+A finding's action may not assert more certainty than its evidence level carries:
+
+- Evidence `open question` or `external-behavior claim` ⇒ action is `verify at runtime` or `port differently` (pre-porting), or `investigate` (maintenance). **Never `fix before porting` or `fix now`.** A fix designed from an unsettled diagnosis can convert working behavior into the one shape the external system ignores — a real run recommended exactly that reshape, and runtime testing inverted it.
+- Evidence `observed fact` ⇒ action is not `verify at runtime`. A settled label with an unsettled action contradicts itself; pick the one that is true.
+- Every finding whose evidence is `open question` or `external-behavior claim` also appears in the report's **Open Questions** table, so the hedge travels with the finding into every document a later phase or a human reads — not only into the handoff.
+
+Validation checks the first rule mechanically on the findings tables; on a current scaffold a violation fails the phase. If a routed `carry_forward` item derives from an open question of `kind: needs-runtime-test` that is still unresolved, the finding that addresses it inherits that uncertainty: it closes the carry-forward with `verify at runtime`, not with a settled action, unless the question itself is closed with runtime evidence in the same handoff.
+
 ## Output
 
 Write findings to the primary output using the template at `templates/defect-report.md`.

package/.codecarto/findings/defect-scan/passes/01-logic-and-correctness.md

@@ -41,7 +41,7 @@ For each finding, record:
 - **Defect**: what is wrong, in one sentence.
 - **Evidence**: what you observed that proves or strongly suggests the defect.
 - **Severity**: critical (incorrect results in normal use), high (incorrect results in edge cases), medium (dead code or latent risk), low (style issue with correctness implications).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/02-error-handling.md

@@ -47,7 +47,7 @@ For each finding, record:
 - **Defect**: what error scenario is mishandled.
 - **Evidence**: the specific code pattern or path that demonstrates the gap.
 - **Severity**: critical (data loss or corruption on failure), high (silent failure in normal operations), medium (poor error messages or missing cleanup), low (observability gap).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/03-concurrency-and-resources.md

@@ -46,7 +46,7 @@ For each finding, record:
 - **Defect**: what concurrent or resource scenario is mishandled.
 - **Evidence**: the specific shared state, missing synchronization, or unclosed resource.
 - **Severity**: critical (data corruption or deadlock in normal operation), high (race condition in common paths), medium (resource leak under error conditions), low (theoretical race in rarely-exercised path).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/04-security-and-trust.md

@@ -54,7 +54,7 @@ For each finding, record:
 - **Defect**: what security property is violated.
 - **Evidence**: the specific code path, missing check, or exposed secret.
 - **Severity**: critical (actively exploitable, data exposure, auth bypass), high (exploitable with some effort or preconditions), medium (defense-in-depth gap, hardcoded non-production secret), low (missing header, informational disclosure).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/05-api-contract-violations.md

@@ -47,9 +47,10 @@ For each finding, record:
 - **Location**: file path and function/method name.
 - **Defect**: what contract is violated and how.
 - **Spec source**: where the expected behavior is documented (docstring, type signature, contracts phase, protocols phase, README).
+- **Which side implements the contract**: the analyzed code is often the *caller* of a contract another system implements (an HTTP API, an inference engine, a driver). A divergence between what this code sends and what the other side documents is only an `observed fact` about this code; what the other side actually does with it — accepts, ignores, rejects — is an `external-behavior claim` until a runtime probe against the pinned version says otherwise, and its action is `verify at runtime`, never `fix before porting`.
 - **Evidence**: the specific divergence between spec and implementation.
 - **Severity**: critical (public API returns wrong results), high (documented behavior incorrect in edge cases), medium (internal API inconsistency), low (stale docs, minor parameter mismatch).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan/passes/06-config-and-environment.md

@@ -50,7 +50,7 @@ For each finding, record:
 - **Defect**: what configuration or environment hazard exists.
 - **Evidence**: the specific hardcoded value, missing validation, or dangerous default.
 - **Severity**: critical (security exposure in default config, data loss on misconfiguration), high (production failure from missing validation), medium (hardcoded value that will break in a different environment), low (undocumented config behavior).
-- **Evidence level**: observed fact / strong inference / open question.
+- **Evidence level**: observed fact / strong inference / external-behavior claim / open question. A claim about what another system does with this code's output (a server, engine, driver, third-party API, OS) is an `external-behavior claim`, not a `strong inference` — see findings/defect-scan/SKILL.md §Evidence Classification.
 
 ## What to skip
 

package/.codecarto/findings/defect-scan-mechanical/SKILL.md

@@ -39,9 +39,10 @@ Use the architecture map to decide emphasis:
 
 Use the same scheme as the legacy defect-scan SKILL:
 
-- **Evidence levels:** `observed fact`, `strong inference`, `open question`.
+- **Evidence levels:** `observed fact`, `strong inference`, `external-behavior claim`, `open question`.
 - **Severity:** `critical`, `high`, `medium`, `low`.
-- **Action (pre-porting pipelines):** `fix before porting`, `port differently`, `leave behind`.
+- **Action (pre-porting pipelines):** `fix before porting`, `port differently`, `leave behind`, `verify at runtime`.
+- **Pairing rule:** `open question` or `external-behavior claim` evidence takes `verify at runtime` or `port differently`, never `fix before porting`, and the finding also appears in the report's Open Questions table. Validation checks this on the findings tables.
 
 See `findings/defect-scan/SKILL.md` for the full criteria; this phase intentionally does not duplicate them.
 

package/.codecarto/findings/defect-scan-semantic/SKILL.md

@@ -47,6 +47,8 @@ When citing a contract or protocol violation, include the contract ID or state-m
 
 Read the `carry_forward` entries in `workflow/status.yaml` whose `target_phase` is `defect-scan-semantic`. The mechanical phase may have routed semantic-flavored sightings here for closure.
 
+**Closing a routed item does not settle the question it came from.** Before closing a carry-forward, check whether it derives from an `open_questions` entry of `kind: needs-runtime-test` that is still unresolved — the mechanical phase typically registers the question and routes one of its candidate explanations onward in the same handoff. If the question stands, the finding that addresses the carry-forward inherits its uncertainty: evidence `external-behavior claim` or `open question`, action `verify at runtime`, and a row in this report's Open Questions table naming the question's id. Asserting one of the question's candidates as `strong inference` / `fix before porting` while the question remains open is the contradiction this rule exists to prevent — a real run did exactly that, and runtime testing inverted the finding. Only runtime evidence (or the external system's own source at the pinned version) closes such a question; when you have it, list the question in `open_question_closures` and cite the evidence in the finding.
+
 ## Output
 
 Write findings to the primary output using `templates/semantic-defects.md`. Organize by pass, then by severity within each pass. End with a summary table covering only passes 3, 4, and 5.

package/.codecarto/findings/porting/SKILL.md

@@ -19,6 +19,7 @@ Keep four classes of findings separate throughout:
 - `observed fact`: direct statements from docs, tests, schemas, types, and code.
 - `strong inference`: architectural conclusions drawn from multiple facts.
 - `portability hazard`: assumptions tied to the source language, runtime, terminal, OS, or third-party SDKs.
+- `external-behavior claim`: a claim about what a system outside this source tree does (a server, engine, driver, third-party API, OS) — unverifiable at any read depth here; carry it forward as unsettled, never promote it to a fact.
 - `open question`: missing or conflicting behavior that still needs evidence.
 
 Prefer concept names over source names:
@@ -39,7 +40,7 @@ Sort features by porting importance:
 
 If the defect report is available, integrate defect findings into the porting bundle:
 - Reference relevant defects in the feature contract table.
-- Tag each referenced defect with a porting recommendation: `fix before porting` (the defect would carry into a new implementation), `port differently` (the new implementation should handle this case differently by design), or `leave behind` (the defect is specific to the source implementation and won't survive porting).
+- Tag each referenced defect with a porting recommendation: `fix before porting` (the defect would carry into a new implementation), `port differently` (the new implementation should handle this case differently by design), `leave behind` (the defect is specific to the source implementation and won't survive porting), or `verify at runtime` (the diagnosis is an `external-behavior claim` or `open question` — carry it as a spike for the spec, and do not design around an unverified diagnosis). Preserve `verify at runtime` as written: flattening it into one of the settled three is how a hedge stops traveling.
 - Consolidate defect-related portability hazards alongside hazards from other phases.
 
 Use the output template at `templates/reverse-engineering-bundle.md`. Produce:

package/.codecarto/findings/protocols/SKILL.md

@@ -77,6 +77,7 @@ Produce four outputs:
 Mark every finding with one of these evidence levels:
 - `observed fact`: direct statement from docs, tests, schemas, types, or code.
 - `strong inference`: protocol conclusion drawn from multiple facts.
+- `external-behavior claim`: a claim about what the peer or a system outside this source tree does with a message (how it parses, what it ignores, version-dependent behavior); unverifiable by reading this code, so it stays unsettled until a runtime capture or that system's own source confirms it.
 - `portability hazard`: assumption tied to the source language, runtime, terminal, OS, or third-party SDKs.
 - `open question`: missing or conflicting behavior that still needs evidence.
 

package/.codecarto/findings/reimplementation-spec/SKILL.md

@@ -69,7 +69,7 @@ End with a spike list:
 - risky performance assumptions
 - platform-sensitive areas that need targeted tests
 
-For every defect in the bundle, preserve its disposition (`fix before porting`, `port differently`, or `leave behind`) and convert it into an explicit design consequence or acceptance check.
+For every defect in the bundle, preserve its disposition (`fix before porting`, `port differently`, `leave behind`, or `verify at runtime`) and convert it into an explicit design consequence or acceptance check — except `verify at runtime`, which becomes a Spike List entry and a `post_pipeline` entry of `kind: spike` in your handoff, never a design consequence: the diagnosis has not been confirmed, and designing around it would build the unverified claim into the new system.
 
 Use the output template at `templates/reimplementation-spec.md`.
 

package/.codecarto/templates/architecture-map.md

@@ -3,7 +3,7 @@
 <!--
   Output template for the architecture phase.
   Fill in each section. Remove placeholder text. Keep the section headers.
-  Mark every conclusion as: fact / strong inference / open question.
+  Mark every conclusion as: fact / strong inference / external-behavior claim / open question.
 -->
 
 ## System Intent

package/.codecarto/templates/defect-report.md

@@ -16,6 +16,12 @@
 <!-- For each finding: location, defect, evidence, severity, evidence level, action. -->
 <!-- Sort by severity: critical → high → medium → low. -->
 <!-- If no findings, write "No defects found in this category." -->
+<!-- Evidence Level: observed fact / strong inference / external-behavior claim / open question.
+     Action — pre-porting pipelines: fix before porting / port differently / leave behind / verify at runtime;
+     maintenance pipelines: fix now / track / accept / investigate.
+     Pairing rule (validated mechanically): open question or external-behavior claim ⇒ verify at
+     runtime or port differently (pre-porting) / investigate (maintenance), never fix before porting
+     or fix now; and list the finding in ## Open Questions below. -->
 
 | # | Location | Defect | Severity | Evidence Level | Action |
 |---|----------|--------|----------|----------------|--------|
@@ -99,6 +105,21 @@
 
 ---
 
+## Open Questions
+
+<!-- Every finding whose Evidence Level is open question or external-behavior claim gets a row
+     here, so the hedge travels with the finding into this document — not only into the handoff.
+     Mirror each row into your phase handoff's open_questions (kind: needs-runtime-test unless a
+     maintainer decision or spec ruling is what is missing). Derived findings lists the finding
+     numbers (e.g. "5.2, 4.1") that depend on this question; none of them may carry a settled
+     action while the question stands. -->
+
+| ID | Kind | Question | Why source cannot settle it | Derived findings |
+|----|------|----------|-----------------------------|------------------|
+| | | | | |
+
+---
+
 ## Coverage and limits
 
 - Inspected scope:
@@ -120,6 +141,8 @@
 | 4 | Summary tables are complete and counts match the detailed findings. | PASS / PARTIAL / FAIL | |
 | 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
 | 6 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+| 7 | Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table. | PASS / PARTIAL / FAIL | |
+| 8 | Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate. | PASS / PARTIAL / FAIL | |
 
 **Validated by:** [session identifier or date]
 **Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/mechanical-defects.md

@@ -22,6 +22,11 @@
 <!-- For each finding: location, defect, evidence, severity, evidence level, action. -->
 <!-- Sort by severity: critical → high → medium → low. -->
 <!-- If no findings, write "No defects found in this category." -->
+<!-- Evidence Level: observed fact / strong inference / external-behavior claim / open question.
+     Action: fix before porting / port differently / leave behind / verify at runtime.
+     Pairing rule (validated mechanically): open question or external-behavior claim ⇒
+     verify at runtime or port differently, never fix before porting; and list the finding
+     in ## Open Questions below. -->
 
 | # | Location | Defect | Severity | Evidence Level | Action |
 |---|----------|--------|----------|----------------|--------|
@@ -90,6 +95,21 @@
 
 ---
 
+## Open Questions
+
+<!-- Every finding whose Evidence Level is open question or external-behavior claim gets a row
+     here, so the hedge travels with the finding into this document — not only into the handoff.
+     Mirror each row into your phase handoff's open_questions (kind: needs-runtime-test unless a
+     maintainer decision or spec ruling is what is missing). Derived findings lists the finding
+     numbers (e.g. "1.3, 6.1") that depend on this question; none of them may carry a settled
+     action while the question stands. -->
+
+| ID | Kind | Question | Why source cannot settle it | Derived findings |
+|----|------|----------|-----------------------------|------------------|
+| | | | | |
+
+---
+
 ## Coverage and limits
 
 - Inspected scope:
@@ -110,6 +130,8 @@
 | 4 | Summary tables are complete and counts match the detailed findings. | PASS / PARTIAL / FAIL | |
 | 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
 | 6 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+| 7 | Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table. | PASS / PARTIAL / FAIL | |
+| 8 | Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate. | PASS / PARTIAL / FAIL | |
 
 **Validated by:** [session identifier or date]
 **Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/reverse-engineering-bundle.md

@@ -86,7 +86,7 @@
 
 | Defect ID | Source Report | One-line Description | Severity | Disposition | Required design consequence |
 |-----------|---------------|----------------------|----------|-------------|-----------------------------|
-| | | | | fix before porting / port differently / leave behind | |
+| | | | | fix before porting / port differently / leave behind / verify at runtime | |
 
 ## Observed Facts vs. Inferred Structure
 
@@ -159,7 +159,7 @@
 | 1 | The system summary, layer map, contract table, protocol notes, and porting findings are synthesized. | PASS / PARTIAL / FAIL | |
 | 2 | Portability hazards and open questions are separated from facts. | PASS / PARTIAL / FAIL | |
 | 3 | Feature importance is sorted for porting. | PASS / PARTIAL / FAIL | |
-| 4 | Known defects are referenced in the Defect Synthesis with porting recommendations (fix before porting / port differently / leave behind), or the section explicitly notes that no defect scan ran. | PASS / PARTIAL / FAIL | |
+| 4 | Known defects are referenced in the Defect Synthesis with porting recommendations (fix before porting / port differently / leave behind / verify at runtime), or the section explicitly notes that no defect scan ran. | PASS / PARTIAL / FAIL | |
 | 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
 | 6 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
 | 7 | The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers. | PASS / PARTIAL / FAIL | |

package/.codecarto/templates/semantic-defects.md

@@ -25,6 +25,12 @@
 <!-- For each finding: location, defect, evidence, severity, evidence level, action. -->
 <!-- Cite the protocol or state-machine entry that the finding violates, when relevant. -->
 <!-- If no findings, write "No defects found in this category." -->
+<!-- Evidence Level: observed fact / strong inference / external-behavior claim / open question.
+     Action: fix before porting / port differently / leave behind / verify at runtime.
+     Pairing rule (validated mechanically): open question or external-behavior claim ⇒
+     verify at runtime or port differently, never fix before porting; and list the finding
+     in ## Open Questions below. A finding that closes a routed carry-forward derived from a
+     still-open needs-runtime-test question inherits that uncertainty. -->
 
 | # | Location | Defect | Severity | Evidence Level | Action |
 |---|----------|--------|----------|----------------|--------|
@@ -45,6 +51,9 @@
 ## Pass 5: API Contract Violations
 
 <!-- Each finding should pair the source contract/protocol reference with the diverging code location. -->
+<!-- When the analyzed code is the CALLER of a contract another system implements, what that system
+     does with the payload is an external-behavior claim (action: verify at runtime) until a runtime
+     probe against the pinned version says otherwise — see passes/05 "Which side implements the contract". -->
 
 | # | Location | Defect | Severity | Evidence Level | Action | Spec Reference |
 |---|----------|--------|----------|----------------|--------|----------------|
@@ -95,6 +104,21 @@
 
 ---
 
+## Open Questions
+
+<!-- Every finding whose Evidence Level is open question or external-behavior claim gets a row
+     here, so the hedge travels with the finding into this document — not only into the handoff.
+     Include any still-open needs-runtime-test question a closed carry-forward derived from.
+     Mirror each row into your phase handoff's open_questions. Derived findings lists the finding
+     numbers (e.g. "5.2") that depend on this question; none of them may carry a settled action
+     while the question stands. -->
+
+| ID | Kind | Question | Why source cannot settle it | Derived findings |
+|----|------|----------|-----------------------------|------------------|
+| | | | | |
+
+---
+
 ## Coverage and limits
 
 - Inspected scope:
@@ -115,6 +139,8 @@
 | 4 | Findings are organized by pass and sorted by severity; summary tables match the detailed findings. | PASS / PARTIAL / FAIL | |
 | 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
 | 6 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+| 7 | Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table. | PASS / PARTIAL / FAIL | |
+| 8 | Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate. | PASS / PARTIAL / FAIL | |
 
 **Validated by:** [session identifier or date]
 **Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/workflow/VALIDATE.md

@@ -50,7 +50,7 @@ Below is what a real PASS WITH GAPS block looks like — useful when a phase fin
 | 2 | The layer map and dependency direction are documented. | PASS | §Layer Map; dependency direction in §Layer Map → "Dependency Direction." |
 | 3 | Public surfaces are identified. | PARTIAL | CLI commands and HTTP routes enumerated (§Public Surfaces). MCP server endpoints and the websocket subscription channel are listed by name only — schemas not extracted. Routed to `carry_forward` as `arch-CF2` with `target_phase: protocols`. |
 | 4 | Runtime lifecycle, concurrency model, and porting priorities are summarized. | PASS | §Runtime Lifecycle, §Concurrency Model, §Porting Priorities (table). |
-| 5 | Findings are marked with evidence levels. | PASS | All inferences marked `observed fact` / `strong inference` / `portability hazard` / `open question`. |
+| 5 | Findings are marked with evidence levels. | PASS | All inferences marked `observed fact` / `strong inference` / `portability hazard` / `external-behavior claim` / `open question`. |
 
 **Validated by:** 2026-05-02 (architecture phase, session 1)
 **Overall:** PASS WITH GAPS

package/.codecarto/workflow/pipeline-defect-scan.yaml

@@ -56,6 +56,8 @@ phases:
       - Findings are organized by pass and sorted by severity.
       - Summary tables are complete and counts match the detailed findings.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.

package/.codecarto/workflow/pipeline-full-with-audit.yaml

@@ -60,6 +60,8 @@ phases:
       - Findings are organized by pass and sorted by severity.
       - Summary tables are complete and counts match the detailed findings.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
@@ -159,7 +161,7 @@ phases:
       - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
       - Portability hazards and open questions are separated from facts.
       - Feature importance is sorted for porting.
-      - Known defects are referenced with porting recommendations (fix before porting / port differently / leave behind).
+      - Known defects are referenced with porting recommendations (fix before porting / port differently / leave behind / verify at runtime).
       - Findings are marked with evidence levels.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.

package/.codecarto/workflow/pipeline-full-with-deep-audit.yaml

@@ -62,6 +62,8 @@ phases:
       - Summary tables are complete and counts match the detailed findings.
       - Items spotted that are actually semantic in nature are routed onward via a carry_forward entry in the phase handoff targeting defect-scan-semantic.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
@@ -157,6 +159,8 @@ phases:
       - Findings are organized by pass and sorted by severity; summary tables match the detailed findings.
       - Any carry_forward entries that targeted defect-scan-semantic have been resolved or explicitly re-routed.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
@@ -196,7 +200,7 @@ phases:
       - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
       - Portability hazards and open questions are separated from facts.
       - Feature importance is sorted for porting.
-      - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind).
+      - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind / verify at runtime).
       - Findings are marked with evidence levels.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.

package/.codecarto/workflow/pipeline-scout-first.yaml

@@ -90,6 +90,8 @@ phases:
       - Summary tables are complete and counts match the detailed findings.
       - Items spotted that are actually semantic in nature are routed onward via a carry_forward entry in the phase handoff targeting defect-scan-semantic.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
@@ -194,6 +196,8 @@ phases:
       - Findings are organized by pass and sorted by severity; summary tables match the detailed findings.
       - Any carry_forward entries that targeted defect-scan-semantic have been resolved or explicitly re-routed.
       - Findings are marked with evidence levels.
+      - Unsettled findings (evidence level open question or external-behavior claim) carry an unsettled action (verify at runtime or port differently on pre-porting pipelines; investigate on maintenance pipelines), never a settled one, and each appears in the Open Questions table.
+      - Every quantitative specific in a finding (size, count, default, version, timeout) cites the file and line or command output it was read from, or is marked as an estimate.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
     handoff_requirements:
       - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
@@ -236,7 +240,7 @@ phases:
       - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
       - Portability hazards and open questions are separated from facts.
       - Feature importance is sorted for porting.
-      - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind).
+      - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind / verify at runtime).
       - Findings are marked with evidence levels.
       - Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots.
       - The Source Index makes the bundle a self-contained compression boundary and identifies targeted deep-read triggers.

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.0
+scaffold_version: 0.17.1

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`.
 
 ---
 
@@ -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.
 
 ---
 
@@ -373,7 +373,7 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_refresh_scaffold` | MCP-only ([#159](https://github.com/HuginnIndustries/CodeCartographer/issues/159)) |
 | `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 +584,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/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

@@ -15,7 +15,7 @@ A CodeCartographer **library** is a directory of published reimplementation-spec
 | `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_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
 

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/dist/core/amendment.js

@@ -9,7 +9,7 @@ import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { 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. */
@@ -134,7 +134,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