Comprehension split: the shared corpus keeps the facts, the planning folder keeps the working

work-package/activities/15-codebase-comprehension.yaml

@@ -1,5 +1,5 @@
 id: codebase-comprehension
-version: 1.10.0
+version: 1.11.0
 name: Codebase Comprehension
 description: Build or augment a mental model of the codebase.
 required: false
@@ -33,10 +33,17 @@ steps:
     technique:
       name: manage-artifacts::write-artifact
       inputs:
+        artifact_content: comprehension_artifact
         target_dir: comprehension_dir
   - kind: technique
     id: revise-initial-questions
     technique: revise-questions
+  - kind: technique
+    id: record-log-initial
+    technique:
+      name: manage-artifacts::write-artifact
+      inputs:
+        artifact_content: comprehension_log
   - kind: loop
     id: deep-dive-iteration
     name: Deep-Dive Iteration
@@ -63,7 +70,14 @@ steps:
         technique:
           name: manage-artifacts::write-artifact
           inputs:
+            artifact_content: comprehension_artifact
             target_dir: comprehension_dir
+      - kind: technique
+        id: record-log
+        technique:
+          name: manage-artifacts::write-artifact
+          inputs:
+            artifact_content: comprehension_log
       - kind: checkpoint
         id: comprehension-sufficient
         condition:
@@ -126,4 +140,5 @@ outcome:
   - Key abstractions and design rationale documented
   - Domain concepts mapped to technical constructs
   - A reusable comprehension reference lands in the cumulative corpus, where the next work package on the same area reads it instead of re-investigating
+  - The questions, investigations and follow-ups behind that reference stay in the session's planning folder as a comprehension log
   - Open questions converged via analyse-challenge before the soft sufficiency gate

work-package/activities/README.md

@@ -79,7 +79,7 @@ graph TD
 
 ### Codebase Comprehension (optional)
 
-Builds or augments a durable mental model of the codebase sufficient to qualify the design assumptions raised in later activities. Produces persistent knowledge artifacts under `.engineering/artifacts/comprehension/` that grow across successive work packages. Runs after design-philosophy and routes to elicitation, research, analysis, or plan-prepare depending on the chosen path.
+Builds or augments a durable mental model of the codebase sufficient to qualify the design assumptions raised in later activities. Produces persistent knowledge artifacts under `.engineering/artifacts/comprehension/` that grow across successive work packages, and a session-local log of the questions and investigations behind them. Runs after design-philosophy and routes to elicitation, research, analysis, or plan-prepare depending on the chosen path.
 
 Definition: [`15-codebase-comprehension.yaml`](./15-codebase-comprehension.yaml)
 

work-package/resources/README.md

@@ -34,7 +34,7 @@ Markdown resources for planning-folder templates, elicitation and review guidanc
 | `follow-ups` | Follow-ups | In-task follow-ups register template (distinct from out-of-scope `deferred-items`) |
 | `tdd-concepts-rust` | TDD Concepts Rust | TDD best practices for Rust: Red-Green-Refactor, FIRST principles |
 | `review-mode` | Review Mode | Complete guide for review mode behavior and PR review formats |
-| `codebase-comprehension` | Codebase Comprehension | Comprehension techniques, artifact template, and deep-dive guidance from reverse engineering and code forensics literature |
+| `codebase-comprehension` | Codebase Comprehension | Comprehension techniques, corpus and log artifact templates, promotion criteria, and deep-dive guidance from reverse engineering and code forensics literature |
 | `assumption-reconciliation` | Assumption Reconciliation | Assumptions-log integration and scorecard formats |
 | `research-reconciliation` | Research Reconciliation | Research-candidate inventory shape, reconcilability statuses, and scorecard format |
 | `pr-review-response` | PR Review Response | Response-format and review-document templates |
