codecartographer-pi 0.1.0

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

@@ -0,0 +1,104 @@
+# Mechanical Defects Report — [project_name]
+
+<!--
+  Output template for the `defect-scan-mechanical` phase.
+  Covers passes 1, 2, and 6 from the defect-scan methodology — the bugs visible
+  from local code reading without contracts or protocols context.
+  See findings/defect-scan-mechanical/SKILL.md for instructions.
+-->
+
+## Scan Context
+
+- **Source:** `../` (repository root)
+- **Architecture reference:** `findings/architecture/architecture-map.md`
+- **Pipeline:** [pipeline variant name]
+- **Date:** [date]
+- **Scope:** Mechanical passes only (1 logic, 2 error handling, 6 configuration). Semantic passes (3 concurrency, 4 security, 5 contract violations) deferred to `defect-scan-semantic` after protocols.
+
+---
+
+## Pass 1: Logic and Correctness
+
+<!-- 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." -->
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 2: Error Handling and Resilience
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 6: Configuration and Environment Hazards
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Summary
+
+### Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| Critical | |
+| High | |
+| Medium | |
+| Low | |
+| **Total** | |
+
+### Findings by Pass
+
+| Pass | Critical | High | Medium | Low | Total |
+|------|----------|------|--------|-----|-------|
+| 1. Logic and correctness | | | | | |
+| 2. Error handling | | | | | |
+| 6. Config and environment | | | | | |
+
+### Top Findings
+
+<!-- List the most impactful findings across the mechanical passes, ranked by severity and confidence.
+     Include: pass number, location, one-line defect description, severity, recommended action. -->
+
+1.
+2.
+3.
+4.
+5.
+
+### Routed To Semantic Phase
+
+<!-- Items spotted during this phase that are actually semantic in nature
+     (concurrency, security, contract drift). Mirror these into status.yaml as
+     carry_forward entries with target_phase: defect-scan-semantic. -->
+
+| ID | Description | Why Routed |
+|----|-------------|-----------|
+| | | |
+
+---
+
+## Validation
+
+<!-- Fill in this table per workflow/VALIDATE.md. The rows below match the mechanical-pass scope. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | At least two of the three mechanical passes (1, 2, 6) produced findings or documented "no defects found." | PASS / PARTIAL / FAIL | |
+| 2 | Each finding has location, severity, evidence level, and recommended action. | PASS / PARTIAL / FAIL | |
+| 3 | Findings are organized by pass and sorted by severity. | PASS / PARTIAL / FAIL | |
+| 4 | Summary tables are complete and counts match the detailed findings. | 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

package/.codecarto/templates/protocols-and-state.md

@@ -0,0 +1,126 @@
+# Protocols and State
+
+<!--
+  Output template for the protocols phase.
+  Fill in each section. Remove placeholder text. Keep the section headers.
+  Treat every boundary as a protocol boundary.
+-->
+
+## Boundaries Identified
+
+<!--
+  List the protocol boundaries found:
+  - process to process
+  - UI to core
+  - core to provider
+  - tool layer to runtime
+  - runtime to persistence
+  - local files to exported artifacts
+-->
+
+## Event Catalog
+
+<!--
+  For each protocol or event stream:
+-->
+
+### [Protocol / Event Stream Name]
+
+| Field | Value |
+|---|---|
+| **Producer** | |
+| **Consumer** | |
+| **Transport or carrier** | |
+| **Ordering guarantees** | |
+| **Required fields** | |
+| **Optional fields** | |
+| **Identifiers and timestamps** | |
+| **Error cases** | |
+| **Restart or resume behavior** | |
+
+<!-- Repeat for each protocol. -->
+
+## State Machine
+
+<!--
+  For each significant state machine:
+  - Name the states
+  - Name the transitions
+  - Record guards and side effects
+  - Separate synchronous barriers from observational events
+
+  ASCII diagrams or tables are both acceptable.
+-->
+
+### [State Machine Name]
+
+| Current State | Event / Trigger | Guard | Next State | Side Effects |
+|---|---|---|---|---|
+| | | | | |
+
+## Persistent Schema Notes
+
+<!--
+  For each persistence mechanism:
+  - Append-only vs mutable
+  - Branching vs linear history
+  - Compaction or summarization rules
+  - Replay or resume behavior
+  - Locking, deduplication, or conflict handling
+-->
+
+## Compatibility Hazards
+
+<!--
+  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
+-->
+
+| Hazard | Where It Appears | Severity | Notes |
+|---|---|---|---|
+| | | | |
+
+## 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.
+     Common target from protocols: porting (synthesis-level resolution).
+     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 | An event catalog is documented. | PASS / PARTIAL / FAIL | |
+| 2 | A state machine is documented. | PASS / PARTIAL / FAIL | |
+| 3 | Persistent schema notes are documented. | PASS / PARTIAL / FAIL | |
+| 4 | Compatibility hazards are documented. | 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

