codecartographer-pi 0.1.0

package/.codecarto/templates/behavioral-contracts.md

@@ -0,0 +1,134 @@
+# Behavioral Contracts
+
+<!--
+  Output template for the contracts phase.
+  Fill in each section. Remove placeholder text. Keep the section headers.
+  Split analysis by user-facing surface.
+-->
+
+## Surfaces Covered
+
+<!-- List which surface types this codebase exposes (CLI, TUI, web UI, API/SDK, bot, storage formats). -->
+
+## Feature Contracts
+
+<!--
+  For each significant feature, create a contract entry.
+  Group by surface type.
+-->
+
+### [Surface Type: e.g., CLI]
+
+#### [Feature Name]
+
+| Field | Value |
+|---|---|
+| **Feature** | |
+| **Trigger or input** | |
+| **Defaults** | |
+| **Observable output** | |
+| **Side effects** | |
+| **Persisted state** | |
+| **Error behavior** | |
+| **Retry or recovery behavior** | |
+| **Owner (layer/package)** | |
+
+<!-- Repeat for each feature. -->
+
+## High-Value Behaviors
+
+<!--
+  Specific notes on these areas (if applicable to this codebase):
+  - Cancellation and abort handling
+  - Streaming and partial output
+  - Queueing or follow-up behavior
+  - Compaction and summarization
+  - Persistence and resume flows
+  - Tool execution and validation
+-->
+
+## Security and Authorization
+
+<!--
+  If the system has auth or access control, document:
+  - Authentication method(s) (OAuth, API keys, session tokens, SSO)
+  - Authorization model (RBAC, ABAC, ACLs, capability-based)
+  - Trust boundaries (what is trusted vs untrusted input)
+  - Permission system (who can do what, how permissions are checked)
+  - Secret management (how tokens, keys, and credentials are stored and rotated)
+  - Session security (expiration, refresh, invalidation)
+  - CORS, CSP, or other web security policies (if applicable)
+
+  Skip this section if the system has no auth model (e.g., a pure library or CLI tool).
+-->
+
+## Configuration Model
+
+<!--
+  How does configuration flow through the system?
+  - Config sources and precedence (env vars > config file > defaults)
+  - Config file format and location
+  - Feature flags and how they're toggled
+  - Environment-specific overrides (dev, staging, prod)
+  - Config validation and error handling for bad config
+
+  If the config model is complex, write detailed notes to the secondary output
+  at findings/config-model/config-model.md instead.
+-->
+
+## Doc/Test Conflicts
+
+<!-- Any cases where documentation and test behavior disagree. -->
+
+## Black-Box Acceptance List
+
+<!--
+  Scenario-style checks that another implementation can run without referencing the source.
+  Use concrete preconditions and expected outcomes.
+-->
+
+| # | Scenario | Precondition | Action | Expected Outcome |
+|---|----------|--------------|--------|------------------|
+| 1 | | | | |
+
+## 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 targets from contracts: protocols (wire-format details), 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.
+     IMPORTANT: The rows below must match the completion_criteria in your ACTIVE pipeline YAML.
+     The default rows below match the full, full-with-audit, and full-with-deep-audit pipelines (6 criteria).
+     For pipeline-lite.yaml (5 criteria): DELETE row 3 (security) — that criterion is not in the lite pipeline. -->
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | User-facing surfaces are split by surface type. | PASS / PARTIAL / FAIL | |
+| 2 | Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior. | PASS / PARTIAL / FAIL | |
+| 3 | Security and authorization model is documented (if applicable). | PASS / PARTIAL / FAIL | |
+| 4 | Contract ownership is mapped back to a layer or package. | PASS / PARTIAL / FAIL | |
+| 5 | A black-box acceptance list is included. | PASS / PARTIAL / FAIL | |
+| 6 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/closeout-template.md

