@libar-dev/architect 1.0.0-pre.3

package/docs-live/decisions/adr-005-codec-based-markdown-rendering.md

@@ -0,0 +1,150 @@
+# ADR-005: ADR 005 Codec Based Markdown Rendering
+
+**Purpose:** Architecture decision record for ADR 005 Codec Based Markdown Rendering
+
+---
+
+## Overview
+
+| Property | Value        |
+| -------- | ------------ |
+| Status   | accepted     |
+| Category | architecture |
+
+**Context:**
+The documentation generator needs to transform structured pattern data
+(MasterDataset) into markdown files. The initial approach used direct
+string concatenation in generator functions, mixing data selection,
+formatting logic, and output assembly in a single pass. This made
+generators hard to test, difficult to compose, and impossible to
+render the same data in different formats (e.g., full docs vs compact
+AI context).
+
+**Decision:**
+Adopt a codec architecture inspired by serialization codecs (encode/decode).
+Each document type has a codec that decodes a MasterDataset into a
+RenderableDocument — an intermediate representation of sections, headings,
+tables, paragraphs, and code blocks. A separate renderer transforms the
+RenderableDocument into markdown. This separates data selection (what to
+include) from formatting (how it looks) from serialization (markdown syntax).
+
+**Consequences:**
+
+| Type     | Impact                                                                            |
+| -------- | --------------------------------------------------------------------------------- |
+| Positive | Codecs are pure functions: dataset in, document out -- trivially testable         |
+| Positive | RenderableDocument is an inspectable IR -- tests assert on structure, not strings |
+| Positive | Composable via CompositeCodec -- reference docs assemble from child codecs        |
+| Positive | Same dataset can produce different outputs (full doc, compact doc, AI context)    |
+| Negative | Extra abstraction layer between data and output                                   |
+| Negative | RenderableDocument vocabulary must cover all needed output patterns               |
+
+**Benefits:**
+
+| Benefit                | Before (String Concat)        | After (Codec)                     |
+| ---------------------- | ----------------------------- | --------------------------------- |
+| Testability            | Assert on markdown strings    | Assert on typed section blocks    |
+| Composability          | Copy-paste between generators | CompositeCodec assembles children |
+| Format variants        | Duplicate generator logic     | Same codec, different renderer    |
+| Progressive disclosure | Manual heading management     | Heading depth auto-calculated     |
+
+## Rules
+
+### Codecs implement a decode-only contract
+
+**Invariant:** Every codec is a pure function that accepts a MasterDataset and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse.
+
+**Rationale:** Pure functions are deterministic and trivially testable. For the same MasterDataset, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions.
+
+**Codec call signature:**
+
+```typescript
+interface DocumentCodec {
+  decode(dataset: MasterDataset): RenderableDocument;
+}
+```
+
+**Verified by:**
+
+- Codec produces deterministic output
+- Codec has no side effects
+
+### RenderableDocument is a typed intermediate representation
+
+**Invariant:** RenderableDocument contains a title, an ordered array of SectionBlock elements, and an optional record of additional files. Each SectionBlock is a discriminated union: heading, paragraph, table, code, list, separator, or metaRow. The renderer consumes this IR without needing to know which codec produced it.
+
+**Rationale:** A typed IR decouples codecs from rendering. Codecs express intent ("this is a table with these rows") and the renderer handles syntax ("pipe-delimited markdown with separator row"). This means switching output format (e.g., HTML instead of markdown) requires only a new renderer, not changes to every codec.
+
+| Block Type | Purpose                       | Markdown Output             |
+| ---------- | ----------------------------- | --------------------------- |
+| heading    | Section title with depth      | ## Title (depth-adjusted)   |
+| paragraph  | Prose text                    | Plain text with blank lines |
+| table      | Structured data               | Pipe-delimited table        |
+| code       | Code sample with language     | Fenced code block           |
+| list       | Ordered or unordered items    | - item or 1. item           |
+| separator  | Visual break between sections | ---                         |
+| metaRow    | Key-value metadata            | **Key:** Value              |
+
+**Section block types:**
+
+**Verified by:**
+
+- All block types render to markdown
+- Unknown block type is rejected
+
+### CompositeCodec assembles documents from child codecs
+
+**Invariant:** CompositeCodec accepts an array of child codecs and produces a single RenderableDocument by concatenating their sections. Child codec order determines section order in the output. Separators are inserted between children by default.
+
+**Rationale:** Reference documents combine content from multiple domains (patterns, conventions, shapes, diagrams). Rather than building a monolithic codec that knows about all content types, CompositeCodec lets each domain own its codec and composes them declaratively.
+
+**Composition example:**
+
+```typescript
+const referenceDoc = CompositeCodec.create({
+  title: 'Architecture Reference',
+  codecs: [
+    behaviorCodec, // patterns with rules
+    conventionCodec, // decision records
+    shapeCodec, // type definitions
+    diagramCodec, // mermaid diagrams
+  ],
+});
+```
+
+**Verified by:**
+
+- Child sections appear in codec array order
+- Empty children are skipped without separators
+
+### ADR content comes from both Feature description and Rule prefixes
+
+**Invariant:** ADR structured content (Context, Decision, Consequences) can appear in two locations within a feature file. Both sources must be rendered. Silently dropping either source causes content loss.
+
+**Rationale:** Early ADRs used name prefixes like "Context - ..." and "Decision - ..." on Rule blocks to structure content. Later ADRs placed Context, Decision, and Consequences as bold-annotated prose in the Feature description, reserving Rule: blocks for invariants and design rules. Both conventions are valid. The ADR codec must handle both because the codebase contains ADRs authored in each style. The Feature description lives in pattern.directive.description. If the codec only renders Rules (via partitionRulesByPrefix), then Feature description content is silently dropped -- no error, no warning. This caused confusion across two repos where ADR content appeared in the feature file but was missing from generated docs. The fix renders pattern.directive.description in buildSingleAdrDocument between the Overview metadata table and the partitioned Rules section, using renderFeatureDescription() which walks content linearly and handles prose, tables, and DocStrings with correct interleaving.
+
+| Source              | Location                            | Example                   | Rendered Via               |
+| ------------------- | ----------------------------------- | ------------------------- | -------------------------- |
+| Rule prefix         | Rule: Context - ...                 | ADR-001 (taxonomy)        | partitionRulesByPrefix()   |
+| Feature description | **Context:** prose in Feature block | ADR-005 (codec rendering) | renderFeatureDescription() |
+
+**Verified by:**
+
+- Feature description content is rendered
+- Rule prefix content is rendered
+- Both sources combine in single ADR
+
+### The markdown renderer is codec-agnostic
+
+**Invariant:** The renderer accepts any RenderableDocument regardless of which codec produced it. Rendering depends only on block types, not on document origin. This enables testing codecs and renderers independently.
+
+**Rationale:** If the renderer knew about specific codecs, adding a new codec would require renderer changes. By operating purely on the SectionBlock discriminated union, the renderer is closed for modification but open for extension via new block types.
+
+**Verified by:**
+
+- Same renderer handles different codec outputs
+- Renderer and codec are tested independently
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)

