@libar-dev/architect 1.0.0-pre.3

package/docs-live/decisions/adr-001-taxonomy-canonical-values.md

@@ -0,0 +1,197 @@
+# ADR-001: ADR 001 Taxonomy Canonical Values
+
+**Purpose:** Architecture decision record for ADR 001 Taxonomy Canonical Values
+
+---
+
+## Overview
+
+| Property | Value    |
+| -------- | -------- |
+| Status   | accepted |
+| Category | process  |
+
+**Context:**
+The annotation system requires well-defined canonical values for taxonomy
+tags, FSM status lifecycle, and source ownership rules. Without canonical
+values, organic growth produces drift (Generator vs Generators, Process
+vs DeliveryProcess) and inconsistent grouping in generated documentation.
+
+**Decision:**
+Define canonical values for all taxonomy enums, FSM states with protection
+levels, valid transitions, tag format types, and source ownership rules.
+These are the durable constants of the delivery process.
+
+**Consequences:**
+
+| Type     | Impact                                                        |
+| -------- | ------------------------------------------------------------- |
+| Positive | Generated docs group into coherent sections                   |
+| Positive | FSM enforcement has clear, auditable state definitions        |
+| Positive | Source ownership prevents cross-domain tag confusion          |
+| Negative | Migration effort for existing specs with non-canonical values |
+
+## Rules
+
+### 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.
+
+**Rationale:** Without canonical values, organic drift (e.g., Generator vs Generators) produces inconsistent grouping in generated documentation and fragmented product area pages.
+
+| 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        |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### ADR category canonical values
+
+**Invariant:** The adr-category tag uses one of 4 values.
+
+**Rationale:** Unbounded category values prevent meaningful grouping of architecture decisions and make cross-cutting queries unreliable.
+
+| Value         | Purpose                                       |
+| ------------- | --------------------------------------------- |
+| architecture  | System structure, component design, data flow |
+| process       | Workflow, conventions, annotation rules       |
+| testing       | Test strategy, verification approach          |
+| documentation | Documentation generation, content structure   |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### 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.
+
+**Rationale:** Without protection levels, active specs accumulate scope creep and completed specs get silently modified, undermining delivery process integrity.
+
+| 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                    |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### Valid FSM transitions
+
+**Invariant:** Only these transitions are valid. All others are rejected by Process Guard.
+
+**Rationale:** Allowing arbitrary transitions (e.g., roadmap to completed) bypasses the active phase where scope-lock and deliverable tracking provide quality assurance.
+
+| From     | To        | Trigger               |
+| -------- | --------- | --------------------- |
+| roadmap  | active    | Start work            |
+| roadmap  | deferred  | Postpone              |
+| active   | completed | All deliverables done |
+| active   | roadmap   | Blocked/regressed     |
+| deferred | roadmap   | Resume planning       |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+  Completed is a terminal state. Modifications require
+  `@architect-unlock-reason` escape hatch.
+
+### Tag format types
+
+**Invariant:** Every tag has one of 6 format types that determines how its value is parsed.
+
+**Rationale:** Without explicit format types, parsers must guess value structure, leading to silent data corruption when CSV values are treated as single strings or numbers are treated as text.
+
+| 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' |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### Source ownership
+
+**Invariant:** Relationship tags have defined ownership by source type. Anti-pattern detection enforces these boundaries.
+
+**Rationale:** Cross-domain tag placement (e.g., runtime dependencies in Gherkin) creates conflicting sources of truth and breaks the dual-source architecture ownership model.
+
+| 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    |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### Quarter format convention
+
+**Invariant:** The quarter tag uses `YYYY-QN` format (e.g., `2026-Q1`). ISO-year-first sorting works lexicographically.
+
+**Rationale:** Non-standard formats (e.g., Q1-2026) break lexicographic sorting, which roadmap generation and timeline queries depend on for correct ordering.
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### 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.
+
+**Rationale:** Ad-hoc phase names and ordering produce inconsistent roadmap grouping across packages and make cross-package progress tracking impossible.
+
+| 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         |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+### Deliverable status canonical values
+
+**Invariant:** Deliverable status (distinct from pattern FSM status) uses exactly 6 values, enforced by Zod schema at parse time.
+
+**Rationale:** Freeform status strings bypass Zod validation and break DoD checks, which rely on terminal status classification to determine pattern completeness.
+
+| 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       |
+
+**Verified by:**
+
+- Canonical values are enforced
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)

package/docs-live/decisions/adr-002-gherkin-only-testing.md

@@ -0,0 +1,57 @@
+# ADR-002: ADR 002 Gherkin Only Testing
+
+**Purpose:** Architecture decision record for ADR 002 Gherkin Only Testing
+
+---
+
+## Overview
+
+| Property | Value    |
+| -------- | -------- |
+| Status   | accepted |
+| Category | testing  |
+
+**Context:**
+A package that generates documentation from `.feature` files had dual
+test approaches: 97 legacy `.test.ts` files alongside Gherkin features.
+This undermined the core thesis that Gherkin IS sufficient for all testing.
+
+**Decision:**
+Enforce strict Gherkin-only testing for the Architect package:
+
+- All tests must be `.feature` files with step definitions
+- No new `.test.ts` files
+- Edge cases use Scenario Outline with Examples tables
+
+**Consequences:**
+
+| Type     | Impact                                                                     |
+| -------- | -------------------------------------------------------------------------- |
+| Positive | Single source of truth for tests AND documentation                         |
+| Positive | Demonstrates Gherkin sufficiency -- the package practices what it preaches |
+| Positive | Living documentation always matches test coverage                          |
+| Positive | Forces better scenario design with Examples tables                         |
+| Negative | Scenario Outline syntax more verbose than parameterized tests              |
+
+## Rules
+
+### Source-driven process benefit
+
+**Invariant:** Feature files serve as both executable specs and documentation source. This dual purpose is the primary benefit of Gherkin-only testing for this package.
+
+**Rationale:** Parallel `.test.ts` files create a hidden test layer invisible to the documentation pipeline, undermining the single source of truth principle this package enforces.
+
+| Artifact            | Without Gherkin-Only        | With Gherkin-Only                  |
+| ------------------- | --------------------------- | ---------------------------------- |
+| Tests               | .test.ts (hidden from docs) | .feature (visible in docs)         |
+| Business rules      | Manually maintained         | Extracted from Rule blocks         |
+| Acceptance criteria | Implicit in test code       | Explicit @acceptance-criteria tags |
+| Traceability        | Manual cross-referencing    | @architect-implements links        |
+
+**Verified by:**
+
+- Gherkin-only policy enforced
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)

package/docs-live/decisions/adr-003-source-first-pattern-architecture.md

@@ -0,0 +1,147 @@
+# ADR-003: ADR 003 Source First Pattern Architecture
+
+**Purpose:** Architecture decision record for ADR 003 Source First Pattern Architecture
+
+---
+
+## Overview
+
+| Property | Value    |
+| -------- | -------- |
+| Status   | accepted |
+| Category | process  |
+
+**Context:**
+The original annotation architecture assumed pattern definitions live
+in tier 1 feature specs, with TypeScript code limited to `@architect-implements`.
+At scale this creates three problems: tier 1 specs become stale after implementation
+(only 39% of 44 specs have traceability to executable specs), retroactive annotation
+of existing code triggers merge conflicts, and duplicated Rules/Scenarios in tier 1
+specs average 200-400 lines that exist in better form in executable specs.
+
+**Decision:**
+Invert the ownership model: TypeScript source code is the canonical pattern
+definition. Tier 1 specs become ephemeral planning documents. The three durable
+artifacts are annotated source code, executable specs, and decision specs.
+
+**Consequences:**
+
+| Type     | Impact                                                              |
+| -------- | ------------------------------------------------------------------- |
+| Positive | Pattern identity travels with code from stub through production     |
+| Positive | Eliminates stale tier 1 spec maintenance burden                     |
+| Positive | Executable specs become the living specification (richer, verified) |
+| Positive | Retroactive annotation works without merge conflicts                |
+| Negative | Migration effort for existing tier 1 specs                          |
+| Negative | Requires updating CLAUDE.md annotation ownership guidance           |
+
+## Rules
+
+### TypeScript source owns pattern identity
+
+**Invariant:** A pattern is defined by `@architect-pattern` in a TypeScript file — either a stub (pre-implementation) or source code (post-implementation).
+
+**Rationale:** If pattern identity lives in tier 1 specs, it becomes stale after implementation and diverges from the code that actually realizes the pattern.
+
+| Phase          | Location                        | Status    |
+| -------------- | ------------------------------- | --------- |
+| Design         | `architect/stubs/pattern-name/` | roadmap   |
+| Implementation | `src/path/to/module.ts`         | active    |
+| Completed      | `src/path/to/module.ts`         | completed |
+
+**Pattern Definition Lifecycle:**
+
+    Exception: Patterns with no TypeScript implementation (pure process or
+    workflow concerns) may be defined in decision specs. The constraint is:
+    one definition per pattern, regardless of source type.
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+### Tier 1 specs are ephemeral working documents
+
+**Invariant:** Tier 1 roadmap specs serve planning and delivery tracking. They are not the source of truth for pattern identity, invariants, or acceptance criteria. After completion, they may be archived.
+
+**Rationale:** Treating tier 1 specs as durable creates a maintenance burden — at scale only 39% maintain traceability, and duplicated Rules/Scenarios average 200-400 stale lines.
+
+| Phase     | Planning Value                | Documentation Value                |
+| --------- | ----------------------------- | ---------------------------------- |
+| roadmap   | High                          | None (not yet built)               |
+| active    | Medium (deliverable tracking) | Low (stale snapshot)               |
+| completed | None                          | None (executable specs are better) |
+
+**Value by lifecycle phase:**
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+### Three durable artifact types
+
+**Invariant:** The delivery process produces three artifact types with long-term value. All other artifacts are projections or ephemeral.
+
+**Rationale:** Without a clear boundary between durable and ephemeral artifacts, teams maintain redundant documents that inevitably drift from the source of truth.
+
+| Artifact                 | Purpose                              | Owns                                  |
+| ------------------------ | ------------------------------------ | ------------------------------------- |
+| Annotated TypeScript     | Pattern identity, architecture graph | Name, status, uses, categories        |
+| Executable specs         | Behavior verification, invariants    | Rules, rationale, acceptance criteria |
+| Decision specs (ADR/PDR) | Architectural choices, rationale     | Why decisions were made               |
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+### Implements is UML Realization (many-to-one)
+
+**Invariant:** `@architect-implements` declares a realization relationship. Multiple files can implement the same pattern. One file can implement multiple patterns (CSV format).
+
+**Rationale:** Without many-to-one realization, cross-cutting patterns that span multiple files cannot be traced back to a single canonical definition.
+
+| Relationship | Tag                     | Cardinality             |
+| ------------ | ----------------------- | ----------------------- |
+| Definition   | `@architect-pattern`    | Exactly one per pattern |
+| Realization  | `@architect-implements` | Many-to-one             |
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+### Single-definition constraint
+
+**Invariant:** `@architect-pattern:X` may appear in exactly one file across the entire codebase. The `mergePatterns()` conflict check in `orchestrator.ts` correctly enforces this.
+
+**Rationale:** Duplicate pattern definitions cause merge conflicts in the MasterDataset and produce ambiguous ownership in generated documentation.
+
+| Current State                   | Resolution                                      |
+| ------------------------------- | ----------------------------------------------- |
+| Pattern in both TS and feature  | Keep TS definition, feature uses `@implements`  |
+| Pattern only in tier 1 spec     | Move definition to TS stub, archive tier 1 spec |
+| Pattern only in TS              | Already correct                                 |
+| Pattern only in executable spec | Valid if no TS implementation exists            |
+
+**Migration path for existing conflicts:**
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+### Reverse links preferred over forward links
+
+**Invariant:** `@architect-implements` (reverse: "I verify this pattern") is the primary traceability mechanism. `@architect-executable-specs` (forward: "my tests live here") is retained but not required.
+
+**Rationale:** Forward links in tier 1 specs go stale when specs are archived, while reverse links in test files are self-maintaining because the test cannot run without the implementation.
+
+| Mechanism                     | Usage             | Reliability                      |
+| ----------------------------- | ----------------- | -------------------------------- |
+| `@implements` (reverse)       | 14 patterns (32%) | Self-maintaining, lives in test  |
+| `@executable-specs` (forward) | 9 patterns (20%)  | Requires tier 1 spec maintenance |
+
+**Verified by:**
+
+- TypeScript source is canonical pattern definition
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)

package/docs-live/decisions/adr-004-session-workflow-commands.md

@@ -0,0 +1,137 @@
+# ADR-004: PDR 001 Session Workflow Commands
+
+**Purpose:** Architecture decision record for PDR 001 Session Workflow Commands
+
+---
+
+## Overview
+
+| Property | Value        |
+| -------- | ------------ |
+| Status   | accepted     |
+| Category | architecture |
+
+**Context:**
+DataAPIDesignSessionSupport adds `scope-validate` (pre-flight session
+readiness check) and `handoff` (session-end state summary) CLI subcommands.
+Seven design decisions affect how these commands behave.
+
+**Decision:**
+Seven design decisions (DD-1 through DD-7) captured as Rules below.
+
+## Rules
+
+### DD-1 - Text output with section markers
+
+**Invariant:** scope-validate and handoff must return plain text with === SECTION === markers, never JSON.
+
+**Rationale:** Inconsistent output formats force consumers to detect and branch on format type, breaking the dual output path contract.
+
+**Verified by:**
+
+- scope-validate outputs structured text
+
+  Both scope-validate and handoff return string from the router
+
+- using
+  === SECTION === markers. Follows the dual output path where text
+  commands bypass JSON.stringify.
+
+### DD-2 - Git integration is opt-in via --git flag
+
+**Invariant:** Domain logic must never invoke shell commands or depend on git directly.
+
+**Rationale:** Shell dependencies in domain logic make functions untestable without git fixtures and break deterministic behavior.
+
+**Verified by:**
+
+- N/A — no-shell constraint verified by code review (no exec/spawn calls in domain logic)
+
+  The handoff command accepts an optional --git flag. The CLI handler
+  calls git diff and passes file list to the pure generator function.
+  No shell dependency in domain logic.
+
+### DD-3 - Session type inferred from FSM status
+
+**Invariant:** Every FSM status must map to exactly one default session type, overridable by an explicit --session flag.
+
+**Rationale:** Ambiguous or missing inference forces users to always specify --session manually, defeating the ergonomic benefit of status-based defaults.
+
+| Status    | Inferred Session |
+| --------- | ---------------- |
+| roadmap   | design           |
+| active    | implement        |
+| completed | review           |
+| deferred  | design           |
+
+**Verified by:**
+
+- N/A — full mapping table (4 statuses) verified by code review; active→implement example in "Active pattern infers implement session"
+
+  Handoff infers session type from pattern's current FSM status.
+  An explicit --session flag overrides inference.
+
+### DD-4 - Severity levels match Process Guard model
+
+**Invariant:** Scope validation must use exactly three severity levels (PASS, BLOCKED, WARN) consistent with Process Guard.
+
+**Rationale:** Divergent severity models cause confusion when the same violation appears in both systems with different severity classifications.
+
+| Severity | Meaning                   |
+| -------- | ------------------------- |
+| PASS     | Check passed              |
+| BLOCKED  | Hard prerequisite missing |
+| WARN     | Recommendation not met    |
+
+**Verified by:**
+
+- N/A — three severity levels defined as type-system enum; verified by code review
+
+  Scope validation uses three severity levels:
+
+  The --strict flag promotes WARN to BLOCKED.
+
+### DD-5 - Current date only for handoff
+
+**Invariant:** Handoff must always use the current system date with no override mechanism.
+
+**Rationale:** A --date flag enables backdating handoff timestamps, which breaks audit trail integrity for multi-session work.
+
+**Verified by:**
+
+- N/A — no --date flag by design; verified by code review and CLI arg inventory
+
+  Handoff always uses the current date. No --date flag.
+
+### DD-6 - Both positional and flag forms for scope type
+
+**Invariant:** scope-validate must accept scope type as both a positional argument and a --type flag.
+
+**Rationale:** Supporting only one form creates inconsistency with CLI conventions and forces users to remember which form each subcommand uses.
+
+**Verified by:**
+
+- N/A — dual-form acceptance verified by code review (both positional and --type flag parsed in CLI handler)
+
+  scope-validate accepts scope type as both positional argument
+  and --type flag.
+
+### DD-7 - Co-located formatter functions
+
+**Invariant:** Each module must export both its data builder and text formatter as co-located functions.
+
+**Rationale:** Splitting builder and formatter across files increases coupling surface and makes it harder to trace data flow through the module.
+
+**Verified by:**
+
+- N/A — co-location is a module structure decision; verified by code review of scope-validator.ts and handoff-generator.ts exports
+
+  Each module (scope-validator.ts
+
+- handoff-generator.ts) exports
+  both the data builder and the text formatter. Simpler than the
+  context-assembler/context-formatter split.
+
+---
+
+[← Back to All Decisions](../DECISIONS.md)