@@ -0,0 +1,85 @@
+# Closeout — <YYYY-MM-DD> — <phase-or-module>
+
+<!--
+  Per-session closeout file. Place at: closeouts/<YYYY-MM-DD>-<phase-or-module>.md
+  THREAD_LOG.md gets a one-line index entry pointing here.
+
+  This pattern replaces the monolithic THREAD_LOG.md body. Per-session files
+  scale forever, are individually read-budget-cheap, and avoid the heredoc-vs-edit
+  sync risks that bite append-to-large-file workflows.
+
+  Fill every section that applies. Delete sections that don't.
+-->
+
+## Summary
+
+<!-- Two-to-four sentences. What did this session do, and what is the next session's starting point? -->
+
+## Files Touched
+
+<!-- Group by add/modify/delete. List paths relative to repo root. -->
+
+- **Added:**
+- **Modified:**
+- **Deleted:**
+
+## Tests / Gates
+
+<!-- Whatever the project's "all gates green" set is. Honest reporting only. -->
+
+| Gate | Result | Notes |
+|---|---|---|
+| `bun install` | | |
+| `tsc --noEmit` | | |
+| `oxlint` | | |
+| `bun test` | | |
+
+## Decisions Beyond Prompt
+
+<!-- Cross-cutting decisions made this session that diverged from spec, prompt, or obvious-default.
+     These become numbered entries in DECISIONS.md when the orchestrator promotes them.
+     Format each entry: <one-liner> | <rationale, ~one paragraph>. -->
+
+- **D???** | <one-liner> | <rationale>
+
+## Proposed Conventions
+
+<!-- Cross-cutting patterns this session reached for that may generalize.
+     The orchestrator promotes these to CONVENTIONS.md when a third independent session
+     reaches for the same pattern (or when the orchestrator confirms generalization sooner).
+     Format: title + Why + How to apply. -->
+
+### C? <Title>
+
+**Why:**
+
+**How to apply:**
+
+## Open Questions Left Behind
+
+<!-- Items that are still genuinely unknown after this session.
+     Mirror these into workflow/status.yaml under the relevant phase's open_questions. -->
+
+| ID | Kind | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Carry-Forward Routed
+
+<!-- Items deferred to a specific later phase.
+     Mirror these into workflow/status.yaml under the relevant phase's carry_forward. -->
+
+| ID | Target Phase | Description | Deferred Reason |
+|---|---|---|---|
+| | | | |
+
+## Framework Feedback (optional)
+
+<!-- If this session encountered friction with the framework itself, write a short note here.
+     Promote to a separate file under .codecarto/feedback/ (create the directory if needed) if the note
+     is substantial. Closing the loop on the framework is itself a CodeCarto-style activity — see GUIDE.md. -->
+
+## Next Session Pointer
+
+<!-- One paragraph: what should the next session pick up first? Cite specific files, status.yaml entries,
+     or carry_forward IDs. The next session reads this as part of pre-flight. -->

package/.codecarto/templates/conventions-template.md

