codecartographer-pi 0.1.0

package/.codecarto/GUIDE.md

@@ -0,0 +1,298 @@
+# CodeCartographer — LLM Session Guide
+
+## What This Is
+
+This is a structured reverse-engineering workspace embedded inside a repository. You are an LLM assistant. Your job is to analyze the source code in this repository (the parent directory, `../`) and produce a reusable evaluation bundle: an architecture map, behavioral contracts, protocol and state notes, a porting synthesis, and a reimplementation spec.
+
+All CodeCartographer files live inside this `.codecarto/` folder. The source code is everything outside it.
+
+Work in explicit phases. Do not try to do everything at once.
+
+## Roles
+
+CodeCartographer distinguishes two roles. They are different jobs, often held by different threads, and the framework's discipline depends on both existing.
+
+**Implementing session.** One phase or one module of work, fresh thread, follows a SKILL.md and a template, validates, writes a closeout, ends. The bulk of the framework — phases, skills, templates, validation gates — is written for this role. The "You are an LLM assistant" framing in "What This Is" addresses this role.
+
+**Orchestrator.** One persistent thread (typically the first LLM the user points at the project) paired with the human user. The orchestrator holds cross-session context, drafts implementing-session prompts from prior closeouts, curates `CONVENTIONS.md` and `DECISIONS.md` (promoting patterns when they recur), and gates strategic forks the user makes. **The orchestrator does not execute pipeline phases itself** — that is the implementing-session role. The orchestrator's deliverables are *prompts and curated artifacts*, not phase outputs. When the orchestrator finds itself reading a SKILL.md or producing a `findings/<phase>/<primary-output>.md`, it has slipped into the implementing-session role and should stop, draft a prompt, and hand off instead. Without an orchestrator, the framework still works phase-by-phase but cross-cutting conventions and decisions don't accumulate, and each implementing session re-discovers what prior sessions established.
+
+If you are an LLM reading this guide for the first time on a project where `CONVENTIONS.md` and `DECISIONS.md` are unwritten (still showing template content) and `closeouts/` is empty, **see "First-Time Project Setup" below before starting any phase.**
+
+## First-Time Project Setup
+
+If this is the first LLM to touch this project — no closeouts in `closeouts/`, `CONVENTIONS.md` and `DECISIONS.md` still showing template skeletons, `workflow/status.yaml` at defaults — stop before starting any pipeline phase and have a one-time role conversation with the user. Combine the explanation and the ask in one structured prompt:
+
+> "I see this is a fresh CodeCartographer-equipped project. Before I start the analysis, one one-time decision: would you like me to take on the **orchestrator role** for this project, or work session-by-session?
+>
+> The orchestrator role means I'd hold cross-session context across the entire project — drafting prompts for implementation threads you'll spin up, curating two project-wide files (`CONVENTIONS.md` for patterns and `DECISIONS.md` for cross-cutting calls), and gating the strategic forks where you'd want to make a call.
+>
+> How it works in practice: this thread becomes the orchestrator; you spin up fresh threads for each implementation session using the prompts I draft, run them, and paste the closeout report back here. I update `CONVENTIONS.md`/`DECISIONS.md` and prepare the next prompt. The framework's discipline compounds across sessions instead of being reinvented each time.
+>
+> One operational tip: if your coding agent supports renaming and pinning threads, rename this thread to "Orchestrator" and pin it. Keeps it organized and quick to find when you switch back from implementation threads.
+>
+> The alternative is session-by-session work with no cross-session context — the framework still works phase-by-phase, but `CONVENTIONS.md` stays empty and each session has to re-derive patterns from prior closeouts. Better for one-off audits; worse for long-running multi-module projects.
+>
+> Which would you like?"
+
+If the user accepts the orchestrator role:
+
+1. Initialize `CONVENTIONS.md` from `templates/conventions-template.md` and `DECISIONS.md` from `templates/decisions-template.md` (skeletons only — populate as patterns and decisions accumulate).
+2. Set `project_name` in `workflow/status.yaml`.
+3. **Do not run the architecture phase yourself.** The orchestrator never executes pipeline phases — that is the implementing-session role (see §Roles). Instead, **draft an implementing-session prompt for the architecture phase** that a fresh thread will execute. Hand the prompt to the user; they spin up a new thread with it; the implementing thread runs the phase, validates, writes a closeout, and reports back; you (the orchestrator) read the returned closeout, update `CONVENTIONS.md` / `DECISIONS.md` / `workflow/status.yaml` per the closeout ritual, and draft the next phase's prompt. **Phase work always happens in fresh implementing-session threads, never in the orchestration thread.** A useful self-check: if you find yourself reading a `findings/<phase>/SKILL.md` or writing a `findings/<phase>/<primary-output>.md`, you have slipped into the implementing-session role — stop, draft the prompt, hand off.
+
+If the user declines:
+
+1. Note in `THREAD_LOG.md` that the project runs in degraded no-orchestrator mode.
+2. Proceed phase-by-phase as a standalone implementing session.
+3. `CONVENTIONS.md` and `DECISIONS.md` stay as templates; closeouts accumulate but cross-cutting promotion doesn't happen.
+
+If the user is ambivalent, default to recommending the orchestrator path for any project expected to span more than one phase or module — the framework's compounding-discipline benefits are real and the cost is just paste-and-react work for the user.
+
+## First Read For New Sessions
+
+Read these files in order before doing any analysis:
+
+1. This `GUIDE.md` (you are here — `.codecarto/GUIDE.md`).
+2. `workflow/status.yaml` to see which phases are done and what is next.
+3. The current phase's existing output file, if one exists (to avoid repeating work).
+4. The current phase's `SKILL.md` for detailed instructions on what to analyze and produce.
+5. The output template from `templates/` for the current phase (if starting a new output).
+
+All paths in this guide are relative to `.codecarto/` unless stated otherwise.
+
+If `project_name` in `workflow/status.yaml` is blank, set it to the name of this repository before starting analysis.
+
+Treat this workspace as durable memory across sessions. Do not invent a new structure. Use the one that exists.
+
+## Trust Boundaries
+
+Some files in this workspace are **read-only instructions** and must not be modified during analysis. Others are **writable outputs** that you create or update.
+
+| Category | Files | Access |
+|---|---|---|
+| Orchestration (read-only) | `GUIDE.md`, `CONTRIBUTING.md`, `LICENSE` | Read only. Never modify. |
+| Skills (read-only) | `findings/*/SKILL.md`, `findings/defect-scan/passes/*.md`, `skills/*/SKILL.md` | Read only. Never modify. |
+| Templates (read-only) | `templates/*.md` | Read only. Never modify. |
+| Pipeline definitions (read-only) | `workflow/pipeline*.yaml`, `workflow/VALIDATE.md` | Read only. Never modify. |
+| Source code (read-only) | `../` (everything outside `.codecarto/`) | Read only. Analyze but never modify. |
+| Workflow state (read-write) | `workflow/status.yaml` | Update to track progress. |
+| Findings (read-write) | `findings/<phase>/<primary-output>.md`, secondary output files | Create and update during phases. |
+| Closeouts (read-write, append-only) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Each session writes a new closeout file; `THREAD_LOG.md` is an INDEX pointing to closeouts. |
+| Conventions (orchestrator-maintained) | `CONVENTIONS.md` | Cross-cutting patterns promoted to project-wide invariants. Implementing sessions propose; the orchestrator writes. |
+| Decisions (orchestrator-maintained, append-only) | `DECISIONS.md` | Numbered log of decisions that diverge from spec, prompt, or obvious-default. Appended at session close. |
+| Backlog (read-write) | `BACKLOG.md` | Deferred items with rationale. |
+| Scratch (read-write) | `scratch/*` | Disposable working notes. |
+
+If you are uncertain whether a file should be modified, treat it as read-only.
+
+## Pipeline Selection
+
+Six pipeline variants are available. Check the `pipeline` field in `workflow/status.yaml` to see which is active.
+
+- If the field is **empty**, ask the user which scope to use.
+- If the field points to a **file that does not exist**, stop and ask the user to correct it. Do not guess or fall back to the default pipeline.
+
+| Variant | File | Phases | When to use |
+|---|---|---|---|
+| Full with deep audit (default) | `workflow/pipeline-full-with-deep-audit.yaml` | architecture → defect-scan-mechanical → contracts → protocols → defect-scan-semantic → porting → reimplementation-spec | Complete analysis with defect scan split into an early mechanical pass and a deep semantic pass; reimplementation designs around defects with full context |
+| Full with audit | `workflow/pipeline-full-with-audit.yaml` | architecture → defect-scan → contracts → protocols → porting → reimplementation-spec | Single early defect scan; cheaper than the deep variant when you do not need contracts/protocols-grounded defect findings |
+| Full | `workflow/pipeline.yaml` | architecture → contracts → protocols → porting → reimplementation-spec | Porting bundle without defect scan |
+| Defect scan | `workflow/pipeline-defect-scan.yaml` | architecture → defect-scan | Maintenance audit to surface latent problems |
+| Lite | `workflow/pipeline-lite.yaml` | architecture → contracts → protocols | Understanding behavior without porting plans |
+| Architecture only | `workflow/pipeline-architecture-only.yaml` | architecture | Quick structural overview |
+
+## Evaluation Objective
+
+Produce a reusable evaluation bundle for the repository. The bundle has two purposes:
+
+- **Immediate use**: future sessions can continue the analysis without repeating earlier work.
+- **Future automation**: the same workflow can be pointed at another codebase later.
+
+### Primary Deliverables
+
+| Artifact | Location |
+|---|---|
+| Architecture map | `findings/architecture/architecture-map.md` |
+| Defect report | `findings/defect-scan/defect-report.md` |
+| Behavioral contracts | `findings/contracts/behavioral-contracts.md` |
+| Protocols and state | `findings/protocols/protocols-and-state.md` |
+| Reverse-engineering bundle | `findings/porting/reverse-engineering-bundle.md` |
+| Reimplementation spec | `findings/reimplementation-spec/reimplementation-spec.md` |
+
+Not all deliverables apply to every pipeline variant. Check your active pipeline YAML for which phases and outputs are included.
+
+### Secondary Artifacts
+
+Created only when a phase grows too large or a topic needs standalone treatment. Secondary outputs use `mode: append` — always append to these files, never overwrite content from a previous phase.
+
+| Artifact | Location |
+|---|---|
+| Public surfaces notes | `findings/public-surfaces/public-surfaces.md` |
+| Runtime lifecycle notes | `findings/runtime-lifecycle/runtime-lifecycle.md` |
+| State and storage notes | `findings/state-and-storage/state-and-storage.md` |
+| Build and deploy notes | `findings/build-and-deploy/build-and-deploy.md` |
+| Configuration model | `findings/config-model/config-model.md` |
+
+### Primary vs Secondary Output Relationship
+
+The two output kinds have different jobs and must not duplicate each other.
+
+- **Primary outputs own the map and the load-bearing claims.** They are the canonical reference a downstream phase cites by section anchor. Sections may *summarize* secondary content (one-paragraph synopsis with a pointer) but should not catalog every detail.
+- **Secondary outputs own the catalog-level detail.** They accumulate across phases via `mode: append`, with each phase adding a dated section. A reader who wants the full inventory of public surfaces, the full SQLite migration history, or the full env-var matrix goes here, not to the primary output.
+
+If a primary and a secondary output describe the same topic (e.g., the architecture map's `Public Surfaces` section vs. `findings/public-surfaces/public-surfaces.md`), the primary owns the *summary and the claims that downstream phases will cite*; the secondary owns the *enumerated detail*. Conflicting content is a bug — recency wins, and the primary should be updated to point to the latest secondary section.
+
+### Orchestrator-Maintained Artifacts
+
+Two cross-cutting files compound across sessions and live at the `.codecarto/` top level:
+
+- **`CONVENTIONS.md`** — cross-cutting patterns that have been promoted to project-wide invariants (e.g., a shared discriminated-union return shape, a tripwire-naming vocabulary, a verbatim-spec-quote discipline). Implementing sessions propose additions in their closeout; the orchestrator promotes them. New conventions land when a third independent session reaches for the same pattern, or when a spec/feedback corpus identifies a project-wide invariant.
+- **`DECISIONS.md`** — append-only numbered log of cross-cutting decisions that diverge from spec, prompt, or obvious-default. Each entry: `D<NNN> | <one-liner> | <source-session> | <rationale-pointer>`. Categories partition the namespace (type system, toolchain, module-internal patterns, lifted primitives, etc.).
+
+Both files are skeletons in the framework templates (`templates/conventions-template.md`, `templates/decisions-template.md`) and become project-specific artifacts when a session writes to them. They are *orchestrator-maintained*, not implementer-edited — implementing sessions propose, the orchestrator promotes.
+
+## Context Budget
+
+Before beginning a phase, estimate how much source material you need to read. For large codebases:
+
+- Read structural files first (manifests, entrypoints, READMEs) from the repository root (`../`).
+- Use the architecture map to prioritize which packages to read in detail.
+- Defer deep reads until the current phase actually needs them.
+- If you are running low on context, finish the current section, write a PARTIAL validation, and document what remains in `open_questions` (truly unknown) or `carry_forward` (deferred to a specific later phase) in status.yaml. See "Open Questions vs Carry-Forward" below.
+
+### Subagent Delegation for Large Codebases
+
+For codebases over roughly 50 source files or 100K LOC, do not burn primary context on bulk extraction work. Delegate dependency mapping, file inventories, manifest enumeration, and cross-document comparisons to subagents and cite their scratch artifacts (`scratch/<topic>.md`) from the primary output. The primary session reads the synthesized scratch note, not the raw walks. Bless this pattern explicitly so primary context stays for the load-bearing reasoning that the subagent can't do — naming layers, pinning invariants, classifying findings.
+
+### Open Questions vs Carry-Forward
+
+`open_questions` does two distinct jobs that the schema separates explicitly:
+
+- **`open_questions`** — items that are *still genuinely unknown*. Need more evidence (a runtime test, a maintainer decision, a spec ruling). Not resolvable by any later phase in the current pipeline.
+- **`carry_forward`** — items that are deferred to a specific later phase because the current phase can't responsibly close them but the pipeline naturally will. Each entry has a target phase.
+
+Both lists carry structured entries. Recommended shape:
+
+```yaml
+open_questions:
+  - id: arch-OQ1
+    kind: needs-runtime-test
+    description: Does the SSE stream emit a final `done: true` event, or does the connection just close?
+    deferred_reason: cannot determine from source alone; requires live capture against the running service.
+carry_forward:
+  - id: arch-CF1
+    kind: defer-to-phase
+    target_phase: defect-scan
+    description: The `loadConfig()` callsite returns `{}` on both ENOENT and parse-error — can't tell absent from corrupt.
+    deferred_reason: framing this as a defect requires the defect-scan rubric; flagged here so defect-scan picks it up.
+```
+
+`kind` is one of: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`. The downstream phase scans `carry_forward` entries whose `target_phase` matches its own ID and either resolves them (deleting the entry) or re-defers (updating `target_phase`).
+
+## Phase Selection Logic
+
+1. Load the active pipeline YAML (see `pipeline` field in `workflow/status.yaml`).
+2. Load `workflow/status.yaml`.
+3. Traverse `phase_order` in order.
+4. Pick the first phase whose status is not `complete` and whose `depends_on` phases are all `complete`.
+5. Load that phase's `skill_path` and all files listed in `required_reads`.
+6. Run the phase. Write output to `primary_output`.
+7. Run validation per `workflow/VALIDATE.md`. Append the validation block to the output.
+8. Enforce completion rules: the primary output file must exist with a PASS or PASS WITH GAPS validation block, status.yaml must reflect completion, and THREAD_LOG.md must have a handoff entry.
+
+**Parallel phase warning:** Some phases share the same `depends_on` and can run concurrently (e.g., `contracts` and `protocols` both depend only on `architecture`). If two sessions update `status.yaml` at the same time, the second write will overwrite the first. When running parallel phases, update `status.yaml` carefully — read the file immediately before writing, and preserve the status of any phase completed by a sibling session.
+
+## Session Update Protocol
+
+When a session starts:
+
+1. Read this GUIDE.md.
+2. Read `workflow/status.yaml`.
+3. Read `CONVENTIONS.md` (if it exists) — the project's accumulated cross-cutting patterns.
+4. Read the current phase's existing output, if present.
+5. Read the current phase's `SKILL.md`.
+6. Read the output template from `templates/` for the current phase (if starting a new output).
+7. Scan `carry_forward` entries in status.yaml whose `target_phase` matches your phase — these are the items earlier phases routed to you.
+
+When a session finishes durable work:
+
+1. Run the validation step described in `workflow/VALIDATE.md`. Append a validation block to the output.
+2. Update `workflow/status.yaml` (the single source of truth for progress): mark the phase status as `complete`, advance `current_phase` to the next pending phase, and update both `open_questions` and `carry_forward`. When all phases in the pipeline are complete, set `current_phase` to `complete`.
+3. Record 2-3 key observations in `owner_notes` for the completed phase (e.g., row counts, notable decisions, scope of analysis).
+4. Write a per-session closeout file at `closeouts/<YYYY-MM-DD>-<phase-or-module>.md` using `templates/closeout-template.md`. Append a one-line index entry to `THREAD_LOG.md` pointing at it.
+5. Store the durable output in the declared `findings/` path.
+6. If the session made cross-cutting decisions or discovered project-wide invariants, propose additions to `CONVENTIONS.md` (in the closeout's "Proposed Conventions" section) and `DECISIONS.md` (numbered entries in the closeout's "Decisions Beyond Prompt" section). The orchestrator promotes these to the canonical files.
+
+### Strategic Alignment Hook (before synthesis)
+
+Before starting `reimplementation-spec` (or any synthesis phase), confirm with the user — explicitly, in chat — whether the spec is:
+
+- **Language-agnostic** (the default; "any port to any stack"), or
+- **Opinionated** (target stack, project identity, scope cuts, named primitives are pre-locked).
+
+This conversation produces inputs the synthesis phase actually needs (locked target stack, locked project name, locked scope cuts) and selects the right template. If the answer is "opinionated," use `templates/reimplementation-spec-opinionated.md` instead of the default. Skipping the hook produces a generic spec when the user wanted a specific one — the most informative friction the framework has produced to date. A two-question pre-flight is cheap.
+
+## Guardrails
+
+These rules cannot be enforced by the template — they rely on the LLM following instructions. A future code-backed implementation should enforce them programmatically.
+
+1. **Validation gate:** Never set a phase's status to `complete` in `status.yaml` if the validation block contains any FAIL result. Fix the output first, re-run validation, and only then mark complete. If the validation is PASS WITH GAPS, document the gaps in `open_questions` before marking complete.
+2. **Status recovery:** If `workflow/status.yaml` becomes malformed (bad YAML syntax, missing fields), do not guess at the intended state. Stop and ask the user to review the file. Compare against the phase outputs in `findings/` to reconstruct which phases are actually complete.
+3. **Output path verification:** After writing a phase's primary output, verify the file path matches the `primary_output` field in the active pipeline YAML. Do not write findings to a path that belongs to a different phase.
+
+## Output Placement Rules
+
+- Durable findings go under `findings/<phase>/`.
+- Rough working notes go under `scratch/`.
+- The primary outputs are listed in the deliverables table above.
+- Secondary outputs are created only when needed, using `mode: append`.
+- Per-session closeouts go under `closeouts/<YYYY-MM-DD>-<phase-or-module>.md`. `THREAD_LOG.md` is an INDEX of one-line pointers to those closeouts, not the primary store.
+- Cross-cutting patterns go in `CONVENTIONS.md`; numbered cross-cutting decisions go in `DECISIONS.md`. Both are orchestrator-maintained — implementing sessions propose in their closeout, the orchestrator promotes.
+- Do not store durable findings only in `THREAD_LOG.md`. The log is an index, not the primary artifact store.
+
+## Folder Layout
+
+```
+your-repo/
+  src/                         # Your source code (whatever structure it has).
+  ...
+  .codecarto/                  # This folder. All CodeCartographer files live here.
+    GUIDE.md                   # This file. LLM entry point.
+    findings/
+      architecture/            # System structure, layers, dependency direction.
+      defect-scan/             # Multi-pass defect report (used by the legacy single-scan pipelines).
+        passes/                # Per-category analysis instructions (6 pass files; reused by the split phases below).
+      defect-scan-mechanical/  # Early defect pass (passes 1, 2, 6); used by full-with-deep-audit.
+      defect-scan-semantic/    # Deep defect pass (passes 3, 4, 5); used by full-with-deep-audit.
+      contracts/               # User-visible behavior, defaults, acceptance checks.
+      protocols/               # Event streams, state machines, persistence formats.
+      porting/                 # Reverse-engineering synthesis bundle.
+      reimplementation-spec/   # Final language-agnostic build spec.
+      public-surfaces/         # (Optional) Extracted public interface notes.
+      runtime-lifecycle/       # (Optional) Extracted runtime sequence notes.
+      state-and-storage/       # (Optional) Extracted durable state notes.
+      build-and-deploy/        # (Optional) Build pipeline and packaging notes.
+      config-model/            # (Optional) Configuration inheritance and env behavior.
+    scratch/                   # Disposable analysis notes.
+    templates/                 # Output templates and log entry templates.
+    skills/
+      spec-delta-application/  # Post-pipeline skill: apply triaged spec deltas with citation discipline.
+        SKILL.md
+    workflow/
+      pipeline-full-with-deep-audit.yaml  # 7-phase pipeline with split defect scan (default).
+      pipeline-full-with-audit.yaml       # 6-phase pipeline with single early defect scan.
+      pipeline.yaml                       # 5-phase (no defect scan).
+      pipeline-defect-scan.yaml           # 2-phase (architecture + defect scan).
+      pipeline-lite.yaml                  # 3-phase (no porting or reimpl).
+      pipeline-architecture-only.yaml     # 1-phase (architecture only).
+      status.yaml              # Per-project progress. Single source of truth.
+      VALIDATE.md              # Validation protocol. Run after every phase.
+    closeouts/                 # Per-session closeout files (replaces monolithic THREAD_LOG body).
+      <YYYY-MM-DD>-<phase-or-module>.md
+    CONVENTIONS.md             # (Optional, project-grown) Cross-cutting invariants. Orchestrator-maintained.
+    DECISIONS.md               # (Optional, project-grown) Numbered decisions log. Orchestrator-maintained.
+    BACKLOG.md                 # (Optional) Deferred items with rationale.
+    THREAD_LOG.md              # Cross-session INDEX of closeout files.
+    CONTRIBUTING.md            # Contribution guidelines.
+    LICENSE                    # MIT License.
+```

package/.codecarto/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Sesler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.codecarto/NEW_THREAD_BLURB.md

@@ -0,0 +1,47 @@
+# CodeCartographer - New Session Quick Start
+
+Source code under evaluation: `../` (this repository — everything outside `.codecarto/`)
+
+All CodeCartographer files are inside `.codecarto/`. Paths below are relative to `.codecarto/`.
+
+**First-time project?** If `CONVENTIONS.md` and `DECISIONS.md` are still template skeletons and `closeouts/` is empty, see GUIDE.md §Roles and §First-Time Project Setup before reading the rest. The first LLM on a project takes a one-time role decision with the user (orchestrator vs session-by-session).
+
+Read these in order before doing work:
+
+1. `GUIDE.md` - the LLM entry point and session guide
+2. `workflow/status.yaml` - the single source of truth for project progress
+3. `CONVENTIONS.md` if present - cross-cutting patterns this project follows
+4. The current phase's existing output file, if present
+5. The current phase's `SKILL.md`
+6. The output template from `templates/` for the current phase (if starting a new output)
+7. Scan `carry_forward` entries in `workflow/status.yaml` whose `target_phase` matches your phase — these are items earlier phases routed to you to close.
+
+Where to store results:
+
+- Durable findings: `findings/<phase>/`
+- Rough notes: `scratch/`
+- Workflow status: `workflow/status.yaml` (only status file to update)
+- Per-session closeouts: `closeouts/<YYYY-MM-DD>-<phase-or-module>.md` (use `templates/closeout-template.md`)
+- Cross-session log: append a one-line index entry to `THREAD_LOG.md` pointing at your closeout file
+
+After completing work:
+
+1. Run validation per `workflow/VALIDATE.md`. Append the validation block to the output.
+2. Update `workflow/status.yaml`: mark the phase `complete`, advance `current_phase` to the next pending phase (or `complete` if all phases are done), and update both `open_questions` (genuinely unknown) and `carry_forward` (deferred to a specific later phase) for the phase. See GUIDE.md "Open Questions vs Carry-Forward" for the entry shape.
+3. Record 2-3 key observations in `owner_notes` for the completed phase.
+4. Write a per-session closeout file at `closeouts/<YYYY-MM-DD>-<phase-or-module>.md`. Append a one-line entry to `THREAD_LOG.md` pointing at it (de-dup discipline: scan the bottom 5 entries first to avoid double-appending).
+5. Store the durable output in the declared `findings/` path.
+6. If the session made cross-cutting decisions or proposed conventions, fill in the closeout's "Decisions Beyond Prompt" and "Proposed Conventions" sections. The orchestrator promotes them to `DECISIONS.md` and `CONVENTIONS.md` respectively.
+
+## File-System Sync Warning
+
+Some host setups exhibit lag between host file-tools (Read/Write/Edit) and a Linux bash mount of the same files. Symptoms include parse errors at line numbers that don't appear in the host view, files that look truncated mid-line, and duplicated trailing content after a heredoc-vs-Edit collision.
+
+To stay safe:
+
+- Prefer **full-file overwrites** (Write) over in-place patches (Edit) when host/mount disagreement appears.
+- Verify writes by running `wc -l` and `md5sum` from both sides if you suspect drift.
+- **Never chain Edit and bash heredocs against the same file in a single session** — pick one writer and stick with it.
+- Keep test code in a separate file from production code so a sync gap on one doesn't poison the other.
+
+This is not a CodeCartographer issue per se, but the framework's reliance on append-to-narrative-files (`THREAD_LOG.md`, `status.yaml`, large primary outputs) magnifies the cost — every truncated write is a potential silent data loss in a load-bearing place.

package/.codecarto/README.md

@@ -0,0 +1,39 @@
+# CodeCartographer
+
+Copy the `.codecarto/` folder into any repository you want to analyze.
+
+## Setup
+
+```bash
+# From inside your target repo:
+cp -r /path/to/CodeCartographer/.codecarto .
+```
+
+That's it. No symlinks, no copying your code anywhere.
+
+## Usage
+
+Point any LLM with file access at the guide:
+
+```
+Read .codecarto/GUIDE.md and begin the analysis.
+```
+
+The LLM reads your source code directly from the repo root (`../` relative to `.codecarto/`) and writes findings into `.codecarto/findings/`.
+
+## Git
+
+The `.codecarto/.gitignore` already excludes generated findings and scratch files. If you want to commit the CodeCartographer template files (so other team members can run the analysis too), just commit the `.codecarto/` folder as-is.
+
+## Choosing a Pipeline
+
+The default is the 7-phase **full-with-deep-audit** pipeline, which splits the defect scan into an early mechanical pass (after architecture) and a deep semantic pass (after protocols) so the reimplementation can design around defects with full contracts and protocols context. To use a different one, edit `.codecarto/workflow/status.yaml`:
+
+```yaml
+pipeline: workflow/pipeline-full-with-deep-audit.yaml  # 7-phase with split defect scan (default; depth-first)
+pipeline: workflow/pipeline-full-with-audit.yaml       # 6-phase with single early defect scan — adjust phases to use one defect-scan
+pipeline: workflow/pipeline.yaml                       # 5-phase without defect scan — remove defect-scan phases
+pipeline: workflow/pipeline-defect-scan.yaml           # 2-phase defect audit — remove contracts through reimplementation-spec
+pipeline: workflow/pipeline-lite.yaml                  # 3-phase understanding — remove defect-scan phases, porting, and reimplementation-spec
+pipeline: workflow/pipeline-architecture-only.yaml     # 1-phase quick overview — keep only architecture
+```

package/.codecarto/THREAD_LOG.md

@@ -0,0 +1,39 @@
+# Thread Log — Index
+
+This file is an **index** of per-session closeouts. Each session writes a full closeout to
+`closeouts/<YYYY-MM-DD>-<phase-or-module>.md` using `templates/closeout-template.md`, and
+appends one line here pointing to it.
+
+The body of each session lives in the closeout file, not in this index. This pattern scales
+forever: per-session files are individually small and read-budget-cheap, and avoid the
+heredoc-vs-edit sync risks that bite append-to-large-file workflows once the file grows past
+~50 KB.
+
+## Format
+
+```
+- YYYY-MM-DD — <phase-or-module> — <one-line-summary> — [closeout](closeouts/YYYY-MM-DD-phase-or-module.md)
+```
+
+## De-dup discipline
+
+Before appending, scan the bottom 5 entries. If you see a line with the same date AND same
+phase-or-module AND same summary, do not append — the prior session already wrote it. The
+framework has no programmatic dedup gate; this is human-discipline. (See
+`Apply 20 spec deltas to Thaumaturge.txt` for the incident that established this rule.)
+
+A one-liner to surface duplicates from the shell:
+
+```bash
+grep -E '^- [0-9]{4}-[0-9]{2}-[0-9]{2}' .codecarto/THREAD_LOG.md | sort | uniq -d
+```
+
+## Entries
+
+<!--
+  Append one line per session below this marker.
+  Example:
+  - 2026-05-02 — framework-feedback-pass — applied 6 spec-blockers + 5 clarifications from FEEDBACK_INDEX.md — [closeout](closeouts/2026-05-02-framework-feedback-pass.md)
+-->
+
+- 2026-05-02 — framework-feedback-pass — applied 6 spec-blockers + 5 clarifications from FEEDBACK_INDEX.md; 14 deferred to BACKLOG.md — [closeout](closeouts/2026-05-02-framework-feedback-pass.md)

package/.codecarto/closeouts/2026-05-02-framework-feedback-pass.md

@@ -0,0 +1,111 @@
+# Closeout — 2026-05-02 — framework-feedback-pass
+
+## Summary
+
+This was a meta-session: instead of using CodeCartographer to analyze a codebase, the session edited CodeCartographer based on accumulated feedback from 13 prior agent sessions. Six spec-blockers landed, five spec-clarifications applied, fourteen nice-to-haves recorded in `BACKLOG.md`. The framework now formalizes the orchestrator role (CONVENTIONS.md + DECISIONS.md + spec-delta-application skill), schema-splits open_questions into open_questions + carry_forward, and replaces the monolithic THREAD_LOG body with a per-session closeouts pattern. Next session is back to project-level work (Thaumaturge `thaum-tools`) with the upgraded framework as the base.
+
+## Files Touched
+
+- **Added:**
+  - `.codecarto/templates/closeout-template.md`
+  - `.codecarto/templates/conventions-template.md`
+  - `.codecarto/templates/decisions-template.md`
+  - `.codecarto/templates/deltas-applied.md`
+  - `.codecarto/templates/reimplementation-spec-opinionated.md`
+  - `.codecarto/skills/spec-delta-application/SKILL.md`
+  - `.codecarto/BACKLOG.md`
+  - `.codecarto/CHANGELOG-2026-05-02-feedback-pass.md`
+  - `.codecarto/closeouts/2026-05-02-framework-feedback-pass.md` (this file)
+  - `Feedback From Agents/Framework feedback pass - 2026-05-02.txt`
+- **Modified:**
+  - `.codecarto/GUIDE.md` (trust-boundaries table extended; new subsections: Primary vs Secondary, Orchestrator-Maintained Artifacts, Subagent Delegation, Open Questions vs Carry-Forward, Strategic Alignment Hook; Session Update Protocol updated; folder layout updated)
+  - `.codecarto/workflow/status.yaml` (open_questions/carry_forward schema split)
+  - `.codecarto/workflow/VALIDATE.md` (carry_forward routing rule + worked PARTIAL example)
+  - `.codecarto/templates/architecture-map.md` (Carry-Forward section)
+  - `.codecarto/templates/behavioral-contracts.md` (Carry-Forward section)
+  - `.codecarto/templates/protocols-and-state.md` (Carry-Forward section)
+  - `.codecarto/templates/reverse-engineering-bundle.md` (Carry-Forward section)
+  - `.codecarto/templates/reimplementation-spec.md` (Known Unknowns + Carry-Forward shapes)
+  - `.codecarto/templates/thread-log-entry-template.md` (repurposed as legacy one-line index entry template)
+  - `.codecarto/THREAD_LOG.md` (rewritten as one-line-pointer index)
+  - `.codecarto/CONTRIBUTING.md` (THREAD_LOG dedup linter; carry_forward in testing checklist)
+  - `.codecarto/NEW_THREAD_BLURB.md` (carry_forward routing; per-session closeout pattern; file-system-sync warning)
+  - `Feedback From Agents/FEEDBACK_INDEX.md` (cross-cutting-themes table annotated with resolution markers; entry 15 added)
+- **Deleted:** none.
+
+## Tests / Gates
+
+| Gate | Result | Notes |
+|---|---|---|
+| File-path consistency | PASS | Every path referenced in GUIDE.md, NEW_THREAD_BLURB.md, VALIDATE.md, CONTRIBUTING.md, and pipeline YAMLs resolves to a real file. |
+| Schema consistency (status.yaml ↔ templates) | PASS | The `{id, kind, target_phase, deferred_reason}` shape is consistent across status.yaml, all 5 templates' Carry-Forward sections, GUIDE.md "Open Questions vs Carry-Forward", and VALIDATE.md's worked example. |
+| Trust-boundaries table coverage | PASS | New artifacts (closeouts, CONVENTIONS.md, DECISIONS.md, BACKLOG.md) all listed with access columns. |
+| Closeout-template self-application | PASS | This closeout file uses `templates/closeout-template.md`. |
+| FEEDBACK_INDEX.md self-awareness | PASS | Cross-cutting-themes table now carries APPLIED / CLARIFIED / DEFERRED-Bxx markers; entry 15 added. |
+
+## Decisions Beyond Prompt
+
+- **D-meta-1** | The `spec-delta-application` skill lives at a new top-level `.codecarto/skills/` directory (sibling of `findings/`), not inside `findings/`. | The prompt suggested "or a new top-level skills location — propose where" — chosen because spec-delta-application is post-pipeline (not phase-bound), so `findings/<phase>/SKILL.md` would mis-locate it. Trust-boundaries table updated to include `skills/*/SKILL.md`.
+- **D-meta-2** | Rather than create CONVENTIONS.md and DECISIONS.md as filled-in framework artifacts, the framework ships them as `templates/conventions-template.md` and `templates/decisions-template.md` (skeletons that projects copy to `.codecarto/CONVENTIONS.md` / `.codecarto/DECISIONS.md`). | Per the prompt's "generalize from working examples, don't copy" — the codex artifacts are 600+ lines of Thaumaturge-specific content. The framework version should be the skeleton (~150 lines) that projects fork.
+- **D-meta-3** | Schema split landed under both fields (`open_questions` AND `carry_forward`), not as a renaming. | A renaming would have broken the convention "open_questions field is the in-your-face honesty hook." Adding `carry_forward` as a sibling preserves the friction-driving job of `open_questions` (genuinely unknown) while solving the "two jobs" problem.
+- **D-meta-4** | THREAD_LOG.md was rewritten as an index, not migrated. | The framework's THREAD_LOG.md was empty (only the example comment block), so there was no historical content to migrate. A real project's THREAD_LOG.md migration is a separate, project-level operation; documented in the THREAD_LOG.md header.
+- **D-meta-5** | The Strategic Alignment Hook and the dual-mode reimpl-spec template land together as one feature, not two. | The hook *picks between* the two templates. Splitting them across two backlog items would have split the user experience.
+- **D-meta-6** | The "Append-mode supersession rule" (3 agents) was deferred to backlog (B7) despite meeting the 3-agent threshold. | The prompt said "Spec-blocker = raised by 3+ agents AND clean concrete edit." Append-mode supersession does not have a clean concrete edit — it implies a reconciliation pass, which is phase-shape change. Defer per the AND clause.
+- **D-meta-7** | "Validation as semantic check" (4 agents) was deferred to backlog (B8) despite the highest agent-count after THREAD_LOG scaling. | Same reasoning — no clean concrete edit; the proposed solutions (quality subagent, 1–5 score) are themselves design questions.
+- **D-meta-8** | The Resolutions footer (B12) is partially obviated by the new `carry_forward` field. | Documented in BACKLOG.md to wait for the next round of feedback before adding more machinery.
+
+## Proposed Conventions
+
+### CO-1 (framework-level) — "Schema-split a one-job-too-many field rather than renaming"
+
+**Why:** When a field is doing two distinct jobs (e.g., `open_questions` carrying both "still unknown" and "deferred to later phase" items), the cleaner fix is to add a sibling field rather than rename or restructure. Renaming breaks discoverability and history; adding a sibling preserves the original field's identity and the muscle-memory of past sessions while resolving the conflation.
+
+**How to apply:** When agent feedback consistently identifies a field as doing two jobs, prefer "split into A + B siblings" over "rename A to A1 and A2" or "restructure into a nested map." Tested in this pass with `open_questions` + `carry_forward`.
+
+(This is a framework-level convention, not a project-level one. It would land in a hypothetical `.codecarto-framework/CONVENTIONS.md` if such a file existed; for now, document in CHANGELOG.)
+
+### CO-2 (framework-level) — "Defer per AND, not OR, when a proposal mentions multiple criteria"
+
+**Why:** The triage discipline ("3+ agents AND clean concrete edit") is an AND, not an OR. Two proposals that hit 3+ agents but lacked clean concrete edits (B7, B8) deferred this pass — preserving the apply-in-good-faith posture rather than landing speculative changes.
+
+**How to apply:** Future framework-feedback passes treat the two clauses as conjoined. A proposal raised by many agents but lacking a clean edit goes to backlog with a smallest-viable-form sketch (which then unblocks the next pass).
+
+## Open Questions Left Behind
+
+| ID | Kind | Description | Deferred Reason |
+|---|---|---|---|
+| FW-OQ1 | needs-feedback | Whether the per-session closeout pattern actually feels lighter than monolithic THREAD_LOG once a project accumulates >20 closeout files. | Need real-world usage data; revisit after Thaumaturge accumulates 10–15 more closeouts. |
+| FW-OQ2 | needs-feedback | Whether the `kind` enum on open_questions/carry_forward entries is the right granularity. | Five values feels right but could prove too coarse (e.g., should `defer-to-phase` distinguish "rubric-fit" from "sequencing"?). Evaluate after 5+ projects use it. |
+| FW-OQ3 | needs-feedback | Whether the spec-delta-application skill being at `skills/` (sibling of `findings/`) is the right home, or if a `skills/post-pipeline/` subdirectory is needed once more post-pipeline skills land. | One skill in the directory today; revisit when a second one (e.g., spike-template) lands. |
+
+## Carry-Forward Routed
+
+| ID | Target Phase | Description | Deferred Reason |
+|---|---|---|---|
+| FW-CF1 | future-feedback-pass | The 14 BACKLOG.md items each have a "smallest viable form" sketch — they're ready for the next pass to execute. | Bundle scope: ship one pass per category (e.g., next pass = "post-pipeline machinery": spike template + amendments + defect-pass-N). |
+
+## Framework Feedback (the meta-meta layer)
+
+The framework-feedback pattern (this session) is itself a CodeCarto-style activity that the
+framework currently has no first-class concept of. Things I noticed running it:
+
+1. **The triage discipline (apply / clarify / defer / reject) ported cleanly from spec-delta-application to framework-delta-application.** The same four buckets, the same "don't rubber-stamp" posture. The fact that the pattern transfers is evidence it's load-bearing — worth pinning explicitly. Suggestion for next pass: lift the triage discipline into a shared sub-skill that both `spec-delta-application` and a future `framework-feedback-pass` skill reference. Today the discipline lives only in prompts.
+
+2. **The "do not modify" list at the bottom of FEEDBACK_INDEX.md was load-bearing.** Without it I would have rewritten the validation gate in the name of "improvement." The unanimous-defenders list is the framework's immune system. Worth promoting to a permanent fixture in CONTRIBUTING.md (currently lives only in the index).
+
+3. **The cross-cutting-themes table at the bottom of FEEDBACK_INDEX.md is the actual spec for this kind of pass.** Per-file feedback summaries are useful for context but the table is what drove triage. Suggestion: future framework changes should update the cross-cutting-themes table in the same edit (which this pass did, via the resolution markers — but that pattern should be standard, not invented per-pass).
+
+4. **The framework's self-applied `.codecarto/` is a real sanity test.** Editing GUIDE.md broke nothing because the framework's own self-application is structurally trivial (no findings, no closeouts before this session). For a richer self-application, edits to the framework would have a sharper feedback loop. Suggestion for future: maintain a synthetic example project (`examples/<small-codebase>/`) with a populated `.codecarto/` so framework edits can be smoke-tested against a real artifact.
+
+5. **There's no skill for "framework-feedback-pass" itself.** This session ran on the discipline embedded in the prompt — apply blockers, defer nice-to-haves, preserve unanimous-defenders, write a CHANGELOG with the same shape as DELTAS-APPLIED.md, update the index with resolution markers. That's a reusable workflow. Worth codifying as a skill the same way `spec-delta-application` was codified this pass. Maybe `skills/framework-feedback-pass/SKILL.md` is the next entry in `skills/`.
+
+## Next Session Pointer
+
+Next concrete step: back to **Thaumaturge module work — `thaum-tools`** — but now with the
+upgraded framework as the base. Specifically the next session should:
+
+1. Read this closeout file plus `.codecarto/CHANGELOG-2026-05-02-feedback-pass.md` to inherit the framework changes.
+2. The codex `.codecarto/CONVENTIONS.md` and `DECISIONS.md` artifacts are now the *project-level* artifacts; the framework-level skeletons are in `templates/conventions-template.md` and `templates/decisions-template.md`. The orchestrator's discipline maintaining those project files is now first-class.
+3. The `carry_forward` schema split is now usable — items routed across phases get explicit `target_phase` IDs. Use it in the next session's status.yaml updates.
+4. The per-session closeout pattern means `closeouts/2026-05-XX-thaum-tools.md` is the next file to write at session close, not an append to a monolithic THREAD_LOG.
+5. Pending: Δ-36 (Ollama unknown done_reason) and Δ-37 (allowed-loopback wire shape) noted as D501/D502 in codex's DECISIONS.md — next spec-revision pass picks these up using the new `spec-delta-application` skill.

package/.codecarto/findings/architecture/README.md

@@ -0,0 +1,3 @@
+# Architecture Findings
+
+System structure, layers, dependency direction, and public surface inventory.