codecartographer-pi 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
@@ -35,6 +35,14 @@
   },
   "files": [
     ".codecarto/**/*",
+    "!.codecarto/BACKLOG.md",
+    "!.codecarto/THREAD_LOG.md",
+    "!.codecarto/CONVENTIONS.md",
+    "!.codecarto/DECISIONS.md",
+    "!.codecarto/closeouts/**",
+    "!.codecarto/broadside/**",
+    ".codecarto/broadside/SKILL.md",
+    ".codecarto/broadside/config.yaml",
     "agent-skill/**/*",
     "dist/**/*",
     "assets/logo.svg",
@@ -49,6 +57,7 @@
     "prepublishOnly": "npm run build",
     "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test tests/*.test.mjs",
     "smoke": "node scripts/smoke-mcp.mjs",
+    "smoke:broadside": "node scripts/smoke-broadside.mjs",
     "demo:synthesis": "npm run build && node scripts/create-synthesis-demo.mjs"
   },
   "dependencies": {

package/.codecarto/BACKLOG.md

@@ -1,184 +0,0 @@
-# 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 — SHIPPED in smallest viable form (v0.15.0, issue #101)
-
-Landed exactly as scoped: `templates/spike-report.md` (Goal / Method / Measurements / Findings / Recommended Deltas) with the `scratch/spikes/<spike-id>/<scenario>.md` convention documented in GUIDE.md and the spec-delta-application skill. No workflow machinery; spikes stay registered as `post_pipeline` entries (`kind: spike`), their findings flow to the spec through spec-delta-application and to `status.yaml` through `codecarto_amend`. Status.yaml spike tracking remains deferred until a project demonstrates the need.
-
----
-
-## B2. Amendments mechanic — SHIPPED (v0.15.0, issue #99)
-
-Landed as `codecarto_amend` over `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`): post-pipeline open-question closures and post_pipeline backlog retirement, applied to `workflow/status.yaml` under the completion lock with an amendment closeout and THREAD_LOG entry. The narrower back-amendment question ("a later phase says a prior output is wrong") remains open — a real run handled it with a correction section in the later report plus a delta-application pass, which worked; promote that pattern only if it recurs.
-
----
-
-## 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

@@ -1,118 +0,0 @@
-# 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/closeouts/2026-05-02-framework-feedback-pass.md

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