codecartographer-pi 0.1.0

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

@@ -0,0 +1,109 @@
+# Semantic Defects Report — [project_name]
+
+<!--
+  Output template for the `defect-scan-semantic` phase.
+  Covers passes 3, 4, and 5 from the defect-scan methodology — the bugs that
+  need contracts and protocols context to spot reliably.
+  See findings/defect-scan-semantic/SKILL.md for instructions.
+-->
+
+## Scan Context
+
+- **Source:** `../` (repository root)
+- **Architecture reference:** `findings/architecture/architecture-map.md`
+- **Contracts reference:** `findings/contracts/behavioral-contracts.md`
+- **Protocols reference:** `findings/protocols/protocols-and-state.md`
+- **Mechanical defects reference:** `findings/defect-scan-mechanical/mechanical-defects.md`
+- **Pipeline:** [pipeline variant name]
+- **Date:** [date]
+- **Scope:** Semantic passes only (3 concurrency, 4 security, 5 contract violations). Mechanical passes (1 logic, 2 error handling, 6 configuration) were covered earlier in `defect-scan-mechanical`.
+
+---
+
+## Pass 3: Concurrency and Resource Management
+
+<!-- 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." -->
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 4: Security and Trust Boundaries
+
+<!-- Cite the contract entry (e.g., feature ID) that the finding violates, when relevant. -->
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 5: API Contract Violations
+
+<!-- Each finding should pair the source contract/protocol reference with the diverging code location. -->
+
+| # | Location | Defect | Severity | Evidence Level | Action | Spec Reference |
+|---|----------|--------|----------|----------------|--------|----------------|
+| 1 | | | | | | |
+
+---
+
+## Summary
+
+### Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| Critical | |
+| High | |
+| Medium | |
+| Low | |
+| **Total** | |
+
+### Findings by Pass
+
+| Pass | Critical | High | Medium | Low | Total |
+|------|----------|------|--------|-----|-------|
+| 3. Concurrency and resources | | | | | |
+| 4. Security and trust | | | | | |
+| 5. API contract violations | | | | | |
+
+### Top Findings
+
+<!-- List the most impactful findings across the semantic passes, ranked by severity and confidence.
+     Include: pass number, location, one-line defect description, severity, recommended action. -->
+
+1.
+2.
+3.
+4.
+5.
+
+### Carry-Forward Closure
+
+<!-- carry_forward entries in status.yaml that targeted defect-scan-semantic and were closed here. -->
+
+| ID | Source Phase | Closed Because |
+|----|--------------|---------------|
+| | | |
+
+---
+
+## Validation
+
+<!-- Fill in this table per workflow/VALIDATE.md. The rows below match the semantic-pass scope. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | All three semantic passes (3, 4, 5) 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 | Pass 5 findings cite the contract or protocol reference they violate. | PASS / PARTIAL / FAIL | |
+| 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 | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/thread-log-entry-template.md

@@ -0,0 +1,27 @@
+# THREAD_LOG.md Entry Template (legacy / one-line index form)
+
+This template is the **one-line index entry** appended to `THREAD_LOG.md` per session.
+The full body of each session lives in a separate closeout file under `closeouts/`.
+
+For the closeout file itself, use `templates/closeout-template.md`.
+
+## Entry format
+
+```
+- YYYY-MM-DD — <phase-or-module> — <one-line-summary> — [closeout](closeouts/YYYY-MM-DD-phase-or-module.md)
+```
+
+## Example
+
+```
+- 2026-05-02 — architecture — mapped 14 packages across 3 layers; 2 carry-forward items routed to defect-scan — [closeout](closeouts/2026-05-02-architecture.md)
+```
+
+## Rules
+
+- One line per session, no exceptions.
+- Date in ISO format (YYYY-MM-DD).
+- `<phase-or-module>` matches the closeout filename's slug.
+- Summary is one clause, no more than ~20 words.
+- Always link to the closeout file. If there is no closeout file, the entry doesn't belong here.
+- Before appending, scan the bottom 5 entries to avoid duplicating a prior session's entry.

package/.codecarto/workflow/VALIDATE.md