@@ -0,0 +1,65 @@
+# Conventions
+
+<!--
+  Project-level skeleton. Copy this to `.codecarto/CONVENTIONS.md` (one level up from templates/)
+  the first time the orchestrator promotes a convention. Then add entries as they accumulate.
+
+  This file holds cross-cutting patterns that have been promoted to project-wide invariants.
+  Every new session reads this file and either honors these conventions or documents why it
+  diverges.
+
+  This file is **orchestrator-maintained**. Implementing sessions should not edit it without
+  explicit invitation; they propose additions in their session closeout and the orchestrator
+  promotes them.
+-->
+
+Cross-cutting patterns promoted to project-wide invariants. Every session reads this file at start
+and either honors these conventions or documents why it diverges.
+
+This file is **orchestrator-maintained**. Implementing sessions propose additions in their
+closeout's "Proposed Conventions" section; the orchestrator promotes them here.
+
+## How conventions get added
+
+A new entry lands here when ONE of the following holds:
+
+1. **Three independent sessions** reach for the same pattern (the "lift if it generalizes" rule
+   applied to conventions themselves), OR
+2. **One session** explicitly promotes a pattern in its closeout report and the orchestrator
+   confirms it generalizes, OR
+3. **The spec or framework feedback corpus** identifies a project-wide invariant that future
+   implementing sessions need to know about.
+
+The orchestrator owns this file. Implementing sessions propose; orchestrator promotes.
+
+## Entry shape
+
+Each convention is a numbered section (`## C<NN>. <Title>`) with three required parts:
+
+- **Body** — the rule itself, in prose. May include a code block for shape contracts.
+- **Why:** — the reason the rule exists. Often a past incident or a defect class the rule
+  prevents. Future maintainers judging edge cases need to know *why* to judge whether the rule
+  applies.
+- **How to apply:** — when and where the rule kicks in. Should answer "is this case in scope?"
+
+Optional:
+- **Current implementers:** — files/modules that already follow the rule. Useful as worked examples.
+- **Source:** — the closeout entry where the orchestrator promoted this convention.
+
+---
+
+## C01. <Title>
+
+<!-- Lead with the rule itself. -->
+
+**Why:**
+
+**How to apply:**
+
+**Current implementers:**
+
+**Source:**
+
+---
+
+<!-- Repeat the C<NN> block for each convention. Number sequentially. -->

package/.codecarto/templates/decisions-template.md

@@ -0,0 +1,82 @@
+# Decisions
+
+<!--
+  Project-level skeleton. Copy this to `.codecarto/DECISIONS.md` (one level up from templates/)
+  the first time the orchestrator promotes a decision. Then add entries as they accumulate.
+
+  This file is an append-only numbered log of cross-cutting decisions made during the project
+  that diverge from spec text, prompt direction, or the obvious-default. Each entry is a
+  one-liner with a back-reference to the closeout where the decision was made and the rationale
+  lives.
+
+  This file is **append-only and orchestrator-maintained**. Every implementing session's
+  "Decisions Beyond Prompt" section in the closeout becomes one or more entries here.
+-->
+
+Append-only log of cross-cutting decisions that diverge from spec text, prompt direction, or
+obvious-default. Each entry is a one-liner with a back-reference to the closeout where the
+decision was made and the rationale lives.
+
+This file is **append-only and orchestrator-maintained**. Every implementing session's
+"Decisions Beyond Prompt" section in the closeout becomes one or more entries here. The
+orchestrator updates this file at session close as part of the closeout ritual.
+
+## Format
+
+```
+D<NNN> | <ONE-LINER> | <SOURCE-CLOSEOUT> | <RATIONALE-POINTER>
+```
+
+- `D<NNN>` — sequential within category (see Categories below). Use leading zeros to width 3.
+- `<ONE-LINER>` — the decision in one sentence. Should answer "what did we decide and why is it
+  not obvious?"
+- `<SOURCE-CLOSEOUT>` — closeout filename (e.g., `2026-05-02-architecture`).
+- `<RATIONALE-POINTER>` — short pointer to where the full rationale lives. Usually the closeout's
+  "Decisions Beyond Prompt" section.
+
+## Categories
+
+Numbering is sequential within each category, not within the file. Future sessions add at the
+end of the appropriate category.
+
+- **D000–D099** — Type system, discriminators, cross-cutting type discipline
+- **D100–D199** — Toolchain, lint, project-level config
+- **D200–D299** — Module-internal patterns
+- **D300–D399** — Cross-module primitives lifted into a shared module
+- **D400–D499** — Native code, OS-platform-specific, sandboxing
+- **D500–D599** — Pending spec deltas (proposed but not yet applied)
+- **D600–D699** — Reserved for future categories — extend the table here when you open a new range
+
+Categories are project-specific. Edit this list when the project's shape demands a new range.
+
+---
+
+## D000–D099: Type system and discriminator
+
+<!-- Append entries here as they accumulate. Example:
+
+D001 | Outcome<T,E> is a brand newtype keyed by a unique Symbol, NOT a value-union; only OutcomeSink can construct one. | 2026-05-02-protocol | Spike List #11 requires unconstructable-outside-the-sink.
+
+-->
+
+## D100–D199: Toolchain and lint
+
+## D200–D299: Module-internal patterns
+
+## D300–D399: Cross-module primitives lifted
+
+## D400–D499: Native / platform-specific
+
+## D500–D599: Pending spec deltas
+
+---
+
+## How decisions get added
+
+Every implementing session's "Decisions Beyond Prompt" section in the closeout becomes one or
+more `D<NNN>` entries here. The orchestrator promotes them at session close as part of the
+closeout ritual. Implementing sessions never edit this file directly.
+
+If a decision is later overturned, do **not** delete the entry. Append a new `D<NNN>` superseding
+it (with `Supersedes D<old-NNN>` in the one-liner) and update the old entry's one-liner to begin
+`SUPERSEDED by D<new-NNN>:`. The history is the value.