package/.codecarto/templates/reimplementation-spec-opinionated.md

@@ -0,0 +1,183 @@
+# Reimplementation Spec — <Project Name>
+
+<!--
+  Output template for the reimplementation-spec phase, OPINIONATED variant.
+
+  Use this template when the orchestrator's strategic-alignment hook (see GUIDE.md) has
+  pre-locked: target stack, project identity, scope cuts, named modules, and named primitives.
+
+  This is a SIBLING of templates/reimplementation-spec.md (the language-agnostic default), not a
+  replacement. Pick at session start based on the strategic-alignment conversation:
+
+  - Default (any port to any stack)        → templates/reimplementation-spec.md
+  - Opinionated (locked stack + identity)  → templates/reimplementation-spec-opinionated.md (this file)
+
+  The differences from the default template:
+    - Project identity (name, language, runtime, lint/format toolchain) is fixed at the top.
+    - "External Dependencies" is replaced with "Locked Stack" — the answer is given, not chosen.
+    - "Layer Split" is replaced with "Named Module Inventory" — modules have committed names.
+    - "Acceptance Scenarios" stays — scenarios are independent of stack choice.
+    - Adds "Spec Conventions" (citation forms, evidence-level codes, [revised per ...] marker).
+    - Adds "Spike List" up-front because opinionated specs typically pre-identify spikes.
+
+  Fill in each section. Remove placeholder text. Keep the section headers.
+-->
+
+## Project Identity
+
+| Field | Value |
+|---|---|
+| **Project name** | <e.g., Thaumaturge> |
+| **CLI command** | <e.g., thaum> |
+| **Primary language / runtime** | <e.g., TypeScript on Bun> |
+| **License** | <e.g., Apache-2.0> |
+| **Lint / format / test toolchain** | <e.g., oxlint, oxfmt, bun test> |
+| **Target platforms** | <e.g., macOS x64/aarch64, Linux x64/aarch64> |
+| **Source we are porting** | <e.g., codex (../) — see findings/architecture/architecture-map.md> |
+
+## System Summary
+
+<!-- Restate the system's purpose and scope for the person who will build the new version. -->
+
+## Spec Conventions
+
+<!-- Up-front so a reader knows how to interpret citations and markers. -->
+
+- **Section anchors** are H2 (`##`) and H3 (`###`). Cross-references in the spec use `§<section>`.
+- **Source citations** by phase: `[contracts §X]`, `[protocols §X]`, `[porting Finding N]`,
+  `[defect-scan §Pass.N]`.
+- **Evidence levels** appear inline in italic: *observed fact*, *strong inference*,
+  *portability hazard*, *open question*.
+- **Revised markers** for post-pipeline delta applications: `[revised per <source> §<delta-id>]`
+  (see `skills/spec-delta-application/SKILL.md`).
+- **Required behaviors** are normative. The verb form pins the rule:
+  - "MUST" = invariant, fail-build-if-violated.
+  - "SHOULD" = strong default; deviation requires justification in DECISIONS.md.
+  - "MAY" = permitted; both behaviors are valid.
+
+## Named Module Inventory
+
+<!--
+  Modules have committed names because the stack is locked. List every module the
+  reimplementation will produce, in dependency-from-leaf-to-root order.
+-->
+
+| Module | Responsibility | Public Inputs | Public Outputs | Owned State | Depends On |
+|---|---|---|---|---|---|
+| <module-name-1> | | | | | |
+| <module-name-2> | | | | | |
+
+## Locked Stack
+
+<!--
+  The opinionated equivalent of "External Dependencies." The answer is given, not chosen.
+  List every external dependency with the committed choice and rationale.
+-->
+
+| Dependency | Committed Choice | Rationale | Stance (replace/wrap/emulate/postpone source) |
+|---|---|---|---|
+| <e.g., HTTP client> | <e.g., native fetch> | <e.g., Bun ships it; zero-dep target> | replace |
+| <e.g., Sandbox primitive> | <e.g., landlock + seccomp on Linux, sandbox-exec on macOS> | <e.g., kernel-supported> | replace |
+
+## Required Behaviors
+
+<!-- What the reimplementation must do. Derived from contracts. Use MUST/SHOULD/MAY pinning. -->
+
+## Protocols and Persisted State
+
+<!-- Wire formats, state machines, and persistence rules that must be preserved.
+     Derived from protocols. Cite back to protocols phase by section anchor. -->
+
+## Portability Hazards
+
+<!-- Risks specific to the locked stack. (In opinionated mode, "portability across stacks" is
+     not a concern; "portability across OS targets within the locked stack" usually is.) -->
+
+## Implementation Sequence
+
+<!-- Suggested build order, named-module by named-module. -->
+
+### Module Order
+
+1. <module-1>  — <one-line: what unblocks after this is done>
+2. <module-2>  — ...
+3. ...
+
+### Scope Tiers
+
+**v0 (minimum viable port):**
+<!-- Which named modules ship in v0; which are tripwire-stubbed (see CONVENTIONS.md). -->
+
+**v1 (major-workflow parity):**
+<!-- Which modules promote from stub to real; which new modules land. -->
+
+**v2 (full parity):**
+<!-- Final state. -->
+
+## Acceptance Scenarios
+
+<!--
+  Black-box checks with concrete inputs and observable outputs.
+  Independent of source-language internals. The acceptance scenarios are the same for both
+  language-agnostic and opinionated modes — what differs is the implementation, not the
+  observable contract.
+-->
+
+| # | Scenario | Input | Expected Output / Side Effect |
+|---|----------|-------|-------------------------------|
+| 1 | | | |
+
+## Spike List
+
+<!--
+  In opinionated mode, the spike list is up-front (the orchestrator usually has identified
+  the spikes during strategic alignment). Each spike has a goal, a success criterion, and a
+  named scratch directory.
+-->
+
+| # | Spike | Goal | Success Criterion | Scratch Path |
+|---|---|---|---|---|
+| 1 | | | | spikes/<id>/ |
+
+## Deliberate Non-Goals
+
+<!--
+  Features intentionally deferred, source-specific UX not worth carrying over,
+  integrations that will be stubbed first.
+-->
+
+## Known Unknowns
+
+<!-- Items that are still genuinely unknown — need a prototype, runtime test, maintainer decision,
+     or spec ruling. Same shape as the language-agnostic template. -->
+
+| ID | Kind | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Carry-Forward
+
+<!-- Items deferred to post-pipeline work (spike, delta, amendment).
+     Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }. -->
+
+| ID | Target Phase | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+---
+
+## Validation
+
+<!-- Fill in this table per workflow/VALIDATE.md. Same criteria as the language-agnostic template;
+     the opinionated form changes the body, not the validation rubric. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | Concept-level modules are defined. | PASS / PARTIAL / FAIL | |
+| 2 | Required behaviors are stated. | PASS / PARTIAL / FAIL | |
+| 3 | Protocol and persisted state expectations are stated. | PASS / PARTIAL / FAIL | |
+| 4 | Acceptance scenarios and known unknowns are included. | 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