@@ -0,0 +1,81 @@
+# Phase Validation
+
+Run this check after completing a phase's primary output, before marking the phase as complete.
+
+## Steps
+
+1. Re-read the phase's `completion_criteria` from the active pipeline YAML (check the `pipeline` field in `workflow/status.yaml` for the file path).
+2. Re-read the primary output you just produced.
+3. For each criterion, answer one of:
+   - **PASS**: the output clearly satisfies this criterion. Cite the section or line.
+   - **PARTIAL**: the output addresses this but is incomplete or shallow. State what is missing.
+   - **FAIL**: the output does not address this criterion at all.
+4. Append a validation block to the end of the primary output file (see format below).
+5. If any criterion is FAIL, do not mark the phase as complete. Fix the output first.
+6. If any criterion is PARTIAL, route the gap appropriately:
+   - If the gap is **still genuinely unknown** (needs a runtime test, maintainer decision, or spec ruling that no later phase will close), record it under `open_questions` for the phase in `workflow/status.yaml`.
+   - If the gap is **deferred to a specific later phase** in this pipeline (the next phase's rubric is the right place to close it), record it under `carry_forward` with an explicit `target_phase` field. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
+   - You may still mark the phase complete if the gaps are documented under one of the two lists and are non-blocking for downstream phases.
+
+## Validation Block Format
+
+Append this to the end of every primary output file:
+
+```markdown
+---
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | [criterion text from pipeline.yaml] | PASS / PARTIAL / FAIL | [section reference or note] |
+| 2 | ... | ... | ... |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL
+```
+
+## Worked PARTIAL Example
+
+Below is what a real PASS WITH GAPS block looks like — useful when a phase finishes meaningful work but is honest about its incompleteness. Note how the PARTIAL row's `Evidence` cell *names what is missing*, not just "incomplete."
+
+```markdown
+---
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | The system intent is documented. | PASS | §System Intent (paragraph). |
+| 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`. |
+
+**Validated by:** 2026-05-02 (architecture phase, session 1)
+**Overall:** PASS WITH GAPS
+```
+
+The `arch-CF2` entry then appears in `workflow/status.yaml` under the architecture phase's `carry_forward`:
+
+```yaml
+phases:
+  architecture:
+    carry_forward:
+      - id: arch-CF2
+        kind: defer-to-phase
+        target_phase: protocols
+        description: MCP server endpoints and websocket subscription channel listed by name only; schemas not extracted.
+        deferred_reason: Wire-format extraction is the protocols phase's rubric; deferring avoids guessing at shapes here.
+```
+
+The protocols phase, on session start, scans `carry_forward` entries with `target_phase: protocols`, picks `arch-CF2` up, and either resolves it (deletes the entry once the schemas are pinned) or re-defers to a later phase.
+
+## Rules
+
+- Do not skip validation. Every primary output must end with a validation block.
+- Do not inflate results. A criterion you are uncertain about is PARTIAL, not PASS.
+- If the output file already has a validation block from a prior session, replace it with a fresh one.
+- Validation checks the output against the pipeline's criteria only. It does not re-evaluate the source code.
+- For automated agents: a phase with any FAIL result must not have its status set to `complete` in status.yaml.
+- A PARTIAL row's `Evidence` cell must name what is missing and (if applicable) which `open_questions` or `carry_forward` entry tracks the gap. "Incomplete" alone is not honest enough.

package/.codecarto/workflow/pipeline-architecture-only.yaml

@@ -0,0 +1,38 @@
+workflow_name: codebase-architecture-scan
+workflow_version: 3
+workflow_goal: Produce an architecture map for an unfamiliar source repository.
+source_location: ../
+validation_protocol: workflow/VALIDATE.md
+phase_order:
+  - architecture
+phases:
+  - id: architecture
+    purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
+    skill_path: findings/architecture/SKILL.md
+    output_template: templates/architecture-map.md
+    depends_on: []
+    primary_output: findings/architecture/architecture-map.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+    completion_criteria:
+      - The system intent is documented.
+      - The layer map and dependency direction are documented.
+      - Public surfaces are identified.
+      - Runtime lifecycle, concurrency model, and porting priorities are summarized.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.

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

@@ -0,0 +1,61 @@
+workflow_name: codebase-defect-scan
+workflow_version: 3
+workflow_goal: Produce an architecture map and a multi-pass defect report for a codebase under active maintenance.
+source_location: ../
+validation_protocol: workflow/VALIDATE.md
+phase_order:
+  - architecture
+  - defect-scan
+phases:
+  - id: architecture
+    purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
+    skill_path: findings/architecture/SKILL.md
+    output_template: templates/architecture-map.md
+    depends_on: []
+    primary_output: findings/architecture/architecture-map.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+    completion_criteria:
+      - The system intent is documented.
+      - The layer map and dependency direction are documented.
+      - Public surfaces are identified.
+      - Runtime lifecycle, concurrency model, and porting priorities are summarized.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: defect-scan
+    purpose: Run a multi-pass defect scan to identify bugs, security issues, and code quality problems for maintenance prioritization.
+    skill_path: findings/defect-scan/SKILL.md
+    output_template: templates/defect-report.md
+    depends_on:
+      - architecture
+    primary_output: findings/defect-scan/defect-report.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+    completion_criteria:
+      - At least three analysis passes produced findings or documented "no defects found."
+      - Each finding has location, severity, evidence level, and recommended action.
+      - 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.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.

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

@@ -0,0 +1,188 @@
+workflow_name: codebase-reverse-engineering-with-audit
+workflow_version: 3
+workflow_goal: Produce a reusable reverse-engineering bundle with a defect scan, so legacy bugs can be identified before porting.
+source_location: ../
+validation_protocol: workflow/VALIDATE.md
+phase_order:
+  - architecture
+  - defect-scan
+  - contracts
+  - protocols
+  - porting
+  - reimplementation-spec
+phases:
+  - id: architecture
+    purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
+    skill_path: findings/architecture/SKILL.md
+    output_template: templates/architecture-map.md
+    depends_on: []
+    primary_output: findings/architecture/architecture-map.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+    completion_criteria:
+      - The system intent is documented.
+      - The layer map and dependency direction are documented.
+      - Public surfaces are identified.
+      - Runtime lifecycle, concurrency model, and porting priorities are summarized.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: defect-scan
+    purpose: Run a multi-pass defect scan to identify legacy bugs, security issues, and code quality problems before porting.
+    skill_path: findings/defect-scan/SKILL.md
+    output_template: templates/defect-report.md
+    depends_on:
+      - architecture
+    primary_output: findings/defect-scan/defect-report.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+    completion_criteria:
+      - At least three analysis passes produced findings or documented "no defects found."
+      - Each finding has location, severity, evidence level, and recommended action.
+      - 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.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: contracts
+    purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
+    skill_path: findings/contracts/SKILL.md
+    output_template: templates/behavioral-contracts.md
+    depends_on:
+      - architecture
+    primary_output: findings/contracts/behavioral-contracts.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+    completion_criteria:
+      - User-facing surfaces are split by surface type.
+      - Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior.
+      - Security and authorization model is documented (if applicable).
+      - Contract ownership is mapped back to a layer or package.
+      - A black-box acceptance list is included.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: protocols
+    purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
+    skill_path: findings/protocols/SKILL.md
+    output_template: templates/protocols-and-state.md
+    depends_on:
+      - architecture
+    primary_output: findings/protocols/protocols-and-state.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+    completion_criteria:
+      - An event catalog is documented.
+      - A state machine is documented.
+      - Persistent schema notes are documented.
+      - Compatibility hazards are documented.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: porting
+    purpose: Synthesize architecture, contracts, protocols, and defect findings into a reverse-engineering bundle oriented toward porting.
+    skill_path: findings/porting/SKILL.md
+    output_template: templates/reverse-engineering-bundle.md
+    depends_on:
+      - architecture
+      - contracts
+      - protocols
+    primary_output: findings/porting/reverse-engineering-bundle.md
+    secondary_outputs:
+      - path: findings/public-surfaces/public-surfaces.md
+        mode: append
+      - path: findings/runtime-lifecycle/runtime-lifecycle.md
+        mode: append
+      - path: findings/state-and-storage/state-and-storage.md
+        mode: append
+      - path: findings/build-and-deploy/build-and-deploy.md
+        mode: append
+      - path: findings/config-model/config-model.md
+        mode: append
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+      - findings/contracts/behavioral-contracts.md
+      - findings/protocols/protocols-and-state.md
+      - findings/defect-scan/defect-report.md
+    completion_criteria:
+      - 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).
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.
+  - id: reimplementation-spec
+    purpose: Produce the final language-agnostic reimplementation plan and acceptance spec.
+    skill_path: findings/reimplementation-spec/SKILL.md
+    output_template: templates/reimplementation-spec.md
+    depends_on:
+      - porting
+    primary_output: findings/reimplementation-spec/reimplementation-spec.md
+    secondary_outputs: []
+    required_reads:
+      - GUIDE.md
+      - workflow/status.yaml
+      - findings/architecture/architecture-map.md
+      - findings/contracts/behavioral-contracts.md
+      - findings/protocols/protocols-and-state.md
+      - findings/porting/reverse-engineering-bundle.md
+    completion_criteria:
+      - Concept-level modules are defined.
+      - Required behaviors are stated.
+      - Protocol and persisted state expectations are stated.
+      - Acceptance scenarios and known unknowns are included.
+      - Findings are marked with evidence levels.
+    handoff_requirements:
+      - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
+      - Update workflow/status.yaml.
+      - Append a summary entry to THREAD_LOG.md.