package/.codecarto/templates/defect-fix-tracker.md

@@ -0,0 +1,77 @@
+# Defect Fix Tracker — [project_name]
+
+**Campaign:** Post-CodeCartographer defect remediation
+**Started:** [date]
+**Source:** `findings/defect-scan/defect-report.md` ([total] defects)
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total defects | |
+| Fixed | |
+| Deferred | |
+| Accepted (by design) | |
+| Remaining | |
+
+**Test suite:** [X tests passing (Y files)] or [no test suite]
+
+---
+
+## Fix Status
+
+### Critical — [X found, Y fixed]
+
+<!-- One row per defect from the defect report. ID format: D{pass}.{number} (e.g., D1.1 = Pass 1, Finding 1). -->
+<!-- Status: FIXED / DEFERRED / ACCEPTED / REMAINING -->
+<!-- Fix Summary: one line describing what changed. Leave blank for deferred/remaining. -->
+
+| ID | Location | Description | Status | Fix Summary |
+|----|----------|-------------|--------|-------------|
+| | | | | |
+
+### High — [X found, Y fixed]
+
+| ID | Location | Description | Status | Fix Summary |
+|----|----------|-------------|--------|-------------|
+| | | | | |
+
+### Medium — [X found, Y fixed]
+
+| ID | Location | Description | Status | Fix Summary |
+|----|----------|-------------|--------|-------------|
+| | | | | |
+
+### Low — [X found, Y fixed]
+
+| ID | Location | Description | Status | Fix Summary |
+|----|----------|-------------|--------|-------------|
+| | | | | |
+
+---
+
+## Deferred Items
+
+<!-- For each deferred defect, explain why and what would be needed to fix it. -->
+
+- **D_._ ([short description]):** [Reason for deferral. What work would be needed — e.g., requires library integration, needs design spike, blocked by upstream.]
+
+---
+
+## Files Modified
+
+<!-- One row per file that was touched during remediation. List which defect IDs were addressed in each. -->
+
+| File | Defects Fixed |
+|------|---------------|
+| | |
+
+---
+
+## Notes
+
+<!-- Any important context about the fix campaign: backward compatibility, breaking changes, migration steps, test coverage changes, etc. -->
+
+-

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