package/.codecarto/templates/reimplementation-spec.md

@@ -0,0 +1,148 @@
+# Reimplementation Spec
+
+<!--
+  Output template for the reimplementation-spec phase.
+  This is the final deliverable: a language-agnostic build plan.
+  Fill in each section. Remove placeholder text. Keep the section headers.
+-->
+
+## System Summary
+
+<!-- Restate the system's purpose and scope for the person who will build the new version. -->
+
+## Conceptual Module Model
+
+<!--
+  For each module:
+  - Responsibility (one sentence)
+  - Public inputs and outputs
+  - Owned state and invariants
+  - Collaborators and dependencies
+-->
+
+### [Module Name]
+
+| Field | Value |
+|---|---|
+| **Responsibility** | |
+| **Public inputs** | |
+| **Public outputs** | |
+| **Owned state** | |
+| **Invariants** | |
+| **Collaborators** | |
+
+<!-- Repeat for each module. -->
+
+## Layer Split
+
+<!--
+  Assign each module to one of:
+  - core semantics: behavior that must survive the port unchanged
+  - adapters: integrations with terminal, browser, filesystem, cloud APIs, SDKs
+  - delivery surfaces: CLI, TUI, web, bot, daemon, deployment wrappers
+-->
+
+| Module | Layer | Notes |
+|---|---|---|
+| | | |
+
+## Required Behaviors
+
+<!-- What the reimplementation must do. Derived from contracts. -->
+
+## Protocols and Persisted State
+
+<!-- What wire formats, state machines, and persistence rules must be preserved. Derived from protocols. -->
+
+## External Dependencies
+
+<!-- For each external dependency, choose a stance. -->
+
+| Dependency | Stance (replace/wrap/emulate/postpone) | Rationale |
+|---|---|---|
+| | | |
+
+## Portability Hazards
+
+<!-- Risks specific to the reimplementation effort. -->
+
+## Implementation Sequence
+
+<!-- Suggested build order. -->
+
+### Scope Tiers
+
+**Minimum viable port:**
+<!-- What must work for the system to be usable at all. -->
+
+**Major-workflow parity:**
+<!-- What must work to cover the primary use cases. -->
+
+**Full parity:**
+<!-- Everything the original does. -->
+
+## Acceptance Scenarios
+
+<!--
+  Black-box checks with concrete inputs and observable outputs.
+  No references to source-language internals.
+-->
+
+| # | Scenario | Input | Expected Output / Side Effect |
+|---|----------|-------|-------------------------------|
+| 1 | | | |
+
+## Deliberate Non-Goals
+
+<!--
+  Features intentionally deferred, source-specific UX not worth carrying over,
+  integrations that will be stubbed first.
+-->
+
+## Known Unknowns
+
+<!-- Items that are still genuinely unknown — need a prototype, runtime test, maintainer decision, or spec ruling.
+     This is the reimplementation-spec phase's terminal "open_questions" — items the pipeline can't close
+     because they require executing code (a spike) or a decision the orchestrator owns.
+     Each entry: { id, kind, description, deferred_reason }. -->
+
+| ID | Kind | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Carry-Forward
+
+<!-- Reimplementation-spec is the terminal phase in most pipelines, so most items belong in Known Unknowns
+     above. Use this section only when post-pipeline work (spikes, deltas, amendments) is the right place
+     to close an item. Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
+     Allowed target_phase values for post-pipeline: "spike", "delta", "amendment". -->
+
+| ID | Target Phase | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Spike List
+
+<!--
+  - Unknown behaviors that need a prototype
+  - Risky performance assumptions
+  - Platform-sensitive areas that need targeted tests
+-->
+
+---
+
+## 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 | Concept-level modules are defined. | PASS / PARTIAL / FAIL | |
+| 2 | Required behaviors are stated. | PASS / PARTIAL / FAIL | |
+| 3 | Protocol and persisted state expectations are stated. | PASS / PARTIAL / FAIL | |
+| 4 | Acceptance scenarios and known unknowns are included. | 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

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

