codecartographer-pi 0.11.0 → 0.12.0

package/.codecarto/GUIDE.md

@@ -6,6 +6,8 @@ This is a structured reverse-engineering workspace embedded inside a repository.
 
 All CodeCartographer files live inside this `.codecarto/` folder. The source code is everything outside it.
 
+**Synthesis exception.** When `workflow/status.yaml` selects `workflow/pipeline-synthesis.yaml`, this workspace is planning a new product rather than reverse-engineering the surrounding repository. Use `inputs/vision.md` and the read-only library paths supplied by the executable host. Do not treat the parent directory as source evidence for synthesis.
+
 Work in explicit phases. Do not try to do everything at once.
 
 ## Roles
@@ -76,9 +78,11 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | 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. |
+| Synthesis input (user-maintained) | `inputs/vision.md` | The user fills this before the synthesis pipeline starts. Implementing phases read it but do not rewrite the raw brief. |
+| Workflow state (framework-owned) | `workflow/status.yaml` | Read to understand progress. Implementing sessions never edit it directly; completion applies a validated phase handoff under a lock. |
 | 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. |
+| Phase handoff (read-write) | `scratch/handoffs/<phase>.yaml` | Implementing sessions propose state changes and closeout content here. The framework validates and applies them. |
+| Closeouts (framework-owned) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Completion writes or updates one canonical closeout and one idempotent index entry. |
 | 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. |
@@ -88,7 +92,7 @@ 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.
+Seven 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.
@@ -101,6 +105,7 @@ Six pipeline variants are available. Check the `pipeline` field in `workflow/sta
 | 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 |
+| Synthesis | `workflow/pipeline-synthesis.yaml` | vision-capture → goal-synthesis-propose → spec-merge → goal-synthesis-finalize | Convert a user vision and explicitly confirmed library specs into a provenance-backed project plan; requires Pi or MCP |
 
 ## Evaluation Objective
 
@@ -119,6 +124,9 @@ Produce a reusable evaluation bundle for the repository. The bundle has two purp
 | 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` |
+| Synthesis proposal | `findings/goal-synthesis/proposal.md` |
+| Merged specification | `findings/spec-merge/merged-spec.md` |
+| Evidence-backed project plan | `findings/goal-synthesis/project-plan.md` |
 
 Not all deliverables apply to every pipeline variant. Check your active pipeline YAML for which phases and outputs are included.
 
@@ -161,7 +169,7 @@ Before beginning a phase, estimate how much source material you need to read. Fo
 - Defer deep reads until the current phase actually needs them.
 - For long phases, update `scratch/checkpoints/<phase>.md` after each major subsystem or output section. Pi writes a phase-aware checkpoint automatically after phase compaction; other hosts should use `templates/phase-checkpoint.md` manually.
 - Every primary output must include `Coverage and limits`: inspected scope, skipped scope, evidence basis, known blind spots, and a `COMPLETE` or `PARTIAL` disposition.
-- 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.
+- 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 the phase handoff. See "Open Questions vs Carry-Forward" below.
 
 ### Synthesis compression boundary
 
@@ -177,8 +185,9 @@ For codebases over roughly 50 source files or 100K LOC, do not burn primary cont
 
 - **`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.
+- **`post_pipeline`** — optional work after the active pipeline: spikes, amendments, deltas, maintainer rulings, or opinionated reruns. These items do not make pipeline completion partial and must not be disguised as carry-forward targets.
 
-Both lists carry structured entries. Recommended shape:
+All three collections carry structured entries. Recommended phase-state shape:
 
 ```yaml
 open_questions:
@@ -192,9 +201,13 @@ carry_forward:
     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.
+post_pipeline:
+  - id: post-runtime-1
+    kind: spike
+    description: Capture restart behavior against a packaged build after the pipeline is complete.
 ```
 
-`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`).
+`kind` is one of: `needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`, or a post-pipeline work kind such as `spike` or `amendment`. Every new `carry_forward.target_phase` must be an ID in the active pipeline. Every `post_pipeline` entry requires a stable ID. Open questions should carry a stable `id` (e.g. `q-loadconfig-ambiguity`); if omitted, the framework auto-assigns one. When a later phase resolves an open question, list its id in `open_question_closures` to remove it from all phases. The downstream phase records resolved carry-forward IDs in `carry_forward_closures`; completion removes those entries atomically.
 
 ## Phase Selection Logic
 
@@ -205,9 +218,9 @@ carry_forward:
 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.
+8. Write `scratch/handoffs/<phase>.yaml`, then run completion. The framework verifies the primary output and validation, applies the handoff to `status.yaml`, and maintains the closeout and `THREAD_LOG.md` 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.
+**Parallel phases:** Some phases share the same `depends_on` and can run concurrently. Each session writes only its phase handoff; completion serializes canonical state changes with a filesystem lock so sibling phase state is preserved.
 
 ## Session Update Protocol
 
@@ -224,9 +237,9 @@ When a session starts:
 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.
+2. Write `scratch/handoffs/<phase>.yaml` with `schema_version: 1`, the exact `phase_id`, arrays for `owner_notes`, `open_questions`, `carry_forward`, `carry_forward_closures`, `open_question_closures`, `post_pipeline`, and `decisions`, plus `closeout_summary` and optional multiline `closeout_content`. Omitted arrays default to empty; malformed collection shapes fail completion.
+3. Record 2-3 key observations in the handoff's `owner_notes` (e.g., row counts, notable decisions, scope of analysis). Do not provide a canonical timestamp; the host clock owns timestamps.
+4. Run `/codecarto-complete` (or `codecarto_complete`). The framework atomically updates `workflow/status.yaml`, writes or updates one canonical closeout, and appends one idempotent `THREAD_LOG.md` entry. Do not edit those files directly.
 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.
 
@@ -243,9 +256,9 @@ This conversation produces inputs the synthesis phase actually needs (locked tar
 
 ## 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.
+These rules combine framework enforcement with explicit agent discipline:
 
-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.
+1. **Validation gate:** Completion refuses FAIL or MISSING validation. Fix the output first and re-run validation. If validation is PASS WITH GAPS, document the gaps in the handoff's `open_questions`.
 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.
 
@@ -255,7 +268,7 @@ These rules cannot be enforced by the template — they rely on the LLM followin
 - 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.
+- Completion owns `closeouts/<YYYY-MM-DD>-<phase-or-module>.md` and `THREAD_LOG.md`; implementing sessions supply closeout content through their phase handoff.
 - 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.
 
@@ -282,7 +295,8 @@ your-repo/
       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.
+    scratch/                   # Disposable analysis notes plus framework handoffs/checkpoints.
+      handoffs/<phase>.yaml    # Structured state/closeout proposal consumed by completion.
     templates/                 # Output templates and log entry templates.
     skills/
       spec-delta-application/  # Post-pipeline skill: apply triaged spec deltas with citation discipline.
@@ -294,6 +308,7 @@ your-repo/
       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).
+      pipeline-synthesis.yaml             # 4-phase forward synthesis (Pi/MCP 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).

package/.codecarto/README.md

@@ -36,4 +36,7 @@ pipeline: workflow/pipeline.yaml                       # 5-phase without defect
 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
+pipeline: workflow/pipeline-synthesis.yaml             # 4-phase forward synthesis — vision + confirmed library specs → project plan (Pi/MCP only)
 ```
+
+The synthesis pipeline is different from the analysis variants: it requires Pi or MCP, a configured non-empty CodeCartographer library, and a completed `inputs/vision.md`. It pauses after proposing candidate specs and will not merge or finalize until the user changes at least one proposal checkbox from `[ ]` to `[x]`.

package/.codecarto/findings/goal-synthesis/README.md

@@ -0,0 +1,3 @@
+# Goal Synthesis
+
+The synthesis pipeline writes the human-confirmation proposal and final evidence-backed project plan here.

package/.codecarto/findings/goal-synthesis-finalize/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: finalize-evidence-backed-project-plan
+description: Transform a confirmed product vision and merged reusable specifications into an executable project plan whose important decisions remain traceable.
+---
+
+# Finalize Evidence-Backed Project Plan
+
+Produce `findings/goal-synthesis/project-plan.md` using `templates/project-plan.md`.
+
+Use `findings/spec-merge/merged-spec.md` as the default compression boundary. Deep-read a confirmed library specification only when the merged intermediate names a gap, unresolved conflict, or missing acceptance detail. Record any targeted deep reads in Coverage and limits.
+
+Create a coherent build plan:
+
+- define the first executable vertical slice,
+- identify target components and stable public boundaries,
+- break delivery into dependency-ordered work packages,
+- give every work package an observable acceptance gate,
+- preserve open conflicts and unknowns with owners or dispositions,
+- state deliberate non-goals.
+
+The provenance ledger is mandatory. Map every load-bearing architecture, scope, behavior, and sequencing decision to one of:
+
+- an exact confirmed library reference and version,
+- an exact product-vision section,
+- an explicit synthesis decision, marked `strong inference`,
+- an unresolved choice, marked `open question`.
+
+Do not hide conflicts by averaging incompatible source behaviors. Prefer a clear disposition with rationale. A complete-looking plan with missing provenance must fail validation.
+
+End with Coverage and limits and the validation table from the template.

package/.codecarto/findings/goal-synthesis-propose/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: propose-synthesis-inputs
+description: Rank reusable CodeCartographer library specifications against a captured product vision and create an explicit human confirmation gate.
+---
+
+# Propose Synthesis Inputs
+
+Produce `findings/goal-synthesis/proposal.md` using `templates/proposal.md`.
+
+Read `findings/vision-capture/vision.md` first. Use the library index and entry paths supplied in the phase prompt. Start with metadata for all entries; deep-read a specification only when its headline, tags, or capabilities indicate a credible fit that metadata cannot resolve.
+
+For each serious candidate:
+
+- map its reusable capabilities to concrete vision needs,
+- state the benefit of including it,
+- identify likely conceptual conflicts, irrelevant surface details, and integration costs,
+- identify vision needs no candidate covers,
+- rank it relative to the other candidates.
+
+Write every candidate row with an unchecked `[ ]` box. Never confirm on the user's behalf, including in auto mode. The user confirms by editing one or more boxes to `[x]` after reviewing the proposal.
+
+On a re-run, preserve existing `[x]` selections unless the user explicitly changed them. Re-evaluate the proposal and mark validation PASS only when the shortlist is coherent; confirmation itself is enforced structurally by the next phase, not by optimistic prose.
+
+Treat library entries as read-only. Do not merge them yet. End with Coverage and limits and the validation table from the template.

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

@@ -0,0 +1,3 @@
+# Specification Merge
+
+The synthesis pipeline writes its normalized, provenance-rich merge of confirmed library entries here as `merged-spec.md`.

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

@@ -0,0 +1,23 @@
+---
+name: merge-confirmed-specifications
+description: Normalize only human-confirmed reimplementation specifications into a provenance-rich, conflict-explicit intermediate for project planning.
+---
+
+# Merge Confirmed Specifications
+
+Produce `findings/spec-merge/merged-spec.md` using `templates/merged-spec.md`.
+
+Read the product vision, proposal, and only the library entries identified as human-confirmed in the phase prompt. The runtime preflight has already verified that at least one proposal checkbox is `[x]`; do not broaden the selection yourself.
+
+Merge by concept, not by original repository structure:
+
+- normalize capabilities that use different names for the same behavior,
+- preserve load-bearing invariants and externally observable acceptance behavior,
+- distinguish reusable semantics from adapters and source-specific delivery surfaces,
+- record each incompatibility in the conflict ledger,
+- choose `adopt`, `adapt`, `defer`, or `reject` only when the evidence supports it,
+- keep gaps against the vision visible rather than filling them with invented behavior.
+
+Every load-bearing row must cite an exact library reference and version, such as `team/router@v2`, or an exact section of the vision. A merged claim without provenance is a validation failure.
+
+Treat library entries as read-only. End with Coverage and limits and the validation table from the template.

package/.codecarto/findings/vision-capture/README.md

@@ -0,0 +1,3 @@
+# Vision Capture
+
+The synthesis pipeline writes its bounded product vision here as `vision.md`.

package/.codecarto/findings/vision-capture/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: capture-product-vision
+description: Convert a user's intended product into bounded outcomes, constraints, acceptance scenarios, assumptions, and non-goals before selecting reusable specifications.
+---
+
+# Capture Product Vision
+
+Produce `findings/vision-capture/vision.md` using `templates/vision.md`.
+
+Treat user-stated intent as the primary evidence. Do not inspect or choose library entries in this phase; selection comes later so the available implementation ingredients do not distort the problem definition.
+
+Capture:
+
+- the specific audience and problem,
+- desired user-visible outcomes,
+- scope boundaries and deliberate non-goals,
+- technical, operational, timeline, privacy, and compatibility constraints,
+- measurable success criteria,
+- black-box acceptance scenarios,
+- assumptions and decisions that still require confirmation.
+
+Do not invent missing product choices. If this phase is running without a sufficiently detailed user vision, use the current conversation and any explicitly supplied inputs, mark unsupported details as assumptions, and return `PASS WITH GAPS`. Record truly blocking choices as stable open-question IDs in the phase handoff.
+
+Keep architecture preferences separate from required outcomes unless the user made them explicit. The next phases need freedom to compare multiple library specifications against the same neutral vision.
+
+End with Coverage and limits and the validation table from the template.

package/.codecarto/inputs/vision.md

@@ -0,0 +1,11 @@
+# Synthesis vision brief
+
+<!--
+Replace this comment with a short description of:
+- who the new product is for,
+- the problem it should solve,
+- the outcome you want,
+- any hard constraints or non-goals.
+
+The vision-capture phase will turn your brief into a structured, testable vision.
+-->

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

@@ -0,0 +1,58 @@
+# Confirmed Specification Merge
+
+## Confirmed inputs
+
+| Reference | Version | Source path | Role in the merge |
+|---|---|---|---|
+| | | | |
+
+## Normalized capability model
+
+| Capability | Required behavior | Invariants | Source references | Vision fit |
+|---|---|---|---|---|
+| | | | | |
+
+## Architecture ingredients
+
+| Concept | Responsibility | Inputs and outputs | Constraints | Provenance |
+|---|---|---|---|---|
+| | | | | |
+
+## Conflict ledger
+
+| ID | Sources in tension | Conflict | Disposition | Confidence |
+|---|---|---|---|---|
+| | | | adopt / adapt / defer / reject | observed / strong inference / open question |
+
+## Gaps against the vision
+
+| Vision need | Missing or weak evidence | Plan consequence |
+|---|---|---|
+| | | |
+
+## Acceptance behavior inventory
+
+| # | Behavior | Observable acceptance | Provenance |
+|---|---|---|---|
+| 1 | | | |
+
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: confirmed library specifications | vision | proposal
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|---|---|---|
+| 1 | Only human-confirmed library entries are merged. | PASS / PARTIAL / FAIL | |
+| 2 | Capabilities, invariants, constraints, and acceptance behavior are normalized by concept rather than copied by source structure. | PASS / PARTIAL / FAIL | |
+| 3 | Conflicts, gaps, and chosen dispositions are explicit. | PASS / PARTIAL / FAIL | |
+| 4 | Every load-bearing merged claim has a provenance reference. | PASS / PARTIAL / FAIL | |
+| 5 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/phase-handoff.yaml

@@ -0,0 +1,22 @@
+# Phase handoff schema v1. Copy to scratch/handoffs/<phase-id>.yaml.
+# The framework owns canonical timestamps, status.yaml, closeouts, and THREAD_LOG.md.
+schema_version: 1
+phase_id: <phase-id>
+owner_notes: []
+open_questions: []
+carry_forward: []
+carry_forward_closures: []
+# Resolved open questions: their IDs are removed from all phases.
+open_question_closures: []
+# Work after the active pipeline: spikes, amendments, deltas, maintainer rulings,
+# or opinionated reruns. Every entry requires a stable id.
+post_pipeline: []
+decisions: []
+closeout_summary: ""
+# Optional full closeout Markdown. YAML literal blocks are supported.
+closeout_content: |-
+  # Closeout — <phase-id>
+
+  ## Summary
+
+  -

package/.codecarto/templates/project-plan.md