@@ -0,0 +1,116 @@
+# Defect Report — [project_name]
+
+## Scan Context
+
+- **Source:** `../` (repository root)
+- **Architecture reference:** `findings/architecture/architecture-map.md`
+- **Contracts reference:** [available / not available]
+- **Protocols reference:** [available / not available]
+- **Pipeline:** [pipeline variant name]
+- **Date:** [date]
+
+---
+
+## 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 3: Concurrency and Resource Management
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 4: Security and Trust Boundaries
+
+| # | Location | Defect | Severity | Evidence Level | Action |
+|---|----------|--------|----------|----------------|--------|
+| 1 | | | | | |
+
+---
+
+## Pass 5: API Contract Violations
+
+| # | 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 Category
+
+| Pass | Critical | High | Medium | Low | Total |
+|------|----------|------|--------|-----|-------|
+| 1. Logic and correctness | | | | | |
+| 2. Error handling | | | | | |
+| 3. Concurrency and resources | | | | | |
+| 4. Security and trust | | | | | |
+| 5. API contract violations | | | | | |
+| 6. Config and environment | | | | | |
+
+### Top Findings
+
+<!-- List the most impactful findings across all passes, ranked by severity and confidence. -->
+<!-- Include: pass number, location, one-line defect description, severity, recommended action. -->
+
+1.
+2.
+3.
+4.
+5.
+
+---
+
+## 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 | At least three analysis passes 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/deltas-applied.md

@@ -0,0 +1,71 @@
+# Deltas Applied — <YYYY-MM-DD>
+
+<!--
+  Output of a spec-delta-application session. See skills/spec-delta-application/SKILL.md.
+
+  One row per delta from every source. APPLY, CLARIFY, DEFER, REJECT all recorded.
+  Future revision passes read this file to know which deltas have already been processed.
+
+  Place at: findings/reimplementation-spec/DELTAS-APPLIED.md
+  (Sibling of the spec; the spec itself stays at reimplementation-spec.md.)
+
+  If multiple delta-application passes happen over the project's life, append a new dated
+  section below the existing one rather than overwriting. Same append-mode discipline as
+  secondary outputs.
+-->
+
+## Sources
+
+<!-- List every source file containing deltas processed in this session. -->
+
+| Source | Delta count | Notes |
+|---|---|---|
+| spike-1-<slug>.md | | |
+| spike-2-<slug>.md | | |
+| <other-source>.md | | |
+
+## Triage Summary
+
+| Bucket | Count | Notes |
+|---|---|---|
+| APPLY | | |
+| CLARIFY | | |
+| DEFER | | |
+| REJECT | | |
+| **Total** | | |
+
+## Audit Table
+
+<!-- One row per delta. Order: by source, then by delta ID within source. -->
+
+| # | Source | Δ ID | Bucket | Spec Section Touched | Disposition / Rationale |
+|---|---|---|---|---|---|
+| 1 | spike-1-<slug>.md | Δ1 | APPLY | §X.Y | Applied — spec said X, real behavior is Y. |
+| 2 | spike-1-<slug>.md | Δ2 | REJECT | n/a | Premise wrong on close reading — three of eleven sites have no IPC. |
+| 3 | spike-2-<slug>.md | Δ3 | CLARIFY | §A.B | Reworded "may" → "must" to match the actual normative rule. |
+| 4 | spike-2-<slug>.md | Δ4 | DEFER | n/a | Real improvement but not load-bearing for next module; in BACKLOG.md. |
+
+## Citation Markers Added
+
+<!-- For audit: list every spec section that received a `[revised per <source> §<delta-id>]` marker
+     in this pass. Future readers can grep for these. -->
+
+- §X.Y — `[revised per spike-1-<slug>.md §Δ1]`
+- §A.B — `[revised per spike-2-<slug>.md §Δ3]`
+
+## Re-Validation Result
+
+<!-- Summary of the re-validation check. The spec's validation block must still be PASS or
+     PASS WITH GAPS after delta application. If it degrades, deltas weren't applied carefully —
+     fix the spec body, NOT the validation criteria. -->
+
+- Pre-edit spec validation: PASS / PASS WITH GAPS
+- Post-edit spec validation: PASS / PASS WITH GAPS
+- Criteria changed: yes / no  (must be `no` — if `yes`, document why)
+
+## Decisions Beyond Triage
+
+<!-- Decisions made during this session that weren't directly in the delta list — e.g., "rejected
+     Δ7 because §X already covers the case." These also become numbered entries in DECISIONS.md. -->
+
+- **D???** | <one-liner> | <rationale>