codecartographer-pi 0.1.0

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

@@ -0,0 +1,17 @@
+# Defect Scan — Mechanical Pass
+
+Early, context-light defect pass. Runs after architecture and before contracts in the `pipeline-full-with-deep-audit` workflow. Covers logic and correctness, error handling, and configuration hazards — the bugs visible from local code reading.
+
+**Primary output:** `mechanical-defects.md`
+
+**Depends on:** architecture phase (required).
+
+**Pass subset (mechanical):**
+
+1. Logic and correctness
+2. Error handling and resilience
+6. Configuration and environment hazards
+
+The deeper passes (concurrency, security, API contract violations) live in the `defect-scan-semantic` phase, which runs after protocols.
+
+See `SKILL.md` for instructions. Pass-specific guidance is reused from `findings/defect-scan/passes/`.

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

@@ -0,0 +1,60 @@
+---
+name: scan-for-defects-mechanical
+description: Run the early, mechanical subset of the multi-pass defect scan — local bugs that do not need contracts or protocols context to spot. Run after the architecture phase, before contracts. Covers logic and correctness, error handling and resilience, and configuration and environment hazards. The semantic subset (concurrency, security, API contract violations) runs later in the `defect-scan-semantic` phase, after protocols.
+---
+
+# Scan For Defects — Mechanical Pass
+
+This phase runs the **early, mechanical** half of the defect-scan methodology. It catches the bugs that are visible from local code reading without needing the contracts or protocols phases to be done first. The deeper passes (concurrency, security, API contract violations) live in the later `defect-scan-semantic` phase.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`).
+
+## Prerequisites
+
+**Required:**
+- `findings/architecture/architecture-map.md` — for the layer map and public surfaces.
+
+You do **not** need contracts or protocols for this phase. If those exist already, skim them as bonus context, but do not block on them — the mechanical pass is by design context-light.
+
+## Pass Execution Order
+
+Run these three passes sequentially. Read the pass file, scan the source, record findings, then move to the next pass. Each pass file is the same one used by the legacy `defect-scan` phase — only the subset is different.
+
+| Pass | File | Focus |
+|------|------|-------|
+| 1 | `findings/defect-scan/passes/01-logic-and-correctness.md` | Dead code, boundary errors, null handling, boolean logic, control flow |
+| 2 | `findings/defect-scan/passes/02-error-handling.md` | Swallowed errors, missing cleanup, uncaught exceptions, retry gaps |
+| 6 | `findings/defect-scan/passes/06-config-and-environment.md` | Hardcoded values, missing validation, dangerous defaults, OS assumptions |
+
+Passes 3, 4, and 5 are deferred to `defect-scan-semantic` because they benefit from contracts/protocols context.
+
+## Prioritization
+
+Use the architecture map to decide emphasis:
+- **Pure library with no config?** Skim pass 6.
+- **Heavy generic-types or branching logic?** Spend extra time on pass 1.
+- **No surfaced error model in architecture?** Pass 2 may surface that gap as a finding.
+
+## Evidence and Severity Classification
+
+Use the same scheme as the legacy defect-scan SKILL:
+
+- **Evidence levels:** `observed fact`, `strong inference`, `open question`.
+- **Severity:** `critical`, `high`, `medium`, `low`.
+- **Action (pre-porting pipelines):** `fix before porting`, `port differently`, `leave behind`.
+
+See `findings/defect-scan/SKILL.md` for the full criteria; this phase intentionally does not duplicate them.
+
+## Output
+
+Write findings to the primary output using `templates/mechanical-defects.md`. Organize by pass, then by severity within each pass. End with a summary table covering only passes 1, 2, and 6.
+
+If the semantic phase later finds related defects, those go in its own report — do not amend this one after this phase is complete.
+
+## What to defer to the semantic phase
+
+- Concurrency, race conditions, and lock issues → pass 3 in `defect-scan-semantic`.
+- Auth, input validation, secrets, and trust boundary defects → pass 4 in `defect-scan-semantic`.
+- API/spec/state-machine drift → pass 5 in `defect-scan-semantic`.
+
+If you spot something semantic during this phase, record it as a `carry_forward` entry in `workflow/status.yaml` with `target_phase: defect-scan-semantic` so the later phase picks it up.

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

@@ -0,0 +1,17 @@
+# Defect Scan — Semantic Pass
+
+Deep, context-rich defect pass. Runs after protocols and before porting in the `pipeline-full-with-deep-audit` workflow. Covers concurrency, security, and API contract violations — bugs that need contracts and protocols already documented to spot reliably.
+
+**Primary output:** `semantic-defects.md`
+
+**Depends on:** architecture, contracts, protocols, and `defect-scan-mechanical` phases (all required).
+
+**Pass subset (semantic):**
+
+3. Concurrency and resource management
+4. Security and trust boundaries
+5. API contract violations
+
+The early passes (logic, error handling, config) live in the `defect-scan-mechanical` phase, which runs right after architecture.
+
+See `SKILL.md` for instructions. Pass-specific guidance is reused from `findings/defect-scan/passes/`.

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

@@ -0,0 +1,54 @@
+---
+name: scan-for-defects-semantic
+description: Run the deep, semantic subset of the multi-pass defect scan — bugs that need contracts and protocols context to spot. Run after protocols, before porting. Covers concurrency and resource management, security and trust boundaries, and API contract violations (including state machine drift). The mechanical subset (logic, error handling, config) runs earlier in the `defect-scan-mechanical` phase, after architecture.
+---
+
+# Scan For Defects — Semantic Pass
+
+This phase runs the **deep, semantic** half of the defect-scan methodology. The findings here only become legible once you know what the code is *supposed* to do — that is what the contracts and protocols phases give you. The early mechanical bugs (passes 1, 2, 6) were caught in the earlier `defect-scan-mechanical` phase.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`).
+
+## Prerequisites
+
+**Required:**
+- `findings/architecture/architecture-map.md`
+- `findings/contracts/behavioral-contracts.md` — pass 5 needs this to define "violation."
+- `findings/protocols/protocols-and-state.md` — passes 3 and 5 need this for state machine and event-ordering analysis.
+- `findings/defect-scan-mechanical/mechanical-defects.md` — read so you do not re-flag what the mechanical phase already covered.
+
+If any prerequisite is missing, stop and surface the gap. The semantic pass is the *paid-for* benefit of running the mechanical phase early; do not regress it by running the semantic pass blind.
+
+## Pass Execution Order
+
+Run these three passes sequentially. Read the pass file, scan the source, record findings, then move to the next pass. Each pass file is reused from the legacy `defect-scan` phase.
+
+| Pass | File | Focus |
+|------|------|-------|
+| 3 | `findings/defect-scan/passes/03-concurrency-and-resources.md` | Race conditions, lock issues, async pitfalls, resource leaks |
+| 4 | `findings/defect-scan/passes/04-security-and-trust.md` | Input validation, auth gaps, secrets in code, trust boundaries |
+| 5 | `findings/defect-scan/passes/05-api-contract-violations.md` | Spec vs. implementation drift, return type mismatches, state machine violations |
+
+## Prioritization
+
+Use the contracts and protocols outputs to decide emphasis:
+- **No concurrency model in protocols?** Skim pass 3, focus elsewhere.
+- **No auth system in contracts?** Skip the auth sections of pass 4, still check input validation.
+- **Heavy state machine in protocols?** Spend extra time on pass 5.
+- **Many features in contracts marked "core" or "important"?** Pass 5 spec-vs-impl drift on those is high-value.
+
+## Evidence, Severity, and Action Classification
+
+Use the scheme from `findings/defect-scan/SKILL.md`. The severity and action sets are the same as the legacy defect-scan phase.
+
+When citing a contract or protocol violation, include the contract ID or state-machine reference from the upstream finding so the porting phase can trace the chain.
+
+## Honor the carry_forward routing
+
+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.
+
+## 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.
+
+The porting phase's reverse-engineering bundle has a "Defect Synthesis" section that consolidates this report and the mechanical report — do not pre-fill that here.