package/docs-live/decisions/adr-006-single-read-model-architecture.md

@@ -0,0 +1,136 @@
+# ADR-006: ADR 006 Single Read Model Architecture
+
+**Purpose:** Architecture decision record for ADR 006 Single Read Model Architecture
+
+---
+
+## Overview
+
+| Property | Value        |
+| -------- | ------------ |
+| Status   | proposed     |
+| Category | architecture |
+
+**Context:**
+The Architect package applies event sourcing to itself: git is
+the event store, annotated source files are authoritative state, generated
+documentation is a projection. The MasterDataset is the read model —
+produced by a single-pass O(n) transformer with pre-computed views
+and a relationship index.
+
+ADR-005 established that codecs consume MasterDataset as their sole input.
+The ProcessStateAPI consumes it. But the validation layer bypasses it,
+wiring its own mini-pipeline from raw scanner/extractor output. It creates
+a lossy local type that discards relationship data, then discovers it
+lacks the information needed — requiring ad-hoc re-derivation of what
+the MasterDataset already computes.
+
+This is the same class of problem the MasterDataset was created to solve.
+Before the single-pass transformer, each generator called `.filter()`
+independently. The MasterDataset eliminated that duplication for codecs.
+This ADR extends the same principle to all consumers.
+
+**Decision:**
+The MasterDataset is the single read model for all consumers. No consumer
+re-derives pattern data from raw scanner/extractor output when that data
+is available in the MasterDataset. Validators, codecs, and query APIs
+consume the same pre-computed read model.
+
+**Consequences:**
+
+| Type     | Impact                                                                                         |
+| -------- | ---------------------------------------------------------------------------------------------- |
+| Positive | Relationship resolution happens once — no consumer re-derives implements, uses, or dependsOn   |
+| Positive | Eliminates lossy local types that discard fields from canonical ExtractedPattern               |
+| Positive | Validation rules automatically benefit from new MasterDataset views and indices                |
+| Positive | Aligns with the monorepo's own ADR-006: projections for all reads, never query aggregate state |
+| Negative | Validators that today only need stage 1-2 data will import the transformer                     |
+| Negative | MasterDataset schema changes affect more consumers                                             |
+
+## Rules
+
+### All feature consumers query the read model, not raw state
+
+**Invariant:** Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the MasterDataset. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the MasterDataset.
+
+**Rationale:** Bypassing the read model forces consumers to re-derive data that the MasterDataset already computes, creating duplicate logic and divergent behavior when the pipeline evolves.
+
+| Layer                  | May Import                       | Examples                                            |
+| ---------------------- | -------------------------------- | --------------------------------------------------- |
+| Pipeline Orchestration | scanner/, extractor/, pipeline/  | orchestrator.ts, process-api.ts pipeline setup      |
+| Feature Consumption    | MasterDataset, relationshipIndex | codecs, ProcessStateAPI, validators, query handlers |
+
+**Verified by:**
+
+- Feature consumers import from MasterDataset not from raw pipeline stages
+
+  Exception: `lint-patterns.ts` is a pure stage-1 consumer. It validates
+  annotation syntax on scanned files. No relationships
+
+- no cross-source
+  resolution. Direct scanner consumption is correct for that use case.
+
+### No lossy local types
+
+**Invariant:** Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data.
+
+**Rationale:** Lossy local types silently drop fields that later become needed, causing bugs that only surface when new MasterDataset capabilities are added and the local type lacks them.
+
+**Verified by:**
+
+- Feature consumers import from MasterDataset not from raw pipeline stages
+
+### Relationship resolution is computed once
+
+**Invariant:** Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToMasterDataset()`. No consumer re-derives these from raw pattern arrays or scanned file tags.
+
+**Rationale:** Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules.
+
+**Verified by:**
+
+- Feature consumers import from MasterDataset not from raw pipeline stages
+
+### Three named anti-patterns
+
+**Invariant:** These are recognized violations, serving as review criteria for new code and refactoring targets for existing code.
+
+**Rationale:** Without named anti-patterns, violations appear as one-off style issues rather than systematic architectural drift, making them harder to detect and communicate in code review.
+
+| Anti-Pattern            | Detection Signal                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| Parallel Pipeline       | Feature consumer imports from scanner/ or extractor/                                     |
+| Lossy Local Type        | Local interface with subset of ExtractedPattern fields + dedicated extraction function   |
+| Re-derived Relationship | Building Map or Set from pattern.implementsPatterns, uses, or dependsOn in consumer code |
+
+**Good vs Bad**
+
+```typescript
+// Good: consume the read model
+    function validateCrossSource(dataset: RuntimeMasterDataset): ValidationSummary {
+      const rel = dataset.relationshipIndex[patternName];
+      const isImplemented = rel.implementedBy.length > 0;
+    }
+
+    // Bad: re-derive from raw state (Parallel Pipeline + Re-derived Relationship)
+    function buildImplementsLookup(
+      gherkinFiles: readonly ScannedGherkinFile[],
+      tsPatterns: readonly ExtractedPattern[]
+    ): ReadonlySet<string> { ... }
+```
+
+**References**
+
+    - Monorepo ADR-006: Projections for All Reads (same principle, application domain)
+    - ADR-005: Codec-Based Markdown Rendering (established MasterDataset as codec input)
+    - Order-management ARCHITECTURE.md: CommandOrchestrator + Read Model separation
+
+**Verified by:**
+
+- Feature consumers import from MasterDataset not from raw pipeline stages
+
+  Naming them makes them visible in code review — including AI-assisted
+  sessions where the default proposal is often "add a helper function."
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)