work-package: migrate codebase-comprehension to reusable codebase-wiki techniques (wiki = pure knowledge, planning = task/process meta)

[m2ux]

Summary

Migrate the work-package workflow's Codebase Comprehension stage off its bespoke .engineering/artifacts/comprehension/{area}.md artifact and onto the reusable codebase-wiki techniques (codebase-wiki/<op>), added in #146.

The migration must split the current comprehension output:

• Pure, durable codebase knowledge → the wiki (citation-backed, confidence-tagged).
• Trigger-task / process metadata (open questions, work-package provenance, the running history of how the knowledge was obtained, and the analytical lenses applied to obtain it) → stays localised to the work package's planning folder, excluded from the wiki.

The wiki is a knowledge base, not a lab notebook: it should read as what is true about the codebase, not how this work package came to understand it.

Hard requirement — no functional regression

The comprehension stage today delivers concrete functional value (see 14-codebase-comprehension.yaml outcome[] and resources/codebase-comprehension.md). The migration MUST preserve all of it. In particular:

1. Durable, cumulative, reusable knowledge base. Comprehension already aims to be "cumulative knowledge, not disposable planning documents" that "future work can build on without re-investigating the same area." The wiki must be at least as reusable and cumulative.
2. Depth of analysis. Architecture, key abstractions, design rationale, and especially the Data Flow & Operational Context analysis (data-flow map, invariant-alignment table, execution context, operational scenarios) must be preserved. This section is load-bearing for the "guard becomes a halt vector" failure mode described in the resource — losing it is a functional regression.
3. Question-driven comprehension loop. The deep-dive-iteration while-loop, needs_comprehension/has_open_questions variables, and the comprehension-sufficient checkpoint must continue to work. Open questions still drive area selection (question-driven-exploration) — they just live in planning, not the wiki.
4. Lens passes still run. The prism/portfolio-analysis passes (pedagogy, rejected-paths) still execute; their output is localised per the split below.
5. Downstream consumers unaffected. design-philosophy, implementation-analysis, plan-prepare, and assumptions-review must receive equivalent inputs — the durable reference (now the wiki) plus the task-meta (now planning).

The split — knowledge vs. task/process meta

Current comprehension content	Nature	Destination
Architecture Overview (project structure, module map, design patterns)	Pure knowledge	Wiki (concept/entity pages)
Key Abstractions (core types, traits, data model, error handling)	Pure knowledge	Wiki (entity pages)
Design Rationale — observation, hypothesized rationale, trade-offs	Pure knowledge	Wiki (concept/comparison pages)
Design Rationale — "Implications for changes"	Task-relative lens	Planning
Data Flow & Operational Context (flow map, invariant alignment, execution context, operational scenarios)	Pure knowledge (durable behavioural facts)	Wiki
Domain Concept Mapping (glossary, domain model)	Pure knowledge	Wiki
Deep-dive findings (traced flows, implementation detail, edge cases)	Pure knowledge (facts)	Wiki (distilled into pages)
"Open Questions" table + "Remaining follow-up (out of scope)"	Trigger-task open questions	Planning
Metadata header "Work packages: [contributing WP list]"	WP-specific provenance	Planning
Dated per-WP deep-dive section wrappers, "Last updated", "augmented across successive work packages" narrative	Running history of how it got there	Planning (generic op history already goes in the wiki log.md; the WP-narrative stays planning)
Applied prism-lens output (pedagogy, rejected-paths)	Lenses applied to obtain understanding	Planning — but a durable fact surfaced by a lens (e.g. a genuinely rejected design alternative) may be distilled into a wiki page; the pedagogical/process framing stays in planning

Guiding principle: if a reader coming fresh to the codebase (with no knowledge of this work package) would want the content, it belongs in the wiki. If it only makes sense in the context of this task's investigation, it belongs in planning.

Wiki-side notes

• Every claim promoted to the wiki must carry a raw/ citation and a confidence score, per the codebase-wiki page format. This is stricter than today's comprehension artifact — an improvement, not a regression, but the migration must actually populate citations rather than dropping content that lacks them.
• The augment-from-task flow is folded into codebase-wiki/ingest (task knowledge as an additional input source). The comprehension stage should bind ingest (source + task knowledge), then maintain-index-log, cross-link, and lint — reusing the wiki ops rather than re-implementing artifact writes.

Acceptance criteria

• The comprehension stage binds codebase-wiki/<op> techniques; it no longer writes the monolithic .engineering/artifacts/comprehension/{area}.md.
• The wiki receives only pure knowledge (architecture, abstractions, rationale-minus-implications, data-flow/operational-context, domain, distilled deep-dive facts), each claim citing raw/ with a confidence score.
• Open questions, WP provenance, task-relative "implications for changes", the per-WP investigation history, and raw applied-lens output are written to a planning artifact — not the wiki.
• The deep-dive-iteration loop and comprehension-sufficient checkpoint still function, driven by the planning-resident open questions.
• The Data Flow & Operational Context analysis (invariant alignment, execution context, operational scenarios) is preserved as wiki knowledge — the halt-vector-prevention capability is intact.
• Every declared outcome[] of the current codebase-comprehension activity still holds after migration.
• Downstream activities receive equivalent inputs (wiki reference + planning task-meta).

Open design questions

1. Planning home for task-meta. Where does the planning-resident comprehension meta live (e.g. .engineering/artifacts/planning/<wp>/comprehension-notes.md holding open questions, implications, the investigation log, and lens output)?
2. Lens output routing. Do pedagogy/rejected-paths passes stay in the comprehension stage feeding planning, and what (if anything) is distilled into wiki comparison/concept pages?
3. Task-knowledge citations. How does ingest-from-task attach raw/ citations + confidence to task-derived claims?
4. Back-compat. What happens to existing .engineering/artifacts/comprehension/*.md artifacts — migrate, deprecate in place, or leave for manual port?
5. Activity shape. Does comprehension stay optional (required: false) with unchanged transitions, or does binding the wiki ops change the activity graph?

References

• codebase-wiki workflow + reusable techniques: feat(codebase-wiki): add codebase-wiki workflow #146
• Current comprehension activity: work-package/activities/14-codebase-comprehension.yaml
• Comprehension techniques: work-package/techniques/codebase-comprehension/ (survey, deep-dive, revise-questions)
• Output format + methodology: work-package/resources/codebase-comprehension.md

Filed on behalf of @m2ux by the workflow-design agent, following the codebase-wiki workflow delivery (#146) and its compliance review.