@@ -66,7 +66,8 @@ Which guide owns each persisted filename's shape.
 | `architecture-summary.md` | [architecture-summary](architecture-summary.md) |
 | `strategic-review-{n}.md` | [strategic-review](strategic-review.md) |
 | `strategic-review-{n}-method.md` | [strategic-review](strategic-review.md#method-record-template) |
-| `{codebase_area}.md` | [codebase-comprehension](codebase-comprehension.md) |
+| `{codebase_area}.md` | [codebase-comprehension](codebase-comprehension.md#corpus-artifact-template) |
+| `codebase-comprehension.md` | [codebase-comprehension](codebase-comprehension.md#comprehension-log-template) |
 | `{YYYY-MM-DD}-pr{pr_number}-review-analysis.md` | [pr-review-response](pr-review-response.md) |
 | `kb-research.md` | [knowledge-base-research](knowledge-base-research.md) |
 | `design-philosophy.md` | [design-framework](design-framework.md) |

work-package/resources/codebase-comprehension.md

@@ -1,16 +1,16 @@
 ---
 name: codebase-comprehension
-description: Comprehension techniques, artifact template, and deep-dive guidance from reverse engineering and code forensics literature.
+description: Comprehension techniques, corpus and log artifact templates, promotion criteria, and deep-dive guidance from reverse engineering and code forensics literature.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
   order: 25
   legacy_id: 25
 ---
 
 
 # Codebase Comprehension Guide
 
-Systematically build a mental model of an unfamiliar codebase before design decisions are made. Artifacts persist in the comprehension corpus, outside any one session's planning folder, and are augmented across successive work packages into a cumulative knowledge base.
+Systematically build a mental model of an unfamiliar codebase before design decisions are made. Comprehension produces a cumulative corpus artifact and a session-local log, each with its own template below.
 
 Knowledge-base sources for concept lookups: *Object-Oriented Reengineering Patterns* (Demeyer, Ducasse, Nierstrasz — first contact, reverse engineering lifecycle), *Your Code as a Crime Scene* (Tornhill — hotspots, temporal coupling, knowledge maps), *Software Design X-Rays* (Tornhill — behavioral analysis, complexity trends, change coupling), *Code Reading* (Spinellis — reading strategies, software archaeology, build analysis), *Working Effectively with Legacy Code* (Feathers — seams, characterization tests, dependency breaking).
 
@@ -51,7 +51,7 @@ Use these to decide where to focus comprehension effort:
 
 ### 5. Hypothesis-Driven Top-Down Comprehension
 
-Form an initial architecture hypothesis from directory layout and build configuration; verify by sampling entry points, module roots, public APIs; revise as evidence accumulates; document verified understanding and open questions.
+Form an initial architecture hypothesis from directory layout and build configuration; verify by sampling entry points, module roots, public APIs; revise as evidence accumulates. Verified understanding lands in the corpus artifact; the hypothesis that produced it, and any question it leaves open, stay in the log.
 
 ### 6. Hierarchical Decomposition
 
@@ -94,6 +94,7 @@ Lexicon for the code path under study:
 
 - **Execution context**: dispatch class, thread model, execution priority. In Substrate, a `Mandatory` dispatch returning an error rejects the block; in a consensus system where all nodes process the same inputs, that halts the network. Execution context determines whether an error is a local retry, a skipped item, or a system-wide halt.
 - **Error propagation**: what happens on error — caught and handled? Rolled back at a transaction boundary? Surfaced to the user? Halts processing? For inherent extrinsics, `IsFatalError` — if all variants return `true`, every error is fatal.
+- **Resource bounds**: what caps the work an untrusted or unlucky input can induce — declared constants, cache capacities, per-identity budgets — and what each one actually limits, which is often narrower than its name suggests.
 - **Operational scenarios** beyond the steady-state happy path:
   - **Startup and genesis**: initial values; a guard assuming "previous value is meaningful" may fail on the first block after genesis when the previous value is zero/default.
   - **Recovery after downtime**: if external state advanced significantly while offline, a bounded-advance guard may reject the catch-up jump.
@@ -103,97 +104,252 @@ Lexicon for the code path under study:
 
 These concerns belong in the architecture survey and deep dives, not as a separate end step: key abstractions raise "where does this data come from?"; rationale raises "what happens if this fails?"; domain mapping raises "what is the timing relationship with dependencies?". Open Questions of this kind ("Does the producer enforce the window bound?", "What happens at genesis when the previous position is zero?") prevent guards from becoming halt vectors.
 
-## Artifact Template
+## Corpus Artifact Template
 
-Comprehension artifacts follow this structure. When augmenting an existing artifact, add new sections or deepen existing ones — do not replace prior content.
+The durable artifact. It states what is true of the codebase area, in the present tense, for a reader who has neither the session nor the code open. Its top-level split is structure (what exists) against behaviour (what happens when it runs).
 
 ```markdown
-# {Codebase Area Name} — Comprehension Artifact
+# {Codebase Area Name} — Comprehension
 
-> YYYY-MM-DD · work packages: [contributing refs] · coverage: [what this artifact covers] · related: [cross-refs to other comprehension artifacts; omit if none]
+[One sentence naming what this area does.]
 
-## Architecture Overview
+## Structure
 
-### Project Structure
-[Directory layout, build system, entry points]
+[What exists and how it is arranged. Nothing here says what happens at run time.]
+
+### Overview
+
+[The dependency shape in a sentence or two, then a diagram of it.]
+
+### Project
+
+[Where the code lives and how a running system reaches it.]
+
+#### {Build units}
+[Table: unit, path, role in this area]
+
+#### Entry points
+[The path from process start to this area, then a diagram of that call chain.]
 
 ### Module Map
-[Modules, responsibilities, dependency relationships]
+
+[Table: module, responsibility, depends on]
 
 ### Design Patterns
-[Overarching architectural patterns observed: layered, event-driven, etc.]
 
-## Key Abstractions
+[The structural shapes this arrangement repeats — what is kept apart from what, and what wraps what.]
+
+#### {Pattern name}
+[What the shape is, and where it shows up.]
 
 ### Core Types
-[Primary types/structs/classes and their roles]
+
+[The types a reader meets first, and how they group.]
+
+| Type | Role |
+|------|------|
+| [type] | [what it is for, in prose] |
 
 ### Traits and Interfaces
-[Key traits/interfaces, purposes, implementors]
 
-### Data Model
-[Core data structures, relationships, state management]
+[What this area reaches the wider system through.]
 
-### Error Handling
-[Error types, propagation strategy, recovery patterns]
+| Interface | Reached for |
+|-----------|-------------|
+| [interface] | [the capability it supplies] |
 
-## Design Rationale
+### Data Model
 
-### {Decision Area}
-- **Observation**: [What was observed]
-- **Hypothesized rationale**: [Why this choice was likely made]
-- **Trade-offs**: [What this optimizes for vs. sacrifices]
-- **Implications for changes**: [How this affects modifications]
+[The values the design turns on.]
 
-[Repeat per significant design choice]
+#### {Data shape}
+[One subsection per distinct payload, store, or encoding.]
 
-## Data Flow and Operational Context
+## Behaviour
+
+[What the code does once it is running.]
 
 ### Data Flow Map
-[Per function the work package modifies: producer → transformations → consumer; which module produces the input, what invariants the producer guarantees]
+
+[Where trust or authority enters, then a diagram of that at concept level.]
+
+#### {Path name}
+[One subsection per producer→consumer route, each with its own diagram and its own prose.]
+
+### Design Patterns
+
+[The runtime shapes — what the area withholds, and how it selects a path from data.]
+
+#### {Pattern name}
+[What the shape is, and when it governs.]
 
 ### Invariant Alignment
-| Invariant | Producer Enforces? | Consumer Assumes? | Gap? |
+
+[What a producer/consumer disagreement costs in this area, and why the table below is where the safety argument is checkable.]
+
+| Invariant | Producer enforces? | Consumer assumes? | Gap? |
 |-----------|-------------------|-------------------|------|
 | [invariant] | [yes/no — cite code] | [yes/no] | [gap description if any] |
 
 ### Execution Context
-[Dispatch class, error propagation path, failure consequences]
+
+[Dispatch class, thread model, failure consequences, and what an operator can see at default verbosity.]
+
+### Error Handling
+
+[How far a failure travels.]
+
+| Error type | Consumer reaction |
+|------------|-------------------|
+| [type] | [what the caller does] |
+
+### Resource Bounds
+
+[What keeps an untrusted or unlucky input from exhausting the machine.]
+
+#### {Declared limits}
+[Table: constant, value, what it binds]
+
+#### {Enforcement}
+[The caches, budgets or gates that apply those limits, and the scope each one actually covers.]
+
+#### {Peak cost}
+[Table: site, live at peak, bounded by]
 
 ### Operational Scenarios
-| Scenario | Effect on This Code Path | Risk |
+
+[How the path behaves in situations a real deployment meets.]
+
+| Scenario | Effect on this code path | Risk |
 |----------|------------------------|------|
 | Genesis / first invocation | [what happens] | [severity] |
 | Recovery after downtime | [what happens] | [severity] |
 | External system timing mismatch | [what happens] | [severity] |
 | External chain reorganization | [what happens] | [severity] |
 
+## Inferred Design Rationale
+
+[State that rationale here is read out of the code, its comments and its structure; entries say so where the source documents a reason outright.]
+
+### {The choice, named as a decision taken}
+
+[What the code does, and the logic that makes it coherent.]
+
+[What the choice costs, and what it constrains about changing it.]
+
 ## Domain Concept Mapping
 
+[The bridge between the words people use and the constructs that implement them.]
+
 ### Glossary
-| Domain Term | Technical Construct | Description |
+
+| Domain term | Technical construct | Description |
 |-------------|-------------------|-------------|
 | [term] | [module/type/function] | [explanation] |
 
 ### Domain Model
-[How domain concepts map to code structure]
+
+[How domain concepts map to code structure.]
+
+## References
+
+[Coverage: what this artifact covers, and the revision it was read at.]
+
+| Reference | What it carries |
+|-----------|-----------------|
+| [the comprehension log] | [the questions, investigations and open items behind this artifact] |
+| [related corpus artifact] | [what that area supplies to this one] |
+
+| Contributing work package | Dates |
+|---------------------------|-------|
+| [work package] | [range] |
+```
+
+## Comprehension Log Template
+
+The session-local artifact. It holds the reasoning that produced the corpus artifact, and everything specific to this work package.
+
+```markdown
+# Codebase Comprehension — {Codebase Area Name}
+
+> [work package] · {dates} · {status} · coverage: {what was read, at which revision}
+
+[What this file is: the questions this pass asked, the investigations that answered them, and
+the items it left open. Name the corpus artifact that holds the settled facts.]
 
 ## Open Questions
 
-[Unresolved questions, including producer-guarantee and operational-scenario questions]
+[Which questions remain open, and why each carries forward as an input rather than a gap this
+pass is expected to close.]
+
+| # | Question | Status | Resolution | Deep-Dive Section |
+|---|----------|--------|------------|-------------------|
+| [n] | [question] | Open / Resolved | [one-line answer, or — while open] | [link to the section that answered it] |
 
 ## Deep-Dive Sections
 
-### {Area Name} — [YYYY-MM-DD]
-[Targeted exploration findings: data flows, implementation details, edge cases]
+### {Area Name} — {date}
+
+[Targeted exploration findings: traced data flows, implementation detail, edge cases.]
+
+## Challenge Lenses
+
+### {Perspective} — {date}
+
+[What the challenge pass surfaced from this angle.]
+
+## Follow-up items (out of scope)
+
+[Items this pass identified and deliberately left for later, each with what it would take to settle.]
 ```
 
+## Promotion
+
+The log is the working; the corpus artifact takes what survives. When a question resolves, its answer is written into the corpus section it belongs to, as a statement about the code, and the reasoning that reached it stays in the log.
+
+- **Promote** the settled outcome — a measured constant, a resolved gap in an invariant row, a correspondence confirmed against upstream source, a rationale the evidence supports.
+- **Keep local** the derivation — the question, the alternatives weighed, the trace that closed it, the challenge-lens output, and anything scoped to this work package.
+- A promoted fact reads as a property of the code, carrying no trace of the question that produced it. Where a reader needs the working, the corpus prose links to the log section that holds it.
+- Facts persist; prose does not. A later pass may merge, restate, or drop corpus wording that a new fact supersedes, so long as no fact is lost.
+
 ## Cross-Referencing
 
-- Check whether other comprehension artifacts reference the same modules or types; add cross-references in the header line.
+- Check whether other corpus artifacts cover the same modules or types; add cross-references as rows in the References section.
 - Note when understanding of one area depends on another.
-- If the work package's problem spans multiple codebase areas, create or update a separate artifact per area and note the relationship.
+- If the work package's problem spans multiple codebase areas, create or update a separate corpus artifact per area and note the relationship. One log covers the pass, however many areas it touched.
 
 ## Rules
 
-- **Line budget:** ~150 lines per area. An area needing more is two areas.
+These govern both the corpus artifact and the comprehension log.
+
+### explanatory-lead
+
+Every section and subsection opens with a paragraph saying what the reader is looking at and why it is there. A heading followed directly by a table or a list leaves the reader to infer the frame.
+
+### prose-over-symbols
+
+Paragraph prose names things in words and hyperlinks to their definition in the sentence flow. Code identifiers, expressions, field lists and enum variants live in tables, diagrams, fenced blocks and link targets — the surfaces built to carry them.
+
+### role-columns-in-prose
+
+Tables carry identifiers generally, under `prose-over-symbols`; a column describing what something is *for* is the exception and carries prose. Parameter lists, field names and variant names belong to the definition the row links to.
+
+### demonstratives-over-counts
+
+Introduce a list with a demonstrative rather than a tally — the count goes stale the moment an entry is added. Where a value matters, name the constant that holds it rather than the number it currently is.
+
+### subdivide-by-topic
+
+A section covering more than one topic splits into subsections, one per topic, each with its own lead. Subsection names carry their own meaning rather than repeating the parent's.
+
+### diagram-the-shape
+
+A section whose subject is a shape carries a diagram of it: module dependencies, the entry-point call chain, and each data-flow path. The diagram carries the shape and the prose carries the detail.
+
+### present-tense-facts
+
+The corpus artifact states what is, in the present tense. Narrative of how the code came to be this way, and comparison against what it used to do, belong to the change record.
+
+### line-budget
+
+Roughly 250 lines for a corpus artifact covering one area. An area needing materially more is two areas.