@@ -0,0 +1,141 @@
+# Reverse-Engineering Bundle
+
+<!--
+  Output template for the porting phase.
+  This is a synthesis of architecture, contracts, and protocols.
+  Fill in each section. Remove placeholder text. Keep the section headers.
+-->
+
+## System Summary
+
+<!-- One to three paragraphs summarizing the system in plain language, aimed at someone who will reimplement it. -->
+
+## Layer Map With Ownership
+
+<!--
+  Synthesized from the architecture phase.
+  Each layer/module with its role and what it owns.
+-->
+
+| Layer / Module | Role | Owns |
+|---|---|---|
+| | | |
+
+## Feature Contract Table
+
+<!--
+  Synthesized from the contracts phase.
+  Summary table of all features with their priority for porting.
+-->
+
+| Feature | Surface | Priority (core/important/optional/incidental) | Key Contracts | Notes |
+|---|---|---|---|---|
+| | | | | |
+
+## Protocol and State Notes
+
+<!--
+  Synthesized from the protocols phase.
+  Summary of protocols, state machines, and persistence that a reimplementation must preserve.
+-->
+
+## Portability Hazards
+
+<!--
+  Consolidated from all prior phases.
+  Separate from facts — these are risks, not certainties.
+-->
+
+| Hazard | Source Phase | Impact | Mitigation |
+|---|---|---|---|
+| | | | |
+
+## Defect Synthesis
+
+<!--
+  Consolidate the defect findings into a single porting view.
+
+  - For pipelines with a single defect-scan phase (e.g. pipeline-full-with-audit):
+    pull from `findings/defect-scan/defect-report.md`.
+  - For pipelines with the split scan (e.g. pipeline-full-with-deep-audit):
+    pull from BOTH `findings/defect-scan-mechanical/mechanical-defects.md`
+    AND `findings/defect-scan-semantic/semantic-defects.md`.
+  - For pipelines without a defect scan (e.g. pipeline.yaml or pipeline-lite):
+    write "No defect scan ran in this pipeline." and skip the table.
+
+  This section is the porting-oriented view of defects — it should answer
+  "which defects must the reimplementation design around, and how?" not
+  re-list every finding. Keep it under one screen.
+-->
+
+| Defect ID | Source Report | One-line Description | Severity | Porting Recommendation |
+|-----------|---------------|----------------------|----------|------------------------|
+| | | | | fix before porting / port differently / leave behind |
+
+## Observed Facts vs. Inferred Structure
+
+<!--
+  Explicitly separate what is documented/tested from what was inferred.
+-->
+
+### Observed Facts
+
+<!-- Direct statements from docs, tests, schemas, types, and code. -->
+
+### Inferred Structure
+
+<!-- Architectural conclusions drawn from multiple facts. -->
+
+## Domain Glossary
+
+<!--
+  Shared vocabulary of domain-specific terms used across the codebase.
+  Include terms that a reimplementer needs to understand, especially:
+  - Terms with project-specific meaning that differs from common usage
+  - Abbreviations or acronyms used in code and docs
+  - Entity names and their relationships
+  - Business rules expressed as domain concepts
+-->
+
+| Term | Definition | Where Used |
+|---|---|---|
+| | | |
+
+## 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.
+     Common target from porting: reimplementation-spec (rule-pinning, opinionated decisions).
+     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 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 | |
+| 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL