codecartographer-pi 0.1.0

package/.codecarto/BACKLOG.md

@@ -0,0 +1,192 @@
+# Backlog
+
+Deferred framework improvements with rationale and source feedback files. Items here were
+proposed by one or more agents in the feedback corpus but were not load-bearing enough to land
+in the 2026-05-02 framework feedback pass. Each item is a candidate for a future pass.
+
+Format per entry: rationale + which feedback file(s) raised it + what the smallest viable form
+of the change would look like.
+
+---
+
+## B1. Spike template + first-class spike concept
+
+**Raised by:** `Run three Thaumaturge implementation spikes.txt`, `Apply 20 spec deltas to Thaumaturge.txt`, `Agent on protocols phase - protocols.txt` (3 agents)
+
+**Why deferred:** A spike template would land cleanly, but "first-class spike concept" implies workflow machinery (a `spikes/` directory convention, a validation rule for spike outputs, status.yaml fields for spike tracking). The 2026-05-02 pass is already changing the closeouts pattern, the open_questions schema, and the orchestrator-maintained artifacts list. Adding spike machinery on top risks too much surface change in one revision.
+
+**Smallest viable form:** `templates/spike-report.md` skeleton with sections for Goal, Method, Measurements, Findings, Recommended Deltas. No workflow machinery; spikes stay a per-project convention initially. Status.yaml integration deferred until a project demonstrates the need.
+
+---
+
+## B2. Amendments mechanic (`findings/amendments/` directory)
+
+**Raised by:** `Run three Thaumaturge implementation spikes.txt`, `Agent on protocols phase - protocols.txt` (2 agents — under threshold but persistent)
+
+**Why deferred:** "Phase outputs can't correct prior phases" is a real gap, but `carry_forward` (introduced in this pass) already covers the most common case (forward-routing a deferred item). True back-amendment (a later phase says "the architecture map is wrong about X") needs more design — should it edit the prior output? Append a "superseded by" marker? Live in a parallel directory? The shape isn't obvious enough to land safely.
+
+**Smallest viable form:** A pre-reimpl-spec "reconciliation" pass that surfaces contradictions across primary outputs. Less ambitious than a full amendments directory; uses existing artifacts.
+
+---
+
+## B3. Cross-CodeCartographer-workspace references in status.yaml
+
+**Raised by:** `Agent on reimplementation spec - reimplementation spec.txt` (1 agent)
+
+**Why deferred:** Single-agent ask. The use case (one CodeCarto workspace cites another) is real but rare. Most projects have one CodeCarto workspace. Designing a citation format that works across workspaces (relative paths? URLs? content-addressed IDs?) is non-trivial.
+
+**Smallest viable form:** A documented convention for citing across workspaces using `<other-workspace-path>/<phase>/<output>.md#<anchor>` paths, without machinery. If a project demonstrates the need, formalize.
+
+---
+
+## B4. 1–5 coverage-depth score (alternative to PASS WITH GAPS)
+
+**Raised by:** `Agent on reimplementation spec - reimplementation spec.txt` (1 agent)
+
+**Why deferred:** Validation is currently structural (PASS / PARTIAL / FAIL with criterion-by-criterion check). A semantic depth score is a real ask but conflicts with the framework's posture that "honest output is the default" — a 1–5 score invites grade inflation in a way the binary criteria do not. Worth more thought before landing.
+
+**Smallest viable form:** Optional second column in the validation block: "Depth: 1–5" with a rubric (1 = section header only; 5 = exhaustive). Use only when the team agrees on the rubric.
+
+---
+
+## B5. Programmatic markdown-regex validator
+
+**Raised by:** `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on broad Defect Scan - defect-scan-broad.txt` (2 agents)
+
+**Why deferred:** A real validator (parses status.yaml, checks output paths, verifies validation blocks exist with correct criterion counts, etc.) is a separate tooling project — more than a SKILL/template change. It deserves its own scoping.
+
+**Smallest viable form:** A `scripts/validate.sh` that runs `yq` + `grep` checks for the most common gates (every primary_output exists; every validation block has at least N rows; every status.yaml phase has a status field). Document, don't ship without consensus on scope.
+
+---
+
+## B6. CI grep gate for tripwire-named functions
+
+**Raised by:** `Agent on fifth module work - thaum-state.txt` (1 agent — project-level concern)
+
+**Why deferred:** This is a *project*-level CI concern (Thaumaturge), not a framework concern. The framework's job is to surface the convention (which the orchestrator does in CONVENTIONS.md); the project's job is to gate it. Documented for the orchestrator to pick up at the project level.
+
+**Smallest viable form:** Document in CONVENTIONS.md template's example entry that "production code path importing any tripwire-named function should fail the build" is a known follow-up. No framework artifact.
+
+---
+
+## B7. Append-mode supersession rule (consolidate vs append)
+
+**Raised by:** `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt`, `Agent on contracts phase - contracts.txt` (3 agents — at threshold but defers per scope)
+
+**Why deferred:** Real friction: secondary outputs accumulate overlapping descriptions and recency wins by unwritten convention. A "supersedes" marker would land cleanly, but it also implies a reconciliation pass before reimplementation-spec, which is a phase-shape change. Worth landing in a follow-up pass that focuses on append-mode discipline holistically.
+
+**Smallest viable form:** A `> SUPERSEDES <date>:<reason>` block convention at the top of each new dated section in append-mode files, plus a paragraph in GUIDE.md describing it. No machinery; just convention.
+
+---
+
+## B8. Validation as semantic check (not just structural / completeness)
+
+**Raised by:** `Agent on broad Defect Scan - defect-scan-broad.txt`, `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt` (4 agents — at-threshold)
+
+**Why deferred:** "LLM grades its own homework" is a real gap. The fix is either a quality-subagent (a separate LLM pass that grades against the criteria) or a coverage-depth score (B4). Both are larger changes than this pass should land. The structural check at minimum prevents the worst failure mode (skipping the criterion entirely).
+
+**Smallest viable form:** A `quality-review` skill that delegates to a subagent for criterion-by-criterion semantic check. Optional; not in the default closeout ritual.
+
+---
+
+## B9. Spec file split (single 1000+ line file → spec/ directory)
+
+**Raised by:** `Agent on fourth module work - thaum-engine.txt`, `Agent on second module work - thaum-providers-ollama.txt`, `Run three Thaumaturge implementation spikes.txt` (3 agents — at-threshold)
+
+**Why deferred:** This is a *project*-level concern (Thaumaturge's reimplementation-spec.md is 1300+ lines). The framework's template doesn't enforce a single file; a project can split. Documented for the orchestrator to pick up at the project level.
+
+**Smallest viable form:** A documented convention in the opinionated reimpl-spec template that says "if the spec exceeds N lines, split into spec/ with INDEX.md anchored to original section IDs." No framework machinery.
+
+---
+
+## B10. SKILL.md and template files redundancy / consolidation
+
+**Raised by:** `Agent on porting phase - porting.txt`, `Agent on protocols phase - protocols.txt`, `Agent on contracts phase - contracts.txt` (3 agents — at-threshold)
+
+**Why deferred:** "SKILL says X, template says X — agent reads both and reconciles" is a real cost. But the framework's posture is that SKILL.md is the *how* (analysis instructions) and template is the *shape* (output skeleton). Collapsing them risks losing the separation. A surgical edit (de-duplicate the obvious overlaps without merging) is hard to do without per-file judgment.
+
+**Smallest viable form:** A pass that inspects each SKILL/template pair and removes section headers from the SKILL that exactly match the template (the template alone is canonical for shape). Per-file work; not a single sweep.
+
+---
+
+## B11. Defect-pass-N append discipline (multi-pass defect-scan)
+
+**Raised by:** `Agent on Deep Defect Scan - defect-scan-deep.txt`, `Agent on broad Defect Scan - defect-scan-broad.txt` (2 agents)
+
+**Why deferred:** Defect-scan today expects "one pass = one phase output." Multi-pass (broad → deep) is a real pattern that emerged in Thaumaturge. Partially blessed in 2026-05-04 by `pipeline-full-with-deep-audit.yaml`, which splits the scan into mechanical (passes 1, 2, 6 — after architecture, before contracts) and semantic (passes 3, 4, 5 — after protocols, before porting) phases. Different mechanism than the originally-proposed within-phase pass-N append, but it covers the broad→deep use case. Open question: do projects still need the within-phase append pattern?
+
+**Smallest viable form:** A `templates/defect-report-pass-N.md` template with a `findings/defect-scan/passes/<pass-id>.md` directory convention. Documented; not pre-applied.
+
+---
+
+## B12. Resolutions footer / phase resolution mechanic
+
+**Raised by:** `Agent coordinating results - coordinating.txt`, `Agent on contracts phase - contracts.txt` (2 agents)
+
+**Why deferred:** Partially resolved by `carry_forward` in this pass — the routing-and-resolution loop now exists. The remaining ask (a "previously resolved" footer in each output, or a resolutions/ directory) may be obviated by `carry_forward` in practice. Wait for next-pass feedback before adding more machinery.
+
+---
+
+## B13. Engine→leaf seam contracts table
+
+**Raised by:** `Agent on fifth module work - thaum-state.txt` (1 agent — project-level)
+
+**Why deferred:** Project-level (Thaumaturge-specific). The framework's job is to surface the convention; CONVENTIONS.md template now has the shape for it. The actual SEAMS.md would live at the project level.
+
+---
+
+## B14. Cross-phase consistency check
+
+**Raised by:** `Agent on protocols phase - protocols.txt` (1 agent)
+
+**Why deferred:** "Contracts and protocols both touch dispatcher / redaction / SSE and must stay aligned" — the proposed consistency check is a pre-reimpl-spec reconciliation pass. Related to B7 (append-mode supersession). Bundle into the same future pass.
+
+---
+
+## B15. spec-delta-application SKILL canonical refinements (first-run friction)
+
+**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first real run of the SKILL post-2026-05-02 framework pass; high-signal because the SKILL had no field exposure before this)
+
+**Why deferred:** Six small refinements to the same SKILL.md / templates pair, all visible only after a non-spike-sourced run. Bundling makes the next pass cheap; piecemeal would churn the SKILL repeatedly.
+
+**Smallest viable form:** A surgical pass over `skills/spec-delta-application/SKILL.md` and `templates/deltas-applied.md` covering:
+- **Citation forms** — canonicalize a small family beyond the spike-sourced `[revised per <file> §<delta-id>]`. Round-3 introduced `[revised per DECISIONS.md D5XX (Δ-N), round-N]` for D-entry-sourced deltas and `[revised per closeouts/<file> §<id>, round-N]` for closeout-sourced deltas. Document both as canonical, alongside the spike form.
+- **Audit file path** — explicitly cover the non-spike case. Round-3 used `findings/deltas-applied/round-N.md` (directory convention) when the deltas weren't spike-driven; the existing "sibling-of-spec DELTAS-APPLIED.md" remains a special case for spike rounds.
+- **Closeout filename** — round-numbered (`closeouts/<YYYY-MM-DD>-spec-delta-N.md`) avoids the collision risk of the current `closeouts/<YYYY-MM-DD>-spec-deltas.md` when two passes happen on the same day.
+- **§header naming** — the spec's `## Post-Spike Revisions` header doesn't generalize for non-spike rounds. Rename to `## Post-Pipeline Revisions` (or similar) so post-pipeline non-spike rounds don't have to add explanatory paragraphs about why "Post-Spike" still applies.
+- **Step 6 prominence** — add a sentence to Step 6 ("Update the spec's front-matter citation conventions list") emphasizing this is required when the application introduces new citation forms; otherwise the audit-table marker list is unanchored.
+- **APPLY may refine the proposal** — Δ-36's literal D501 text was "map to 'error'" but the application refined to "emit error event + done(error)" mirroring the existing in-stream-error pattern. The four-bucket matrix's APPLY bucket implicitly permits refinement, but the SKILL should make it explicit: APPLY may include refinements beyond the literal proposal text, with the refinement captured as a Decision-Beyond-Triage in the closeout.
+
+---
+
+## B16. Project-level BACKLOG.md template + GUIDE.md project-vs-framework-level clarification
+
+**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first-run-of-SKILL friction)
+
+**Why deferred:** The SKILL says "DEFER → Add to BACKLOG.md with rationale and a back-reference," but the codex workspace had no project-level BACKLOG.md and the upstream `.codecarto/BACKLOG.md` is for framework-feedback deferrals (correctly excluded from project sync). Round-3 created `.codecarto/BACKLOG.md` from scratch with a project-scoped shape. Future projects will hit the same bootstrap gap.
+
+**Smallest viable form:**
+- Ship `templates/backlog-project.md` skeleton with header + format-per-entry note + an example entry. Format-per-entry should include: rationale, raised-by (closeout file or D-entry), preconditions (which modules / artifacts need to land before the deferral can be revisited — Δ-38 demonstrated this field's value), and "smallest viable form."
+- Add one paragraph to `GUIDE.md` clarifying the project-level vs framework-level distinction: framework `.codecarto/BACKLOG.md` is for framework-feedback deferrals (raised by agents about CodeCartographer itself); project `.codecarto/BACKLOG.md` is for project-decision deferrals (raised during the project's own work).
+- SKILL Step 7 (DEFER bucket) explicitly references the project template.
+
+---
+
+## B17. SKILL clarification — DECISIONS.md vs BACKLOG.md semantics for DEFER
+
+**Raised by:** `Spec-delta-3 application - 2026-05-03.txt` (1 agent — first-run-of-SKILL semantic ambiguity)
+
+**Why deferred:** The SKILL's DEFER guidance and its "append numbered entries to DECISIONS.md for any decisions made during triage that weren't already in the deltas" instruction left ambiguous whether DEFER-with-rationale belongs in DECISIONS.md or BACKLOG.md. Round-3 chose: DECISIONS.md is for things the project decided to **DO** (including refinements made during application — e.g., D501's refinement); BACKLOG.md is for things the project decided to **DEFER**. DEFERs do not get a D5xx number, and DECISIONS.md's "pending spec deltas" subsection only tracks proposed → applied lifecycle.
+
+**Smallest viable form:** A two-sentence clarification in SKILL Step 7's DEFER bucket: DEFER → BACKLOG.md (no D-number); refinements made during APPLY → DECISIONS.md "Decisions Beyond Triage" section in the audit file, lifted to DECISIONS.md only if cross-cutting. Existing D-entries for proposed deltas get their disposition updated in place (e.g., "APPLIED 2026-05-03 round-3"); they do not get superseded by new D-entries when applied.
+
+---
+
+## How to use this backlog
+
+A future framework-feedback pass picks items up from here. Each item has a "Smallest viable
+form" line so the pass doesn't have to re-design from scratch — the design work was done in this
+pass; the next pass executes.
+
+Add new entries below as agents raise items in future feedback files. When promoting an item to
+"applied," remove the entry from this file and document in the relevant CHANGELOG.

package/.codecarto/CHANGELOG-2026-05-02-feedback-pass.md

@@ -0,0 +1,118 @@
+# Changelog — 2026-05-02 Framework Feedback Pass
+
+Audit of which proposals from the agent feedback corpus (`Feedback From Agents/`) were applied,
+clarified, deferred, or rejected in this pass. Same format as Thaumaturge's `DELTAS-APPLIED.md`
+audit. Future revision passes read this file to know which proposals have already been
+processed.
+
+## Sources
+
+| Source | Notes |
+|---|---|
+| `Feedback From Agents/FEEDBACK_INDEX.md` | Cross-cutting themes table is the load-bearing input. |
+| `Feedback From Agents/Agent coordinating results - coordinating.txt` | Most synthesized single feedback file. |
+| `Feedback From Agents/Agent on fifth module work - thaum-state.txt` | Most recent and most detailed module-work feedback. |
+| `Feedback From Agents/Apply 20 spec deltas to Thaumaturge.txt` | Names the missing spec-delta-application skill explicitly. |
+| (Plus the 9 other feedback files indexed in FEEDBACK_INDEX.md.) | Read at index level; specific items pulled when needed. |
+
+## Triage Discipline Applied
+
+Same discipline as `spec-delta-application`:
+
+- **APPLY** = spec-blocker (raised by 3+ agents AND clean concrete edit) OR explicitly user-mandated.
+- **CLARIFY** = mechanical edit; meaning is right but wording or shape is missing.
+- **DEFER** = real improvement, not load-bearing for next session, written into `BACKLOG.md`.
+- **REJECT** = wrong on close reading or out of scope for the framework.
+
+## Triage Summary
+
+| Bucket | Count | Notes |
+|---|---|---|
+| APPLY | 6 | Spec-blockers — see Applied table below. |
+| CLARIFY | 5 | Mechanical edits — see Clarifications table. |
+| DEFER | 14 | Recorded in BACKLOG.md (B1–B14). |
+| REJECT | 0 | (Nothing rejected; deferred items are deferred, not rejected.) |
+| **Total** | 25 | |
+
+---
+
+## Applied (spec-blockers)
+
+| # | Proposal | Source(s) | Edit |
+|---|---|---|---|
+| 1 | **Schema-split `open_questions` into `open_questions` + `carry_forward`** with structured shape `{id, kind, target_phase, deferred_reason}`. | coordinating, broad defect, deep defect, porting (4 agents) | `workflow/status.yaml` schema updated; `workflow/VALIDATE.md` references both lists; `templates/architecture-map.md`, `behavioral-contracts.md`, `protocols-and-state.md`, `reverse-engineering-bundle.md`, `reimplementation-spec.md` all gained Carry-Forward section; GUIDE.md gained "Open Questions vs Carry-Forward" subsection; `kind` enum specified (`needs-runtime-test`, `needs-maintainer-decision`, `needs-spec-ruling`, `defer-to-phase`, `needs-fixture-capture`). |
+| 2 | **`CONVENTIONS.md` and `DECISIONS.md` as first-class framework artifacts.** | thaum-engine, thaum-state, thaum-ollama (3 agents) | Created `templates/conventions-template.md` and `templates/decisions-template.md` as project-level skeletons; GUIDE.md trust-boundaries table updated to include both as "orchestrator-maintained"; GUIDE.md gained "Orchestrator-Maintained Artifacts" subsection; closeout ritual now mentions proposing entries to both. |
+| 3 | **Subagent-delegation paragraph** under Context Budget for codebases over ~50 source files. | coordinating, broad defect, contracts, protocols, deep defect (5 agents) | GUIDE.md "Context Budget" gained "Subagent Delegation for Large Codebases" subsection. |
+| 4 | **Per-session closeouts pattern** (`closeouts/<date>-<phase>.md`) replacing monolithic THREAD_LOG.md body. | thaum-ollama, thaum-engine, thaum-state, coordinating, spikes, porting (6 agents — top theme) | Created `templates/closeout-template.md`; rewrote `THREAD_LOG.md` as one-line-pointer index; updated `templates/thread-log-entry-template.md` to be the legacy one-line index entry; GUIDE.md Session Update Protocol and Output Placement Rules updated; folder layout in GUIDE.md updated. |
+| 5 | **`spec-delta-application` SKILL** for the apply-deltas pattern (codifying the discipline used for the Thaumaturge 20-delta pass). | deltas (1 agent — user-mandated) | Created `skills/spec-delta-application/SKILL.md` and `templates/deltas-applied.md`. Skill location is a new top-level `skills/` directory (sibling of `findings/`) — chosen because spec-delta-application is post-pipeline, not phase-bound, so it doesn't fit `findings/<phase>/SKILL.md`. GUIDE.md trust-boundaries table updated with `skills/*/SKILL.md`. |
+| 6 | **Dual-mode reimpl-spec template** — opinionated variant when stack/identity are pre-locked. | reimpl-spec, coordinating (2 agents) | Created `templates/reimplementation-spec-opinionated.md` as sibling of the language-agnostic default; GUIDE.md Session Update Protocol gained "Strategic Alignment Hook" subsection that picks between the two. |
+
+## Clarifications (mechanical)
+
+| # | Proposal | Source(s) | Edit |
+|---|---|---|---|
+| 7 | **Strategic-alignment hook** before reimplementation-spec phase. | coordinating (1 agent) | Folded into spec-blocker #6 — the Strategic Alignment Hook subsection in GUIDE.md is the hook *and* selects the template variant. |
+| 8 | **Primary vs secondary output relationship** documentation in GUIDE.md (two-paragraph rule). | coordinating, porting (2 agents) | GUIDE.md gained "Primary vs Secondary Output Relationship" subsection under Evaluation Objective. |
+| 9 | **File-system-sync warning paragraph** in session-prompt boilerplate. | thaum-engine, thaum-state (2 agents) | NEW_THREAD_BLURB.md gained "File-System Sync Warning" section with concrete mitigations. |
+| 10 | **THREAD_LOG dedup linter** as a one-line script in the framework. | deltas (1 agent) | CONTRIBUTING.md gained "THREAD_LOG.md de-dup check" with the `grep ... | sort | uniq -d` one-liner. THREAD_LOG.md itself documents the human-discipline rule. |
+| 11 | **VALIDATE.md PARTIAL example.** | deep defect (1 agent) | VALIDATE.md gained "Worked PARTIAL Example" section with a full PASS-WITH-GAPS validation block AND the matching `carry_forward` entry showing how the gap is routed downstream. |
+
+## Deferred (in BACKLOG.md)
+
+| # | Proposal | Source(s) | Backlog ID |
+|---|---|---|---|
+| 12 | Spike template + first-class spike concept | spikes, deltas, protocols (3) | B1 |
+| 13 | Amendments mechanic (`findings/amendments/`) | spikes, protocols (2) | B2 |
+| 14 | Cross-CodeCartographer references in status.yaml | reimpl-spec (1) | B3 |
+| 15 | 1–5 coverage-depth score | reimpl-spec (1) | B4 |
+| 16 | Programmatic markdown-regex validator | broad defect, deep defect (2) | B5 |
+| 17 | CI grep gate for tripwire-named functions | thaum-state (1, project-level) | B6 |
+| 18 | Append-mode supersession rule | porting, protocols, contracts (3) | B7 |
+| 19 | Validation as semantic check (not just structural) | broad defect, deep defect, porting, protocols (4) | B8 |
+| 20 | Spec file split into spec/ directory | thaum-engine, thaum-ollama, spikes (3, project-level) | B9 |
+| 21 | SKILL.md + template consolidation | porting, protocols, contracts (3) | B10 |
+| 22 | Defect-pass-N append discipline | broad defect, deep defect (2) | B11 |
+| 23 | Resolutions footer / phase resolution mechanic | coordinating, contracts (2) | B12 (partially obviated by carry_forward — wait for re-feedback) |
+| 24 | Engine→leaf seam contracts table | thaum-state (1, project-level) | B13 |
+| 25 | Cross-phase consistency check | protocols (1) | B14 |
+
+## What This Pass Did Not Touch
+
+Per the prompt's "do not modify" list (the unanimous-defenders list at the bottom of
+`FEEDBACK_INDEX.md`):
+
+- **Validation gate** (PASS / PASS WITH GAPS / FAIL) — UNCHANGED. (Rules around it were extended; the gate's shape is preserved.)
+- **Append-mode discipline** for secondary outputs — UNCHANGED.
+- **Trust-boundaries table** — EXTENDED with new categories (closeouts, conventions, decisions, backlog), not modified in shape.
+- **Pipeline variants** (5) — UNCHANGED. None added, none removed, none restructured.
+- **Evidence-level discipline** (`observed fact` / `strong inference` / `portability hazard` / `open question`) — UNCHANGED.
+- **Closeout ritual** — EXTENDED to include conventions/decisions promotion and per-session closeout files; the ritual's shape (validation → status.yaml → per-session record → next pointer) is preserved.
+- **status.yaml-as-handoff-baton** — UNCHANGED in role; schema split adds `carry_forward` alongside existing fields.
+
+## Re-Validation Result
+
+The framework's own `.codecarto/` is the framework applied to itself. After this pass:
+
+- Every file path referenced in GUIDE.md, CONTRIBUTING.md, NEW_THREAD_BLURB.md, VALIDATE.md, and the pipeline YAMLs still exists.
+- Every template file referenced in pipeline YAMLs (`templates/architecture-map.md`, etc.) still exists and is well-formed.
+- New files (`templates/closeout-template.md`, `templates/conventions-template.md`, `templates/decisions-template.md`, `templates/deltas-applied.md`, `templates/reimplementation-spec-opinionated.md`, `skills/spec-delta-application/SKILL.md`, `BACKLOG.md`, this CHANGELOG, the rewritten `THREAD_LOG.md`) are all present.
+- `workflow/status.yaml` schema split is consistent with the templates and GUIDE.md.
+- `Feedback From Agents/FEEDBACK_INDEX.md` cross-cutting-themes table has been annotated with resolution markers (✓ APPLIED / ◑ CLARIFIED / ➜ DEFERRED-Bxx).
+
+The pass is internally consistent. The framework's own self-application still hangs together.
+
+## Net
+
+- 6 spec-blockers landed.
+- 5 spec-clarifications applied (one folded into a blocker; 4 standalone mechanical edits).
+- 14 nice-to-haves recorded in BACKLOG.md with smallest-viable-form sketches.
+- 0 rejections.
+
+The framework now formalizes the orchestrator role (CONVENTIONS.md + DECISIONS.md +
+spec-delta-application skill), formalizes the schema split that has been requested since session
+1 (open_questions vs carry_forward), and replaces the monolithic THREAD_LOG body with a
+per-session closeouts pattern that scales forever.
+
+The next concrete step after this pass is back to project-level work (e.g., Thaumaturge module
+work — `thaum-tools`) — but now with the upgraded framework as the base and the
+orchestrator-discipline artifacts as first-class supporting structure.

package/.codecarto/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to CodeCartographer
+
+Thanks for your interest in improving CodeCartographer.
+
+## How to Contribute
+
+### Reporting Issues
+
+Open a GitHub issue for bugs, unclear instructions, or missing coverage. Include which phase or file is affected and what you expected to happen.
+
+### Proposing Changes
+
+1. Fork the repository.
+2. Create a feature branch from `main`.
+3. Make your changes.
+4. Test by running the template against a real codebase (see below).
+5. Open a pull request with a clear description of what changed and why.
+
+### Testing Your Changes
+
+CodeCartographer is a pure template — there is no test suite to run. Instead, validate changes by pointing an LLM at `GUIDE.md` with a source repo as the parent directory and confirming that the workflow still produces correct, well-structured output.
+
+Key things to verify:
+
+- Pipeline YAML files parse correctly and phase dependencies resolve.
+- SKILL.md instructions produce output that matches the corresponding template.
+- Validation protocol (VALIDATE.md) catches missing or incomplete sections.
+- `status.yaml` updates correctly after each phase, with the schema-split `open_questions` / `carry_forward` lists used for what each is for (see GUIDE.md "Open Questions vs Carry-Forward").
+- All file paths referenced in pipeline YAML, GUIDE.md, and SKILL.md files exist.
+
+#### THREAD_LOG.md de-dup check
+
+`THREAD_LOG.md` is an append-only index of one-line pointers to closeout files. The framework has no programmatic dedup gate, but earlier sessions have produced duplicate entries when an append happened twice. Run this before opening a PR that touches `THREAD_LOG.md`:
+
+```bash
+grep -E '^- [0-9]{4}-[0-9]{2}-[0-9]{2}' .codecarto/THREAD_LOG.md | sort | uniq -d
+```
+
+The command should print nothing. If it prints a duplicate line, find and remove the second occurrence.
+
+### What Makes a Good Contribution
+
+- **SKILL.md improvements**: better analysis instructions, additional patterns to check for, clearer evidence-level guidance.
+- **Template refinements**: sections that are consistently empty or redundant, missing sections that LLMs frequently need.
+- **Pipeline variants**: new scope configurations for specific use cases.
+- **Documentation**: clearer setup instructions, better examples, FAQ entries.
+
+### What to Avoid
+
+- Adding runtime dependencies, CLIs, or build steps. CodeCartographer is a pure template.
+- Changing the folder structure without updating all references (pipeline YAML, GUIDE.md, SKILL.md files, templates).
+- Adding LLM-specific instructions that only work with one model or provider.
+
+## Code of Conduct
+
+Be respectful and constructive. We're all here to make reverse-engineering codebases easier.