package/.codecarto/findings/porting/README.md

@@ -0,0 +1,3 @@
+# Porting Findings
+
+Store porting order, migration strategy, compatibility risks, and acceptance criteria here.

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

@@ -0,0 +1,52 @@
+---
+name: reverse-engineer-for-porting
+description: Synthesize architecture, contracts, and protocol findings into a reverse-engineering bundle oriented toward reimplementation in another language or runtime.
+---
+
+# Reverse Engineer For Porting
+
+This phase synthesizes the outputs of architecture, contracts, and protocols. If defect reports exist, also read and integrate them: `findings/defect-scan/defect-report.md` (full-with-audit pipeline) or both `findings/defect-scan-mechanical/mechanical-defects.md` and `findings/defect-scan-semantic/semantic-defects.md` (full-with-deep-audit pipeline). The pipeline ensures all required phases are complete before this one runs. Read the prior phase artifacts before starting.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.
+
+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.
+- `open question`: missing or conflicting behavior that still needs evidence.
+
+Prefer concept names over source names:
+- Translate file- or class-level details into concepts such as `provider adapter`, `message normalizer`, `agent loop`, `tool executor`, `session store`, `render loop`, `UI surface`, or `product shell`.
+- Do not assume the target implementation should mirror the source folder layout.
+
+Treat layered repositories as a composition problem:
+- Identify the lowest reusable core first.
+- Separate shared middle layers from delivery surfaces.
+- Treat UI, CLI, bot, web, or deployment wrappers as adapters around shared behavior unless evidence says otherwise.
+- Look for reusable layers such as provider normalization, agent runtime, UI surfaces, and product wrappers.
+
+Sort features by porting importance:
+- `core`: required for the system to function.
+- `important`: required for parity on major workflows.
+- `optional`: valuable, but not required for a first viable port.
+- `incidental`: source-specific ergonomics or implementation accidents.
+
+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).
+- Consolidate defect-related portability hazards alongside hazards from other phases.
+
+Use the output template at `templates/reverse-engineering-bundle.md`. Produce:
+- A system summary in plain language.
+- A layer map with package or module ownership.
+- A feature contract table with porting priority (include defect references if the defect report exists).
+- A protocol and state note set.
+- Portability hazards consolidated from all prior phases.
+- Observed facts separated from inferred structure.
+
+Bias toward evidence over cleverness:
+- Prefer tests over assumptions.
+- Prefer behavior over implementation detail.
+- Mark uncertainty explicitly instead of flattening it away.
+
+When fixing defects before or during porting, use the tracker template at `templates/defect-fix-tracker.md` to log each fix, deferral, or acceptance decision. The tracker uses defect IDs from the report (D{pass}.{number}) so progress maps directly back to findings.

