@libar-dev/architect 1.0.0-pre.3

package/docs-live/_claude-md/architecture/architecture-codecs.md

@@ -0,0 +1,160 @@
+### Available Codecs Reference
+
+#### ValidationRulesCodec
+
+| Option                  | Type    | Default | Description                                         |
+| ----------------------- | ------- | ------- | --------------------------------------------------- |
+| includeFSMDiagram       | boolean | true    | Include FSM state diagram                           |
+| includeCLIUsage         | boolean | true    | Include CLI usage section                           |
+| includeEscapeHatches    | boolean | true    | Include escape hatches section                      |
+| includeProtectionMatrix | boolean | true    | Include protection levels matrix                    |
+| includeErrorGuide       | boolean | true    | Include error guide with rationale and alternatives |
+
+#### RoadmapDocumentCodec
+
+| Option              | Type                     | Default | Description                         |
+| ------------------- | ------------------------ | ------- | ----------------------------------- |
+| generateDetailFiles | boolean                  | true    | Create phase detail files           |
+| filterStatus        | NormalizedStatusFilter[] | []      | Filter by status                    |
+| includeProcess      | boolean                  | true    | Show quarter, effort, team metadata |
+| includeDeliverables | boolean                  | true    | List deliverables per phase         |
+| filterPhases        | number[]                 | []      | Filter to specific phases           |
+
+#### CompletedMilestonesCodec
+
+#### CurrentWorkCodec
+
+#### TaxonomyDocumentCodec
+
+| Option             | Type    | Default | Description                     |
+| ------------------ | ------- | ------- | ------------------------------- |
+| includePresets     | boolean | true    | Include preset comparison table |
+| includeFormatTypes | boolean | true    | Include format type reference   |
+| includeArchDiagram | boolean | true    | Include architecture diagram    |
+| groupByDomain      | boolean | true    | Group metadata tags by domain   |
+
+#### SessionContextCodec
+
+#### RemainingWorkCodec
+
+| Option                | Type                                           | Default | Description                   |
+| --------------------- | ---------------------------------------------- | ------- | ----------------------------- |
+| includeIncomplete     | boolean                                        | true    | Include planned items         |
+| includeBlocked        | boolean                                        | true    | Show blocked items analysis   |
+| includeNextActionable | boolean                                        | true    | Next actionable items section |
+| maxNextActionable     | number                                         | 5       | Max items in next actionable  |
+| sortBy                | "phase" \| "priority" \| "effort" \| "quarter" | "phase" | Sort order                    |
+| groupPlannedBy        | "quarter" \| "priority" \| "level" \| "none"   | "none"  | Group planned items           |
+
+#### RequirementsDocumentCodec
+
+| Option               | Type                                     | Default        | Description                      |
+| -------------------- | ---------------------------------------- | -------------- | -------------------------------- |
+| generateDetailFiles  | boolean                                  | true           | Create product area detail files |
+| groupBy              | "product-area" \| "user-role" \| "phase" | "product-area" | Primary grouping                 |
+| filterStatus         | NormalizedStatusFilter[]                 | []             | Filter by status (empty = all)   |
+| includeScenarioSteps | boolean                                  | true           | Show Given/When/Then steps       |
+| includeBusinessValue | boolean                                  | true           | Display business value metadata  |
+| includeBusinessRules | boolean                                  | true           | Show Gherkin Rule: sections      |
+
+#### ChangelogCodec
+
+| Option            | Type                   | Default | Description                       |
+| ----------------- | ---------------------- | ------- | --------------------------------- |
+| includeUnreleased | boolean                | true    | Include unreleased section        |
+| includeLinks      | boolean                | true    | Include links                     |
+| categoryMapping   | Record<string, string> | {}      | Map categories to changelog types |
+
+#### TraceabilityCodec
+
+#### OverviewCodec
+
+#### ReferenceDocumentCodec
+
+| Option             | Type            | Description                                                  |
+| ------------------ | --------------- | ------------------------------------------------------------ |
+| conventionTags     | string[]        | Convention tag values to extract from decision records       |
+| diagramScopes      | DiagramScope[]  | Multiple diagrams                                            |
+| shapeSelectors     | ShapeSelector[] | Fine-grained declaration-level shape filtering               |
+| behaviorCategories | string[]        | Category tags for behavior pattern content                   |
+| includeTags        | string[]        | Cross-cutting content routing via include tags               |
+| preamble           | SectionBlock[]  | Static editorial sections prepended before generated content |
+| productArea        | string          | Pre-filter all content sources to matching product area      |
+| excludeSourcePaths | string[]        | Exclude patterns by source path prefix                       |
+
+| Type            | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| graph (default) | Flowchart with subgraphs by archContext, custom node shapes    |
+| sequenceDiagram | Sequence diagram with typed messages between participants      |
+| stateDiagram-v2 | State diagram with transitions from dependsOn relationships    |
+| C4Context       | C4 context diagram with boundaries, systems, and relationships |
+| classDiagram    | Class diagram with archRole stereotypes and typed arrows       |
+
+| Variant        | Example                                         | Behavior                    |
+| -------------- | ----------------------------------------------- | --------------------------- |
+| group only     | `{ group: "api-types" }`                        | Match shapes by group tag   |
+| source + names | `{ source: "src/types.ts", names: ["Config"] }` | Named shapes from file      |
+| source only    | `{ source: "src/path/*.ts" }`                   | All tagged shapes from glob |
+
+#### PrChangesCodec
+
+#### PlanningChecklistCodec
+
+#### SessionPlanCodec
+
+#### SessionFindingsCodec
+
+#### PatternsDocumentCodec
+
+| Option                 | Type                                  | Default    | Description                                 |
+| ---------------------- | ------------------------------------- | ---------- | ------------------------------------------- |
+| generateDetailFiles    | boolean                               | true       | Create category detail files                |
+| detailLevel            | "summary" \| "standard" \| "detailed" | "standard" | Output verbosity                            |
+| includeDependencyGraph | boolean                               | true       | Render Mermaid dependency graph             |
+| includeUseCases        | boolean                               | true       | Show use cases section                      |
+| filterCategories       | string[]                              | []         | Filter to specific categories (empty = all) |
+
+#### IndexCodec
+
+| Option                   | Type            | Default | Description                                                      |
+| ------------------------ | --------------- | ------- | ---------------------------------------------------------------- |
+| preamble                 | SectionBlock[]  | []      | Editorial sections (reading paths, document roles, key concepts) |
+| documentEntries          | DocumentEntry[] | []      | Static document inventory entries                                |
+| includeProductAreaStats  | boolean         | true    | Product area statistics table                                    |
+| includePhaseProgress     | boolean         | true    | Phase progress summary                                           |
+| includeDocumentInventory | boolean         | true    | Unified document inventory                                       |
+| includePackageMetadata   | boolean         | true    | Package metadata header                                          |
+
+#### DesignReviewCodec
+
+#### CompositeCodec
+
+#### ClaudeModuleCodec
+
+#### BusinessRulesCodec
+
+| Option               | Type                                       | Default             | Description                               |
+| -------------------- | ------------------------------------------ | ------------------- | ----------------------------------------- |
+| groupBy              | "domain" \| "phase" \| "domain-then-phase" | "domain-then-phase" | Primary grouping strategy                 |
+| includeCodeExamples  | boolean                                    | false               | Include code examples from DocStrings     |
+| includeTables        | boolean                                    | true                | Include markdown tables from descriptions |
+| includeRationale     | boolean                                    | true                | Include rationale section per rule        |
+| filterDomains        | string[]                                   | []                  | Filter by domain categories (empty = all) |
+| filterPhases         | number[]                                   | []                  | Filter by phases (empty = all)            |
+| onlyWithInvariants   | boolean                                    | false               | Show only rules with explicit invariants  |
+| includeSource        | boolean                                    | true                | Include source feature file link          |
+| includeVerifiedBy    | boolean                                    | true                | Include Verified by scenario links        |
+| maxDescriptionLength | number                                     | 150                 | Max description length in standard mode   |
+| excludeSourcePaths   | string[]                                   | []                  | Exclude patterns by source path prefix    |
+
+#### ArchitectureDocumentCodec
+
+| Option                   | Type                     | Default     | Description                                    |
+| ------------------------ | ------------------------ | ----------- | ---------------------------------------------- |
+| diagramType              | "component" \| "layered" | "component" | Type of diagram to generate                    |
+| includeInventory         | boolean                  | true        | Include component inventory table              |
+| includeLegend            | boolean                  | true        | Include legend for arrow styles                |
+| filterContexts           | string[]                 | []          | Filter to specific contexts (empty = all)      |
+| diagramKeyComponentsOnly | boolean                  | true        | Only show components with archRole in diagrams |
+
+#### AdrDocumentCodec

package/docs-live/_claude-md/architecture/architecture-types.md

@@ -0,0 +1,32 @@
+### Architecture Types Reference
+
+#### API Types
+
+| Type                    | Kind      |
+| ----------------------- | --------- |
+| MasterDatasetSchema     | const     |
+| StatusGroupsSchema      | const     |
+| StatusCountsSchema      | const     |
+| PhaseGroupSchema        | const     |
+| SourceViewsSchema       | const     |
+| RelationshipEntrySchema | const     |
+| RuntimeMasterDataset    | interface |
+| RawDataset              | interface |
+| PipelineOptions         | interface |
+| PipelineResult          | interface |
+
+#### Orchestrator Pipeline Responsibilities
+
+**Invariant:** The orchestrator is the integration boundary for full docs generation: it delegates dataset construction to the shared pipeline, then executes codecs and writes files.
+
+#### Steps 1-8 via buildMasterDataset()
+
+#### Steps 9-10: Codec Execution and File Writing
+
+#### Shared Pipeline Factory Responsibilities
+
+**Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result<PipelineResult, PipelineError>` without process-level side effects.
+
+#### 8-Step Dataset Build Flow
+
+#### Consumer Architecture and PipelineOptions Differentiation

package/docs-live/_claude-md/architecture/reference-sample.md

@@ -0,0 +1,162 @@
+### Reference Generation Sample
+
+#### Product area canonical values
+
+**Invariant:** The product-area tag uses one of 7 canonical values. Each value represents a reader-facing documentation section, not a source module.
+
+| Value         | Reader Question                     | Covers                                          |
+| ------------- | ----------------------------------- | ----------------------------------------------- |
+| Annotation    | How do I annotate code?             | Scanning, extraction, tag parsing, dual-source  |
+| Configuration | How do I configure the tool?        | Config loading, presets, resolution             |
+| Generation    | How does code become docs?          | Codecs, generators, rendering, diagrams         |
+| Validation    | How is the workflow enforced?       | FSM, DoD, anti-patterns, process guard, lint    |
+| DataAPI       | How do I query process state?       | Process state API, stubs, context assembly, CLI |
+| CoreTypes     | What foundational types exist?      | Result monad, error factories, string utils     |
+| Process       | How does the session workflow work? | Session lifecycle, handoffs, conventions        |
+
+#### ADR category canonical values
+
+**Invariant:** The adr-category tag uses one of 4 values.
+
+| Value         | Purpose                                       |
+| ------------- | --------------------------------------------- |
+| architecture  | System structure, component design, data flow |
+| process       | Workflow, conventions, annotation rules       |
+| testing       | Test strategy, verification approach          |
+| documentation | Documentation generation, content structure   |
+
+#### FSM status values and protection levels
+
+**Invariant:** Pattern status uses exactly 4 values with defined protection levels. These are enforced by Process Guard at commit time.
+
+| Status    | Protection   | Can Add Deliverables | Allowed Actions                 |
+| --------- | ------------ | -------------------- | ------------------------------- |
+| roadmap   | None         | Yes                  | Full editing                    |
+| active    | Scope-locked | No                   | Edit existing deliverables only |
+| completed | Hard-locked  | No                   | Requires unlock-reason tag      |
+| deferred  | None         | Yes                  | Full editing                    |
+
+#### Valid FSM transitions
+
+**Invariant:** Only these transitions are valid. All others are rejected by Process Guard.
+
+| From     | To        | Trigger               |
+| -------- | --------- | --------------------- |
+| roadmap  | active    | Start work            |
+| roadmap  | deferred  | Postpone              |
+| active   | completed | All deliverables done |
+| active   | roadmap   | Blocked/regressed     |
+| deferred | roadmap   | Resume planning       |
+
+#### Tag format types
+
+**Invariant:** Every tag has one of 6 format types that determines how its value is parsed.
+
+| Format       | Parsing                        | Example                       |
+| ------------ | ------------------------------ | ----------------------------- |
+| flag         | Boolean presence, no value     | @architect-core               |
+| value        | Simple string                  | @architect-pattern MyPattern  |
+| enum         | Constrained to predefined list | @architect-status completed   |
+| csv          | Comma-separated values         | @architect-uses A, B, C       |
+| number       | Numeric value                  | @architect-phase 15           |
+| quoted-value | Preserves spaces               | @architect-brief:'Multi word' |
+
+#### Source ownership
+
+**Invariant:** Relationship tags have defined ownership by source type. Anti-pattern detection enforces these boundaries.
+
+| Tag        | Correct Source | Wrong Source  | Rationale                          |
+| ---------- | -------------- | ------------- | ---------------------------------- |
+| uses       | TypeScript     | Feature files | TS owns runtime dependencies       |
+| depends-on | Feature files  | TypeScript    | Gherkin owns planning dependencies |
+| quarter    | Feature files  | TypeScript    | Gherkin owns timeline metadata     |
+| team       | Feature files  | TypeScript    | Gherkin owns ownership metadata    |
+
+#### Quarter format convention
+
+**Invariant:** The quarter tag uses `YYYY-QN` format (e.g., `2026-Q1`). ISO-year-first sorting works lexicographically.
+
+#### Canonical phase definitions (6-phase USDP standard)
+
+**Invariant:** The default workflow defines exactly 6 phases in fixed order. These are the canonical phase names and ordinals used by all generated documentation.
+
+| Order | Phase         | Purpose                                        |
+| ----- | ------------- | ---------------------------------------------- |
+| 1     | Inception     | Problem framing, scope definition              |
+| 2     | Elaboration   | Design decisions, architecture exploration     |
+| 3     | Session       | Planning and design session work               |
+| 4     | Construction  | Implementation, testing, integration           |
+| 5     | Validation    | Verification, acceptance criteria confirmation |
+| 6     | Retrospective | Review, lessons learned, documentation         |
+
+#### Deliverable status canonical values
+
+**Invariant:** Deliverable status (distinct from pattern FSM status) uses exactly 6 values, enforced by Zod schema at parse time.
+
+| Value       | Meaning              |
+| ----------- | -------------------- |
+| complete    | Work is done         |
+| in-progress | Work is ongoing      |
+| pending     | Work has not started |
+| deferred    | Work postponed       |
+| superseded  | Replaced by another  |
+| n/a         | Not applicable       |
+
+#### API Types
+
+| Type                      | Kind      |
+| ------------------------- | --------- |
+| normalizeStatus           | function  |
+| DELIVERABLE_STATUS_VALUES | const     |
+| CategoryDefinition        | interface |
+| SectionBlock              | type      |
+
+#### Behavior Specifications
+
+##### ArchitectFactory
+
+##### DefineConfig
+
+##### ConfigBasedWorkflowDefinition
+
+| Rule                                                 | Description                                                                                                              |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Default workflow is built from an inline constant    | **Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without<br> file system access. It cannot fail. The... |
+| Custom workflow files still work via --workflow flag | **Invariant:** `loadWorkflowFromPath()` remains available for projects<br> that need custom workflow definitions. The... |
+| FSM validation and Process Guard are not affected    | **Invariant:** The FSM transition matrix, protection levels, and Process<br> Guard rules remain hardcoded in...          |
+| Workflow as a configurable preset field is deferred  | **Invariant:** The inline default workflow constant is the only workflow source until preset integration is...           |
+
+##### ADR005CodecBasedMarkdownRendering
+
+| Rule                                                              | Description                                                                                                           |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Codecs implement a decode-only contract                           | **Invariant:** Every codec is a pure function that accepts a MasterDataset<br> and returns a RenderableDocument....   |
+| RenderableDocument is a typed intermediate representation         | **Invariant:** RenderableDocument contains a title, an ordered array of<br> SectionBlock elements, and an optional... |
+| CompositeCodec assembles documents from child codecs              | **Invariant:** CompositeCodec accepts an array of child codecs and<br> produces a single RenderableDocument by...     |
+| ADR content comes from both Feature description and Rule prefixes | **Invariant:** ADR structured content (Context, Decision, Consequences)<br> can appear in two locations within a...   |
+| The markdown renderer is codec-agnostic                           | **Invariant:** The renderer accepts any RenderableDocument regardless of<br> which codec produced it. Rendering...    |
+
+##### ADR001TaxonomyCanonicalValues
+
+| Rule                                                | Description                                                                                                              |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Product area canonical values                       | **Invariant:** The product-area tag uses one of 7 canonical values.<br> Each value represents a reader-facing...         |
+| ADR category canonical values                       | **Invariant:** The adr-category tag uses one of 4 values.<br> **Rationale:** Unbounded category values prevent...        |
+| FSM status values and protection levels             | **Invariant:** Pattern status uses exactly 4 values with defined<br> protection levels. These are enforced by Process... |
+| Valid FSM transitions                               | **Invariant:** Only these transitions are valid. All others are<br> rejected by Process Guard.<br> **Rationale:**...     |
+| Tag format types                                    | **Invariant:** Every tag has one of 6 format types that determines<br> how its value is parsed.<br> **Rationale:**...    |
+| Source ownership                                    | **Invariant:** Relationship tags have defined ownership by source type.<br> Anti-pattern detection enforces these...     |
+| Quarter format convention                           | **Invariant:** The quarter tag uses `YYYY-QN` format (e.g., `2026-Q1`).<br> ISO-year-first sorting works...              |
+| Canonical phase definitions (6-phase USDP standard) | **Invariant:** The default workflow defines exactly 6 phases in fixed<br> order. These are the canonical phase names...  |
+| Deliverable status canonical values                 | **Invariant:** Deliverable status (distinct from pattern FSM status)<br> uses exactly 6 values, enforced by Zod...       |
+
+##### ProcessGuardTesting
+
+| Rule                                                | Description                                                                                                            |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Completed files require unlock-reason to modify     | **Invariant:** A completed spec file cannot be modified unless it carries an @architect-unlock-reason tag....          |
+| Status transitions must follow PDR-005 FSM          | **Invariant:** Status changes must follow the directed graph: roadmap->active->completed, roadmap<->deferred,...       |
+| Active specs cannot add new deliverables            | **Invariant:** A spec in active status cannot have deliverables added that were not present when it entered active.... |
+| Files outside active session scope trigger warnings | **Invariant:** Files modified outside the active session's declared scope produce a session-scope warning....          |
+| Explicitly excluded files trigger errors            | **Invariant:** Files explicitly excluded from a session cannot be modified, producing a session-excluded error....     |
+| Multiple rules validate independently               | **Invariant:** Each validation rule evaluates independently — a single file can produce violations from multiple...    |

package/docs-live/_claude-md/authoring/gherkin-authoring-guide.md

@@ -0,0 +1,245 @@
+### Gherkin Authoring Guide
+
+#### Essential Patterns
+
+##### Roadmap Spec Structure
+
+Roadmap specs define planned work with Problem/Solution descriptions and a Background deliverables table.
+
+```gherkin
+@architect
+@architect-pattern:ProcessGuardLinter
+@architect-status:roadmap
+@architect-phase:99
+Feature: Process Guard Linter
+
+  **Problem:**
+  During planning and implementation sessions, accidental modifications occur:
+  - Specs outside the intended scope get modified in bulk
+  - Completed/approved work gets inadvertently changed
+
+  **Solution:**
+  Implement a Decider-based linter that:
+  1. Derives process state from existing file annotations
+  2. Validates proposed changes against derived state
+  3. Enforces file protection levels per PDR-005
+
+  Background: Deliverables
+    Given the following deliverables:
+      | Deliverable                   | Status  | Location                           |
+      | State derivation              | Pending | src/lint/process-guard/derive.ts   |
+      | Git diff change detection     | Pending | src/lint/process-guard/detect.ts   |
+      | CLI integration               | Pending | src/cli/lint-process.ts            |
+```
+
+**Key elements:**
+
+- `@architect` -- bare opt-in marker (required)
+- `@architect-pattern:Name` -- unique identifier (required)
+- `@architect-status:roadmap` -- FSM state
+- `**Problem:**` / `**Solution:**` -- extracted by generators
+- Background deliverables table -- tracks implementation progress
+
+##### Rule Blocks for Business Constraints
+
+Use `Rule:` to group related scenarios under a business constraint.
+
+```gherkin
+Rule: Status transitions must follow PDR-005 FSM
+
+  **Invariant:** Only valid FSM transitions are allowed.
+
+  **Rationale:** The FSM enforces deliberate progression through planning, implementation, and completion.
+
+  **Verified by:** Valid transitions pass, Invalid transitions fail
+
+  @happy-path
+  Scenario Outline: Valid transitions pass validation
+    Given a file with status "<from>"
+    When the status changes to "<to>"
+    Then validation passes
+
+    Examples:
+      | from     | to        |
+      | roadmap  | active    |
+      | roadmap  | deferred  |
+      | active   | completed |
+      | deferred | roadmap   |
+```
+
+| Element            | Purpose                                 | Extracted By                                |
+| ------------------ | --------------------------------------- | ------------------------------------------- |
+| `**Invariant:**`   | Business constraint (what must be true) | Business Rules generator                    |
+| `**Rationale:**`   | Business justification (why it exists)  | Business Rules generator                    |
+| `**Verified by:**` | Comma-separated scenario names          | Multiple codecs (Business Rules, Reference) |
+
+##### Scenario Outline for Variations
+
+When the same pattern applies with different inputs, use `Scenario Outline` with an `Examples` table:
+
+```gherkin
+Scenario Outline: Protection levels by status
+  Given a file with status "<status>"
+  When checking protection level
+  Then protection is "<protection>"
+  And unlock required is "<unlock>"
+
+  Examples:
+    | status    | protection | unlock |
+    | roadmap   | none       | no     |
+    | active    | scope      | no     |
+    | completed | hard       | yes    |
+    | deferred  | none       | no     |
+```
+
+##### Executable Test Features
+
+Test features focus on behavior verification with section dividers for organization.
+
+```gherkin
+@behavior @scanner-core
+@architect-pattern:ScannerCore
+Feature: Scanner Core Integration
+
+  Background:
+    Given a scanner integration context with temp directory
+
+  @happy-path
+  Scenario: Scan files and extract directives
+    Given a file "src/auth.ts" with valid content
+    When scanning with pattern "src/**/*.ts"
+    Then the scan should succeed with 1 file
+```
+
+Section comments (`# ====`) improve readability in large feature files.
+
+#### DataTable and DocString Usage
+
+##### Background DataTable (Reference Data)
+
+Use for data that applies to all scenarios -- deliverables, definitions, etc.
+
+```gherkin
+Background: Deliverables
+  Given the following deliverables:
+    | Deliverable        | Status  | Location               | Tests |
+    | Category types     | Done    | src/types.ts           | Yes   |
+    | Validation logic   | Pending | src/validate.ts        | Yes   |
+```
+
+##### Scenario DataTable (Test Data)
+
+Use for scenario-specific test inputs.
+
+```gherkin
+Scenario: Session file defines modification scope
+  Given a session file with in-scope specs:
+    | spec                        | intent |
+    | mvp-workflow-implementation | modify |
+    | short-form-tag-migration    | review |
+  When deriving process state
+  Then "mvp-workflow-implementation" is modifiable
+```
+
+##### DocString for Code Examples
+
+Use `"""typescript` for code blocks. Essential when content contains pipes or special characters.
+
+```gherkin
+Scenario: Extract directive from TypeScript
+  Given a file with content:
+    """typescript
+    /** @architect */
+    export function authenticate() {}
+    """
+  When scanning the file
+  Then directive should have tag "@architect-core"
+```
+
+#### Tag Conventions
+
+##### Semantic Tags (Extracted by Generators)
+
+| Tag                    | Purpose                                           |
+| ---------------------- | ------------------------------------------------- |
+| `@acceptance-criteria` | Required for DoD validation of completed patterns |
+| `@happy-path`          | Primary success scenario                          |
+| `@validation`          | Input validation, constraint checks               |
+| `@business-rule`       | Business invariant verification                   |
+| `@business-failure`    | Expected business failure scenario                |
+| `@edge-case`           | Boundary conditions, unusual inputs               |
+| `@error-handling`      | Error recovery, graceful degradation              |
+
+#### Feature Description Patterns
+
+Choose headers that fit your pattern:
+
+| Structure        | Headers                                    | Best For                  |
+| ---------------- | ------------------------------------------ | ------------------------- |
+| Problem/Solution | `**Problem:**`, `**Solution:**`            | Pain point to fix         |
+| Value-First      | `**Business Value:**`, `**How It Works:**` | TDD-style, Gherkin spirit |
+| Context/Approach | `**Context:**`, `**Approach:**`            | Technical patterns        |
+
+The **Problem/Solution** pattern is the dominant style in this codebase.
+
+#### Feature File Rich Content
+
+Feature files serve dual purposes: **executable specs** and **documentation source**. Content in the Feature description section appears in generated docs.
+
+##### Code-First Principle
+
+**Prefer code stubs over DocStrings for complex examples.** Feature files should reference code, not duplicate it.
+
+| Approach                     | When to Use                                                  |
+| ---------------------------- | ------------------------------------------------------------ |
+| DocStrings (`"""typescript`) | Brief examples (5-10 lines), current/target state comparison |
+| Code stub reference          | Complex APIs, interfaces, full implementations               |
+
+Code stubs are annotated TypeScript files with `throw new Error("not yet implemented")`, located in `architect/stubs/{pattern-name}/`.
+
+##### Valid Rich Content
+
+| Content Type  | Syntax                  | Appears in Docs  |
+| ------------- | ----------------------- | ---------------- |
+| Plain text    | Regular paragraphs      | Yes              |
+| Bold/emphasis | `**bold**`, `*italic*`  | Yes              |
+| Tables        | Markdown pipe tables    | Yes              |
+| Lists         | `- item` or `1. item`   | Yes              |
+| DocStrings    | `"""typescript`...`"""` | Yes (code block) |
+| Comments      | `# comment`             | No (ignored)     |
+
+#### Syntax Notes and Gotchas
+
+##### Forbidden in Feature Descriptions
+
+| Forbidden                     | Why                              | Alternative                         |
+| ----------------------------- | -------------------------------- | ----------------------------------- |
+| Code fences (triple backtick) | Not Gherkin syntax               | Use DocStrings with lang hint       |
+| `@prefix` in free text        | Interpreted as Gherkin tag       | Remove `@` or use `libar-dev`       |
+| Nested DocStrings             | Gherkin parser error             | Reference code stub file            |
+| `#` at line start             | Gherkin comment -- kills parsing | Remove, use `//`, or step DocString |
+
+##### Tag Value Constraints
+
+**Tag values cannot contain spaces.** Use hyphens:
+
+| Invalid                         | Valid                          |
+| ------------------------------- | ------------------------------ |
+| `@unlock-reason:Fix for issue`  | `@unlock-reason:Fix-for-issue` |
+| `@architect-pattern:My Pattern` | `@architect-pattern:MyPattern` |
+
+For values with spaces, use the `quoted-value` format where supported:
+
+```gherkin
+@architect-usecase "When handling command failures"
+```
+
+#### Quick Reference
+
+| Element              | Use For                                | Example                             |
+| -------------------- | -------------------------------------- | ----------------------------------- |
+| Background DataTable | Deliverables, shared reference data    | Deliverables table in roadmap specs |
+| Rule:                | Group scenarios by business constraint | Invariant + Rationale + Verified by |
+| Scenario Outline     | Same pattern with variations           | Examples tables with multiple rows  |
+| DocString `"""`      | Code examples, content with pipes      | TypeScript/Gherkin code blocks      |
+| Section comments `#` | Organize large feature files           | `# ========= Section ==========`    |