codecartographer-pi 0.17.0 → 0.18.0

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.
@@ -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,7 @@ 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.
+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/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/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/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/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/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.18.0