package/.codecarto/findings/protocols/README.md

@@ -0,0 +1,3 @@
+# Protocol Findings
+
+Store JSONL formats, RPC/message protocols, event streams, conversion rules, and state-machine notes here.

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

@@ -0,0 +1,87 @@
+---
+name: extract-protocols-and-state
+description: Extract message formats, event streams, state machines, file formats, and cross-boundary protocols from a system. Use when you need to port event-driven agents, session formats, RPC or JSONL interfaces, storage schemas, or tool-calling systems into another language or runtime.
+---
+
+# Extract Protocols And State
+
+Treat every boundary as a protocol boundary.
+
+Enumerate the boundaries first:
+- process to process
+- UI to core
+- core to provider
+- tool layer to runtime
+- runtime to persistence
+- local files to exported artifacts
+
+Prefer type definitions, schemas, and docs before implementation code:
+- Read event and message types first.
+- Read file format docs next.
+- Use source to fill ordering, retry, and recovery gaps.
+
+For each protocol, record:
+- `producer`
+- `consumer`
+- `transport or carrier`
+- `ordering guarantees`
+- `required fields`
+- `optional fields`
+- `identifiers and timestamps`
+- `error cases`
+- `restart or resume behavior`
+
+Convert control flow into a state machine:
+- Name the states.
+- Name the transitions.
+- Record guards and side effects.
+- Separate synchronous barriers from observational events.
+
+Capture persistence semantics explicitly:
+- append-only vs mutable
+- branching vs linear history
+- compaction or summarization
+- replay or resume behavior
+- locking, deduplication, or conflict handling
+
+Look for these protocol-heavy areas:
+- streamed assistant events
+- tool call validation and execution
+- session files
+- JSONL or RPC framing
+- queueing semantics
+- background event scheduling
+- transport fallbacks
+
+Treat configuration propagation as a protocol when it crosses boundaries:
+- How config values flow from files or env vars into runtime behavior.
+- Whether config changes require a restart or are hot-reloaded.
+- How config is validated and what happens on invalid input.
+- If the config propagation model is complex, use the secondary output at `findings/config-model/config-model.md`.
+
+Flag portability hazards that frequently break ports:
+- ANSI terminal semantics
+- IME or cursor positioning rules
+- filesystem locking assumptions
+- async ordering guarantees
+- OAuth token refresh behavior
+- shell quoting and OS differences
+- encoding, width, or Unicode handling
+
+Produce four outputs:
+1. `Event catalog`
+2. `State machine`
+3. `Persistent schema notes`
+4. `Compatibility hazards`
+
+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.
+- `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.
+
+Do not copy the wire syntax blindly. Preserve the meaning of the interaction, then decide how the target language should encode it.
+
+Use the output template at `templates/protocols-and-state.md`.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.

package/.codecarto/findings/public-surfaces/README.md

@@ -0,0 +1,3 @@
+# Public Surfaces Findings
+
+Store binary commands, exports, external APIs, user-facing screens, and integration surfaces here.

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

@@ -0,0 +1,3 @@
+# Reimplementation Spec Findings
+
+Final language-agnostic build plan and acceptance spec for reimplementation.

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

@@ -0,0 +1,66 @@
+---
+name: write-reimplementation-spec
+description: Convert reverse-engineering findings into a language-agnostic reimplementation plan and acceptance spec. Restate a project's features and behavior so another implementation can be built in a different language or runtime without copying the source structure.
+---
+
+# Write Reimplementation Spec
+
+Use this skill after the architecture, behavior, and protocol passes are complete enough to trust.
+
+Treat the source repo as evidence, not as a template.
+
+Define concept-level modules:
+- State each module's responsibility in one sentence.
+- List public inputs and outputs.
+- List owned state and invariants.
+- List collaborators and dependencies.
+
+Split the system into three layers of concern:
+- `core semantics`: behavior that must survive the port unchanged
+- `adapters`: integrations with terminal, browser, Slack, filesystem, cloud APIs, or SDKs
+- `delivery surfaces`: CLI, TUI, web, bot, daemon, or deployment wrappers
+
+Refactor the findings into target-language-friendly shapes:
+- Do not mirror file names or package names unless they still make sense.
+- Preserve contracts and state semantics before preserving organization.
+- Collapse source-language helper layers that exist only for tooling or typing convenience.
+
+For each external dependency, choose one stance:
+- `replace`
+- `wrap`
+- `emulate`
+- `postpone`
+
+Write the plan in this order:
+1. `System summary`
+2. `Conceptual module model`
+3. `Required behaviors`
+4. `Protocols and persisted state`
+5. `Portability hazards`
+6. `Implementation sequence`
+7. `Acceptance scenarios`
+8. `Known unknowns`
+
+Define scope tiers:
+- `minimum viable port`
+- `major-workflow parity`
+- `full parity`
+
+Write acceptance scenarios as black-box checks:
+- Inputs must be concrete.
+- Outputs and side effects must be observable.
+- Avoid assertions that depend on internal file names, classes, or source-language idioms.
+
+Call out deliberate non-goals:
+- features intentionally deferred
+- source-specific UX details not worth carrying over
+- integrations that will be stubbed first
+
+End with a spike list:
+- unknown behaviors that need a prototype
+- risky performance assumptions
+- platform-sensitive areas that need targeted tests
+
+Use the output template at `templates/reimplementation-spec.md`.
+
+The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.

package/.codecarto/findings/runtime-lifecycle/README.md

@@ -0,0 +1,3 @@
+# Runtime Lifecycle Findings
+
+Store boot flow, execution loop, session flow, compaction behavior, and runtime sequencing notes here.

package/.codecarto/findings/state-and-storage/README.md

@@ -0,0 +1,3 @@
+# State And Storage Findings
+
+Store config files, environment variables, auth material, session files, logs, caches, databases, and generated artifacts here.

package/.codecarto/skills/spec-delta-application/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: apply-spec-deltas
+description: Apply triaged spec deltas (from spike findings, defect-scan corrections, post-implementation discoveries, or any source proposing changes to a finished reimplementation spec) without rubber-stamping. Use this skill after the pipeline has produced a complete reimplementation-spec and a separate source has surfaced changes the spec should absorb. The skill enforces triage discipline (apply blockers, defer nice-to-haves, reject what doesn't fit), preserves traceability via [revised per <source> §<delta-id>] citations, and produces a DELTAS-APPLIED.md audit table.
+---
+
+# Apply Spec Deltas
+
+Use this skill when:
+
+- The pipeline has produced a complete `findings/reimplementation-spec/reimplementation-spec.md` (the spec is `complete` in status.yaml).
+- A separate source has surfaced changes the spec should absorb. Common sources:
+  - **Spike reports** (`spikes/<spike-id>/<scenario>.md` plus a `CONSOLIDATED-DELTA.md`).
+  - **Defect-scan re-runs** that find corrections to spec text.
+  - **Implementation discoveries** that contradict spec assumptions (e.g., a wire format the spec misread).
+  - **Maintainer rulings** that close prior open questions.
+
+This is a **post-pipeline** activity. `current_phase` stays `complete`. The spec is updated in place; no phase status changes.
+
+## Core posture: triage, do not rubber-stamp
+
+The single rule of this skill: **don't apply deltas verbatim without thinking.** Every delta gets categorized, and only some get applied. Rubber-stamping a delta list produces an incorrect spec — the discipline is the value.
+
+Triage every delta into one of four buckets:
+
+| Bucket | Definition | Action |
+|---|---|---|
+| **APPLY** | Delta is a real correction or required addition; the spec is wrong without it. | Edit the spec body. Add a `[revised per <source> §<delta-id>]` marker at the changed section. Record in DELTAS-APPLIED.md. |
+| **CLARIFY** | Delta proposes wording change; the spec's *meaning* is correct but the language is ambiguous. | Edit the spec wording (not the rule). Record in DELTAS-APPLIED.md as a clarification. |
+| **DEFER** | Delta is a real improvement but not load-bearing for the next implementation step. | Add to BACKLOG.md with rationale and a back-reference. Do NOT edit the spec. |
+| **REJECT** | Delta is wrong on close reading (premise was incorrect, scope was misread, the rule it proposes already exists, etc.). | Document in DELTAS-APPLIED.md with a one-line rationale. Do NOT edit the spec. |
+
+The previous wisdom: any delta you can't decisively bucket should default to DEFER. The cost of a missed correction is one re-application pass; the cost of a bad correction is shipped.
+
+## Citation convention
+
+Every applied or clarified delta leaves a citation marker in the spec body so a future reader can trace the change back to its source.
+
+```
+<original spec text>  [revised per spike-3-cancellation.md §Δ7]
+<revised spec text>   [revised per spike-3-cancellation.md §Δ7]
+```
+
+The marker form is **canonical**, not per-session: `[revised per <source-filename> §<delta-id>]`. The citation convention list at the front-matter of the spec (or the project's `CONVENTIONS.md`) should include `[revised per ...]` as a recognized form.
+
+## Step-by-step
+
+### 1. Pre-flight
+
+- Confirm `findings/reimplementation-spec/reimplementation-spec.md` is complete (PASS or PASS WITH GAPS validation block).
+- Read every delta source named in the session prompt (the spike reports, the defect-scan addendum, the maintainer-decision file).
+- Read the spec once end-to-end if you haven't recently. The spec's structure determines where deltas land.
+- Read the project's `CONVENTIONS.md` if present — some deltas may be moved into convention entries instead of the spec body.
+
+### 2. Triage every delta
+
+For each delta from each source:
+
+- **Read the delta carefully.** Is the premise correct? Does the affected spec section actually say what the delta claims it says?
+- **Categorize: APPLY / CLARIFY / DEFER / REJECT.** Put each delta in exactly one bucket.
+- If APPLY or CLARIFY: identify the exact spec section to edit. Note line numbers (or section anchors) for the audit table.
+- If DEFER: write a one-line BACKLOG.md entry now, don't wait.
+- If REJECT: write a one-paragraph rationale now, don't wait.
+
+### 3. Apply changes (in spec-source order, not delta-order)
+
+- Group APPLY/CLARIFY deltas by the spec section they touch.
+- Edit each section once (not once per delta), even if multiple deltas converge on the same section.
+- Add the `[revised per <source> §<delta-id>]` citation marker at the changed paragraph.
+- After edits in a section, re-read the section in full to confirm it still hangs together — neighboring claims may need adjustment.
+
+### 4. Re-run validation on the spec
+
+Re-run validation per `workflow/VALIDATE.md` against the spec's `completion_criteria`. The spec was PASS or PASS WITH GAPS before; it must remain PASS or PASS WITH GAPS after. If the validation block degrades, the deltas weren't applied carefully — fix the spec body, do NOT soften the validation criteria. (This rule is load-bearing — see the discipline notes in the source feedback.)
+
+### 5. Write DELTAS-APPLIED.md
+
+Use `templates/deltas-applied.md`. The audit table records every delta from every source — APPLY, CLARIFY, DEFER, REJECT — with one row per delta. Future revision passes read this file to know which deltas have already been processed.
+
+### 6. Update the spec's front-matter citation conventions list
+
+If the spec has a "Citation Conventions" section (or similar), confirm `[revised per ...]` is listed as a recognized citation form. If not, add it.
+
+### 7. Closeout
+
+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`.
+- Update `status.yaml` only if a delta closed an `open_questions` or `carry_forward` entry — do NOT change `current_phase` (stays `complete`).
+- 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
+
+- **Don't rubber-stamp.** A delta list is a *proposal*. The spec-delta session decides.
+- **Don't soften the spec's validation criteria** to make the post-edit spec pass. If the validation degrades, the spec body is wrong, not the criteria.
+- **Don't edit deltas in the source files.** The spike report (or defect addendum, or wherever the delta came from) is read-only. DELTAS-APPLIED.md is the audit; the spike report is the evidence.
+- **Don't change status.yaml's current_phase.** This is post-pipeline work; the pipeline is `complete`.
+- **Don't apply deltas across spec sections without reading the neighbors.** A claim in §3.2 may depend on a claim in §3.1; editing one without the other produces silent contradictions.
+
+## Output template
+
+Use `templates/deltas-applied.md` for the audit table.

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

@@ -0,0 +1,143 @@
+# Architecture Map
+
+<!--
+  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.
+-->
+
+## System Intent
+
+<!-- One paragraph: what does this system do, who is it for, and what problem does it solve? -->
+
+## Layer Map
+
+<!--
+  List each layer, package, or module. For each:
+  - Name
+  - Role (core semantics / protocol or normalization / persistence or state / UI or rendering / integration adapter / product shell)
+  - Key responsibilities
+  - What it depends on
+  - What depends on it
+
+  Call out dependency cycles explicitly.
+  Mark packages that are wrappers around shared internals.
+-->
+
+### Package Inventory
+
+| Package / Module | Role | Public Entrypoints | Key Dependencies | Runtime Surface |
+|---|---|---|---|---|
+| | | | | |
+
+### Dependency Direction
+
+<!-- Describe the dependency graph. Which layer is the stable base? Where do cycles exist? -->
+
+## Public Surfaces
+
+<!--
+  List every boundary the outside world touches:
+  - Binaries and CLI commands
+  - Exported libraries and public types
+  - Network or RPC interfaces
+  - File formats and persistent artifacts
+  - User-facing screens or workflows
+-->
+
+## Runtime Lifecycle
+
+<!--
+  How does the system start, run, and stop?
+  - Boot sequence
+  - Main event loop or request handling
+  - Shutdown and cleanup
+  - Background tasks or scheduled work
+-->
+
+## Concurrency Model
+
+<!--
+  How does the system handle concurrent work?
+  - Threading model (single-threaded, thread pool, async/await, actor model, goroutines)
+  - Event loop or reactor pattern
+  - Shared state and synchronization (locks, channels, atomic operations)
+  - Connection pooling and resource management
+  - Rate limiting or backpressure mechanisms
+  - Performance-critical paths and known bottlenecks
+
+  Mark portability hazards: concurrency models rarely translate 1:1 across languages.
+-->
+
+## Build and Packaging
+
+<!--
+  How is the system built and distributed?
+  - Build tool(s) and build scripts
+  - Multi-stage or multi-target builds
+  - Output artifacts (binaries, containers, packages, bundles)
+  - CI/CD pipeline (if visible from repo)
+  - Platform-specific packaging (npm, pip, cargo, Docker, etc.)
+
+  If the build pipeline is complex, write detailed notes to the secondary output
+  at findings/build-and-deploy/build-and-deploy.md instead.
+-->
+
+## Porting Priorities
+
+<!--
+  Which parts matter most for a reimplementation?
+  - core: required for the system to function
+  - important: required for parity on major workflows
+  - optional: valuable but not needed for first viable port
+  - incidental: source-specific ergonomics
+-->
+
+| Component | Priority | Rationale |
+|---|---|---|
+| | | |
+
+## Durable State
+
+<!--
+  Config files, environment variables, auth material, session files,
+  logs, caches, databases, generated artifacts.
+-->
+
+## Open Questions
+
+<!-- Items that are still genuinely unknown — need a runtime test, maintainer decision, or spec ruling.
+     NOT items deferred to a later phase in this pipeline (those go in Carry-Forward).
+     Each entry: { id, kind, description, deferred_reason }. See workflow/status.yaml schema. -->
+
+| ID | Kind | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Carry-Forward
+
+<!-- Items deferred to a specific later phase whose rubric is the right place to close them.
+     Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
+     Mirror these into workflow/status.yaml under this phase's carry_forward list. -->
+
+| ID | Target Phase | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+---
+
+## Validation
+
+<!-- Fill in this table per workflow/VALIDATE.md. The rows below match the full pipeline.
+     Adjust rows to match your active pipeline's completion_criteria if using a variant. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | The system intent is documented. | PASS / PARTIAL / FAIL | |
+| 2 | The layer map and dependency direction are documented. | PASS / PARTIAL / FAIL | |
+| 3 | Public surfaces are identified. | PASS / PARTIAL / FAIL | |
+| 4 | Runtime lifecycle, concurrency model, and porting priorities are summarized. | PASS / PARTIAL / FAIL | |
+| 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL