codecartographer-pi 0.10.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
@@ -55,8 +57,9 @@ 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).
+4. `scratch/checkpoints/<phase>.md`, if present, to resume durable in-phase progress after compaction or interruption.
+5. The current phase's `SKILL.md` for detailed instructions on what to analyze and produce.
+6. 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.
 
@@ -75,19 +78,21 @@ 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. |
-| Scratch (read-write) | `scratch/*` | Disposable working notes. |
+| Scratch (read-write) | `scratch/*` | Working notes; `scratch/checkpoints/<phase>.md` is the durable in-phase continuation checkpoint until the phase validates. |
 
 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.
@@ -100,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
 
@@ -118,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.
 
@@ -158,7 +167,13 @@ Before beginning a phase, estimate how much source material you need to read. Fo
 - 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.
+- 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 the phase handoff. See "Open Questions vs Carry-Forward" below.
+
+### Synthesis compression boundary
+
+The porting bundle is the intentional compression boundary before `reimplementation-spec`. Its Source Index must preserve load-bearing claims, defect dispositions, coverage gaps, and exact pointers for targeted deep reads. The final synthesis phase reads the bundle by default; it opens architecture, contracts, protocols, or defect reports only when the bundle names a gap or conflict, an acceptance scenario needs omitted detail, a claim needs stronger evidence, or a defect disposition needs its rationale. If the bundle cannot support that selective workflow, mark validation `PARTIAL` instead of loading every upstream report by habit.
 
 ### Subagent Delegation for Large Codebases
 
@@ -170,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:
@@ -185,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
 
@@ -198,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
 
@@ -217,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.
 
@@ -236,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.
 
@@ -248,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.
 
@@ -275,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.
@@ -287,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/porting/SKILL.md

@@ -7,6 +7,12 @@ description: Synthesize architecture, contracts, and protocol findings into a re
 
 This phase synthesizes the outputs of architecture, contracts, and protocols. If defect reports exist, also read and integrate them: `findings/defect-scan/defect-report.md` (full-with-audit pipeline) or both `findings/defect-scan-mechanical/mechanical-defects.md` and `findings/defect-scan-semantic/semantic-defects.md` (full-with-deep-audit pipeline). The pipeline ensures all required phases are complete before this one runs. Read the prior phase artifacts before starting.
 
+Treat the reverse-engineering bundle as the pipeline's intentional compression boundary. It must be self-sufficient enough for `reimplementation-spec` to start from this one artifact rather than loading every upstream report. Preserve compact source pointers instead of copying upstream prose:
+- Add a Source Index covering architecture, contracts, protocols/state, and defects when present.
+- Carry forward every load-bearing invariant, acceptance obligation, compatibility hazard, and defect disposition.
+- For omitted detail, name the canonical upstream section and the exact condition that should trigger a targeted deep read.
+- Surface conflicts and incomplete coverage explicitly; never hide them behind synthesis.
+
 The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.
 
 Keep four classes of findings separate throughout:
@@ -43,6 +49,7 @@ Use the output template at `templates/reverse-engineering-bundle.md`. Produce:
 - A protocol and state note set.
 - Portability hazards consolidated from all prior phases.
 - Observed facts separated from inferred structure.
+- A compact Source Index and explicit coverage gaps that let downstream synthesis deep-read selectively.
 
 Bias toward evidence over cleverness:
 - Prefer tests over assumptions.

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

@@ -7,6 +7,14 @@ description: Convert reverse-engineering findings into a language-agnostic reimp
 
 Use this skill after the architecture, behavior, and protocol passes are complete enough to trust.
 
+Start with `findings/porting/reverse-engineering-bundle.md`; it is the default compression boundary for this phase. Do not load every lower-level finding automatically. Follow the bundle's Source Index and deep-read architecture, contracts, protocols, or defect reports only when:
+- the bundle names a gap or conflict,
+- an acceptance scenario needs detail the bundle deliberately omitted,
+- a load-bearing claim lacks enough evidence to state safely, or
+- a defect disposition needs its original rationale.
+
+Record those targeted deep reads in the spec's Coverage and limits section. If the bundle is not self-sufficient, mark the affected validation criterion PARTIAL and route the gap through `open_questions` or `carry_forward` rather than silently reconstructing the whole pipeline in context.
+
 Treat the source repo as evidence, not as a template.
 
 Define concept-level modules:
@@ -61,6 +69,8 @@ End with a spike list:
 - risky performance assumptions
 - platform-sensitive areas that need targeted tests
 
+For every defect in the bundle, preserve its disposition (`fix before porting`, `port differently`, or `leave behind`) and convert it into an explicit design consequence or acceptance check.
+
 Use the output template at `templates/reimplementation-spec.md`.
 
 The source code to analyze is in the parent directory (`../` relative to `.codecarto/`). This is the repository root.

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/architecture-map.md

@@ -104,6 +104,14 @@
   logs, caches, databases, generated artifacts.
 -->
 
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: source inspection | tests | runtime verification | upstream findings
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
 ## Open Questions
 
 <!-- Items that are still genuinely unknown — need a runtime test, maintainer decision, or spec ruling.
@@ -138,6 +146,7 @@
 | 3 | Public surfaces are identified. | PASS / PARTIAL / FAIL | |
 | 4 | Runtime lifecycle, concurrency model, and porting priorities are summarized. | PASS / PARTIAL / FAIL | |
 | 5 | Findings are marked with evidence levels. | PASS / PARTIAL / FAIL | |
+| 6 | 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/behavioral-contracts.md

@@ -91,6 +91,14 @@
 |---|----------|--------------|--------|------------------|
 | 1 | | | | |
 
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: source inspection | tests | runtime verification | upstream findings
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
 ## Open Questions
 
 <!-- Items that are still genuinely unknown — need a runtime test, maintainer decision, or spec ruling.
@@ -129,6 +137,7 @@
 | 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 | |
+| 7 | 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/defect-report.md

@@ -99,6 +99,14 @@
 
 ---
 
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: source inspection | tests | runtime verification | upstream findings
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
 ## Validation
 
 <!-- Fill in this table per workflow/VALIDATE.md. The rows below match the full pipeline.
@@ -111,6 +119,7 @@
 | 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 | |
+| 6 | 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/mechanical-defects.md

@@ -88,6 +88,14 @@
 
 ---
 
+## Coverage and limits
+
+- Inspected scope:
+- Skipped scope:
+- Evidence basis: source inspection | tests | runtime verification | upstream findings
+- Known blind spots:
+- Coverage disposition: COMPLETE | PARTIAL
+
 ## Validation
 
 <!-- Fill in this table per workflow/VALIDATE.md. The rows below match the mechanical-pass scope. -->
@@ -99,6 +107,7 @@
 | 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 | |
+| 6 | 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/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-checkpoint.md

@@ -0,0 +1,41 @@
+---
+phase: <phase-id>
+updated_at: <ISO-8601 timestamp>
+source: manual | pi-compaction
+---
+
+# Phase checkpoint
+
+## Goal and output
+
+- Phase:
+- Primary output:
+- Current objective:
+
+## Evidence established
+
+<!-- Preserve evidence levels and exact source paths. -->
+
+## Files and subsystems inspected
+
+- Inspected:
+- Not yet inspected:
+
+## Output progress
+
+- Sections complete:
+- Sections remaining:
+
+## Open questions and carry-forward candidates
+
+- Open questions:
+- Carry-forward:
+
+## Validation gaps
+
+- Criteria satisfied:
+- Criteria at risk:
+
+## Exact next steps
+
+1.

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
+
+  -