@@ -0,0 +1,70 @@
+# Evidence-Backed Project Plan
+
+## Product definition
+
+## Scope
+
+### First executable slice
+
+### Subsequent increments
+
+### Non-goals
+
+## Target architecture
+
+| Component | Responsibility | Public boundary | Owned state and invariants | Provenance |
+|---|---|---|---|---|
+| | | | | |
+
+## Work packages
+
+| ID | Deliverable | Dependencies | Acceptance gate | Risk |
+|---|---|---|---|---|
+| WP-01 | | | | |
+
+## Implementation sequence
+
+| Order | Work package | Why now | Exit evidence |
+|---|---|---|---|
+| 1 | | | |
+
+## Acceptance plan
+
+| # | Scenario | Input or starting state | Observable result | Source |
+|---|---|---|---|---|
+| 1 | | | | |
+
+## Provenance ledger
+
+<!-- This is the differentiating contract of the synthesis pipeline. Every load-bearing decision should map to a confirmed spec, the product vision, or an explicit synthesis decision. -->
+
+| Decision ID | Plan decision | Source specification or vision section | Evidence level | Conflict status |
+|---|---|---|---|---|
+| D-01 | | | observed fact / strong inference / open question | none / resolved / open |
+
+## Conflict and unknowns register
+
+| ID | Issue | Disposition or owner | Blocking work package |
+|---|---|---|---|
+| | | | |
+
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: vision | confirmed specifications | merged-spec | explicit synthesis decisions
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|---|---|---|
+| 1 | The plan defines coherent product scope, architecture, work packages, dependencies, and acceptance gates. | PASS / PARTIAL / FAIL | |
+| 2 | Each load-bearing plan decision is traceable through the provenance ledger. | PASS / PARTIAL / FAIL | |
+| 3 | Conflicts and unknowns remain visible with explicit dispositions. | PASS / PARTIAL / FAIL | |
+| 4 | The implementation sequence identifies an executable first slice. | PASS / PARTIAL / FAIL | |
+| 5 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/proposal.md

@@ -0,0 +1,43 @@
+# Synthesis Proposal
+
+## Vision fit summary
+
+## Candidate specifications
+
+<!-- The first column is the human confirmation gate. Leave every candidate unchecked when first writing this proposal. The user changes selected rows from [ ] to [x]. Keep entry references exactly as shown in the phase prompt. -->
+
+| Confirm | Library entry | Version | Vision fit | Reusable capabilities | Likely conflicts or costs |
+|---|---|---|---|---|---|
+| [ ] | `namespace/entry-slug` | v1 | | | |
+
+## Capability coverage
+
+| Vision need | Candidate coverage | Gap or decision |
+|---|---|---|
+| | | |
+
+## Recommendation
+
+## Confirmation instructions
+
+Review the candidates above. Change at least one `[ ]` to `[x]`, save this file, and then continue the pipeline. CodeCartographer will refuse to merge or finalize until a selection is explicitly confirmed.
+
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: library metadata | vision | targeted specification reads
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|---|---|---|
+| 1 | Candidate library entries are ranked against explicit vision needs. | PASS / PARTIAL / FAIL | |
+| 2 | Inclusion benefits, likely conflicts, and missing capabilities are stated for every candidate. | PASS / PARTIAL / FAIL | |
+| 3 | At least one entry is presented with an unchecked human-confirmation box. | PASS / PARTIAL / FAIL | |
+| 4 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL

package/.codecarto/templates/vision.md

@@ -0,0 +1,63 @@
+# Product Vision
+
+## Problem and audience
+
+- Target audience:
+- Problem to solve:
+- Why existing approaches are insufficient:
+
+## Desired outcomes
+
+| Outcome | User-visible evidence | Priority |
+|---|---|---|
+| | | P0 / P1 / P2 |
+
+## Product boundaries
+
+### In scope
+
+### Non-goals
+
+## Constraints
+
+| Constraint | Source | Consequence |
+|---|---|---|
+| | user-stated / inferred | |
+
+## Success measures
+
+| Measure | Target | How it will be observed |
+|---|---|---|
+| | | |
+
+## Acceptance scenarios
+
+| # | Actor and starting state | Action | Observable outcome |
+|---|---|---|---|
+| 1 | | | |
+
+## Assumptions and unresolved decisions
+
+| ID | Type | Statement | Resolution needed |
+|---|---|---|---|
+| | assumption / decision | | |
+
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: user vision | supplied documents | inference
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
+## Validation
+
+| # | Criterion | Result | Evidence |
+|---|---|---|---|
+| 1 | The target audience, problem, outcomes, constraints, and non-goals are explicit. | PASS / PARTIAL / FAIL | |
+| 2 | Success measures and acceptance scenarios are testable. | PASS / PARTIAL / FAIL | |
+| 3 | Assumptions and unresolved decisions are separated from confirmed intent. | PASS / PARTIAL / FAIL | |
+| 4 | Coverage and limits name inspected scope, skipped scope, evidence basis, and blind spots. | PASS / PARTIAL / FAIL | |
+
+**Validated by:** [session identifier or date]
+**Overall:** PASS / PASS WITH GAPS / FAIL