codecartographer-pi 0.15.0 → 0.17.0

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.