@libar-dev/architect 1.0.0-pre.3

package/docs/SESSION-GUIDES.md

@@ -0,0 +1,391 @@
+# Session Workflow Guides
+
+> **Deprecated:** This document is superseded by the auto-generated [Session Workflow Guide](../docs-live/reference/SESSION-WORKFLOW-GUIDE.md) which includes a Mermaid decision tree, session checklists, and FSM protection reference. This file is preserved for reference only.
+>
+> Quick reference for each session type. For concepts (FSM, two-tier architecture), see [METHODOLOGY.md](./METHODOLOGY.md).
+
+---
+
+## Session Decision Tree
+
+```
+Starting from pattern brief?
+├── Yes → Need code stubs now? → Yes → Planning + Design
+│                              → No  → Planning
+└── No  → Ready to code? → Yes → Complex decisions? → Yes → Design first
+                                                    → No  → Implementation
+                        → No  → Planning
+```
+
+| Session           | Input               | Output                      | FSM Change                 |
+| ----------------- | ------------------- | --------------------------- | -------------------------- |
+| Planning          | Pattern brief       | Roadmap spec (`.feature`)   | Creates `roadmap`          |
+| Design            | Complex requirement | Decision specs + code stubs | None                       |
+| Implementation    | Roadmap spec        | Code + tests                | `roadmap→active→completed` |
+| Planning + Design | Pattern brief       | Spec + stubs                | Creates `roadmap`          |
+
+---
+
+## Planning Session
+
+**Goal:** Create a roadmap spec. Do not write implementation code.
+
+### Context Gathering
+
+```bash
+pnpm architect:query -- overview                                # Project health
+pnpm architect:query -- list --status roadmap --names-only      # Available patterns
+```
+
+### Checklist
+
+- [ ] **Extract metadata** from pattern brief:
+  - Phase number → `@<prefix>-phase`
+  - Dependencies → `@<prefix>-depends-on`
+  - Status → `@<prefix>-status:roadmap` (always `roadmap`)
+
+- [ ] **Create spec file** at `{specs-directory}/{product-area}/{pattern}.feature`
+
+- [ ] **Structure the feature:**
+
+  ```gherkin
+  @<prefix>
+  @<prefix>-pattern:MyPattern
+  @<prefix>-status:roadmap
+  @<prefix>-phase:15
+  Feature: My Pattern
+
+    **Problem:** One sentence.
+
+    **Solution:**
+    - Key mechanism 1
+    - Key mechanism 2
+  ```
+
+- [ ] **Add deliverables table:**
+
+  ```gherkin
+  Background: Deliverables
+    Given the following deliverables:
+      | Deliverable | Status  | Location | Tests | Test Type |
+      | Core types  | pending | src/types.ts | Yes | unit |
+  ```
+
+- [ ] **Convert tables to Rules** — Each business constraint becomes a `Rule:` block
+
+- [ ] **Add scenarios per Rule** — Minimum: 1 `@happy-path` + 1 `@validation`
+
+- [ ] **Set executable specs location:**
+  ```gherkin
+  @<prefix>-executable-specs:{package}/tests/features/behavior/{pattern}
+  ```
+
+### Do NOT
+
+- Create `.ts` implementation files
+- Transition to `active`
+- Ask "Ready to implement?"
+
+### Example: Architect dogfood
+
+See [`tests/features/validation/fsm-validator.feature`](../tests/features/validation/fsm-validator.feature) for a complete roadmap spec with Rules, ScenarioOutlines, and proper tagging.
+
+---
+
+## Design Session
+
+**Goal:** Make architectural decisions. Create code stubs with interfaces. Do not implement.
+
+### Context Gathering
+
+```bash
+pnpm architect:query -- context <PatternName> --session design  # Full context bundle
+pnpm architect:query -- dep-tree <PatternName>                  # Dependency chain
+pnpm architect:query -- stubs <PatternName>                     # Existing design stubs
+```
+
+Use these **before** launching explore agents. See [PROCESS-API.md](./PROCESS-API.md).
+
+### When Required
+
+| Use Design Session         | Skip Design Session |
+| -------------------------- | ------------------- |
+| Multiple valid approaches  | Single obvious path |
+| New patterns/capabilities  | Bug fix             |
+| Cross-context coordination | Clear requirements  |
+
+### Checklist
+
+- [ ] **Record decisions** as PDR `.feature` files in `architect/decisions/`
+
+- [ ] **Document options** — At least 2-3 approaches with pros/cons
+
+- [ ] **Get approval** — User must approve recommended approach
+
+- [ ] **Create code stubs** in `architect/stubs/{pattern-name}/`:
+
+  ```typescript
+  // architect/stubs/{pattern-name}/my-function.ts
+  /**
+   * @<prefix>
+   * @<prefix>-status roadmap
+   * @<prefix>-implements MyPattern
+   * @<prefix>-uses Workpool, EventStore
+   *
+   * ## My Pattern - Description
+   *
+   * Target: src/path/to/final/location.ts
+   * See: PDR-001 (Design Decision)
+   * Since: DS-1
+   */
+  export interface MyResult {
+    id: string;
+  }
+
+  export function myFunction(args: MyArgs): Promise<MyResult> {
+    throw new Error('MyPattern not yet implemented - roadmap pattern');
+  }
+  ```
+
+  Stubs live outside `src/` to avoid TypeScript compilation and ESLint issues. They are scanned by the documentation pipeline via `-i 'architect/stubs/**/*.ts'`.
+
+- [ ] **Verify stub identifier spelling** — Check all exported function/type/interface names for typos before committing stubs
+
+- [ ] **List canonical helpers in `@<prefix>-uses`** — If the function does status matching, reference `isDeliverableStatusComplete`/`isDeliverableStatusPending` from `taxonomy/deliverable-status.ts`
+
+### Do NOT
+
+- Create markdown design documents (use decision specs instead)
+- Create implementation plans
+- Transition spec to `active`
+- Write full implementations (stubs only)
+
+---
+
+## Implementation Session
+
+**Goal:** Write code. The roadmap spec is the source of truth.
+
+### Context Gathering (Step 0)
+
+```bash
+# Pre-flight — catches FSM violations, missing deps, incomplete deliverables
+pnpm architect:query -- scope-validate <PatternName> implement
+
+# Curated context — deliverables, FSM state, test files
+pnpm architect:query -- context <PatternName> --session implement
+
+# File paths for implementation
+pnpm architect:query -- files <PatternName> --related
+```
+
+The `scope-validate` command replaces the manual pre-flight checklist — it checks
+dependency completion, deliverable definitions, FSM validity, and design decisions.
+See [PROCESS-API.md](./PROCESS-API.md#scope-validate).
+
+### Execution Checklist
+
+1. **Transition to active FIRST** (before any code):
+
+   ```gherkin
+   # Change in roadmap spec:
+   @<prefix>-status:active
+   ```
+
+   > Protection: `active` = scope-locked (no new deliverables)
+
+2. **Create executable spec stubs** (if `@<prefix>-executable-specs` present):
+
+   ```gherkin
+   @<prefix>-implements:MyPattern
+   Feature: My Pattern Behavior
+   ```
+
+3. **For each deliverable:**
+   - [ ] Read acceptance criteria from spec
+   - [ ] Implement code (replace `throw new Error`)
+   - [ ] Preserve `@<prefix>-*` annotations in JSDoc
+   - [ ] Write tests
+   - [ ] Update deliverable status:
+     ```gherkin
+     | Core types | complete | src/types.ts | Yes | unit |
+     ```
+
+4. **Verify all design decisions addressed:**
+   - [ ] Run `pnpm architect:query -- decisions <SpecName>` and confirm each DD-N has a corresponding `// DD-N:` comment in the implementation
+
+5. **Transition to completed** (only when ALL done):
+
+   ```gherkin
+   @<prefix>-status:completed
+   ```
+
+   > Protection: `completed` = hard-locked (requires `@<prefix>-unlock-reason` to modify)
+
+6. **Regenerate docs:**
+   ```bash
+   pnpm docs:all
+   ```
+
+### Do NOT
+
+- Add new deliverables to an `active` spec
+- Mark `completed` with incomplete work
+- Skip FSM transitions
+- Edit generated docs directly
+
+---
+
+## Planning + Design Session
+
+**Goal:** Create spec AND code stubs in one session. For immediate implementation handoff.
+
+### When to Use
+
+| Use Planning + Design               | Use Planning Only            |
+| ----------------------------------- | ---------------------------- |
+| Need stubs for implementation       | Only enhancing spec          |
+| Preparing for immediate handoff     | Still exploring requirements |
+| Want complete two-tier architecture | Don't need Tier 2 yet        |
+
+### Checklist
+
+1. **Complete Planning checklist** (above)
+
+2. **Add `@<prefix>-executable-specs` tag** pointing to Tier 2 location
+
+3. **Create code stubs** (see Design Session checklist)
+
+4. **Create Tier 2 directory:**
+
+   ```
+   {package}/tests/features/behavior/{pattern-name}/
+   ```
+
+5. **Create Tier 2 feature stubs:**
+
+   ```gherkin
+   @<prefix>-implements:MyPattern
+   @acceptance-criteria
+   Feature: My Pattern - Rule Name
+
+     @happy-path
+     Scenario: Happy path from roadmap spec
+       # Implementation placeholder
+       Given {precondition}
+       When {action}
+       Then {outcome}
+   ```
+
+6. **Create step definitions stub** at `tests/planning-stubs/{pattern}.steps.ts`:
+
+   ```typescript
+   /**
+    * @<prefix>-implements:MyPattern
+    *
+    * NOTE: In tests/planning-stubs/ (excluded from test runner).
+    * Move to tests/steps/ during implementation.
+    */
+
+   interface TestState {
+     result: unknown;
+     error: Error | null;
+   }
+
+   let state: TestState;
+   // Steps with: throw new Error("Not implemented: description");
+   ```
+
+### Handoff Complete When
+
+**Tier 1:**
+
+- [ ] All `@<prefix>-*` tags present
+- [ ] `@<prefix>-executable-specs` points to Tier 2
+- [ ] Deliverables table complete
+- [ ] Status is `roadmap`
+
+**Tier 2:**
+
+- [ ] Directory created with `.feature` files
+- [ ] Each file has `@<prefix>-implements`
+- [ ] Step definitions stub compiles
+
+**Validation:**
+
+- [ ] `pnpm lint` passes
+- [ ] `pnpm typecheck` passes
+
+---
+
+## Handoff Documentation
+
+For multi-session work, capture state at session boundaries.
+
+```bash
+# Generate handoff from actual annotation state (preferred over manual template)
+pnpm architect:query -- handoff --pattern <PatternName>
+pnpm architect:query -- handoff --pattern <PatternName> --git   # include recent commits
+```
+
+The CLI handoff always reflects current annotation state. The template below is for additional context:
+
+### Handoff Template
+
+```markdown
+## Session State
+
+- **Last completed:** Phase 1 - Core types
+- **In progress:** Phase 2 - Validation
+- **Blockers:** None
+
+### Files Modified
+
+- `src/types.ts` - Added core types
+- `src/validate.ts` - Started validation (incomplete)
+
+## Next Session
+
+1. **FIRST:** Complete validation in `src/validate.ts`
+2. Add integration tests
+3. Update deliverable statuses
+```
+
+### Discovery Tags
+
+Capture learnings inline during sessions:
+
+```gherkin
+# In feature file comments or code:
+# @<prefix>-discovered-gap: Missing-edge-case-for-empty-input
+# @<prefix>-discovered-improvement: Cache-parsed-results
+# @<prefix>-discovered-learning: Gherkin-requires-strict-indentation
+```
+
+See [`tests/features/behavior/session-handoffs.feature`](../tests/features/behavior/session-handoffs.feature) for the full handoff specification.
+
+---
+
+## Quick Reference: FSM Protection
+
+| State       | Protection   | Can Add Deliverables | Needs Unlock |
+| ----------- | ------------ | -------------------- | ------------ |
+| `roadmap`   | None         | Yes                  | No           |
+| `active`    | Scope-locked | No                   | No           |
+| `completed` | Hard-locked  | No                   | Yes          |
+| `deferred`  | None         | Yes                  | No           |
+
+Valid transitions: See [METHODOLOGY.md#fsm-enforced-workflow](./METHODOLOGY.md#fsm-enforced-workflow)
+
+---
+
+## Related Documentation
+
+| Document                                     | Content                                           |
+| -------------------------------------------- | ------------------------------------------------- |
+| [METHODOLOGY.md](./METHODOLOGY.md)           | Core thesis, FSM states, two-tier architecture    |
+| [GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md) | DataTables, DocStrings, Rule blocks               |
+| [CONFIGURATION.md](./CONFIGURATION.md)       | Tag prefixes, presets                             |
+| [TAXONOMY.md](./TAXONOMY.md)                 | Tag taxonomy concepts and API                     |
+| [PROCESS-API.md](./PROCESS-API.md)           | Data API CLI commands for all session types       |
+| [VALIDATION.md](./VALIDATION.md)             | CLI flags for lint-patterns and validate-patterns |

package/docs/TAXONOMY.md

@@ -0,0 +1,106 @@
+# Tag Taxonomy
+
+> **Deprecated:** This document is superseded by the auto-generated [Taxonomy Reference](../docs-live/TAXONOMY.md) which contains the full 60-tag catalog with all values, format types, and preset details. This file is preserved for reference only.
+
+The taxonomy defines the vocabulary for pattern annotations: what tags exist, their valid values, and how they're parsed. It's 100% TypeScript-defined in `src/taxonomy/`, providing type safety and IDE autocomplete.
+
+---
+
+## Concept
+
+A **taxonomy** is a classification system. In `@libar-dev/architect`, the taxonomy defines:
+
+| Component        | Purpose                                                   |
+| ---------------- | --------------------------------------------------------- |
+| **Categories**   | Domain classifications (e.g., `core`, `api`)              |
+| **Status**       | FSM states (`roadmap`, `active`, `completed`, `deferred`) |
+| **Format Types** | How tag values are parsed (`flag`, `csv`, `enum`)         |
+| **Hierarchy**    | Work item levels (`epic`, `phase`, `task`)                |
+
+The taxonomy is NOT a fixed schema. Presets (`libar-generic`, `ddd-es-cqrs`) select different subsets, and you can define custom categories.
+
+---
+
+## Architecture
+
+```
+src/taxonomy/
+├── index.ts               # Barrel exports
+├── registry-builder.ts    # buildRegistry() — creates TagRegistry
+├── categories.ts          # Category definitions (core, api, ddd, …)
+├── status-values.ts       # FSM state values: roadmap/active/completed/deferred
+├── deliverable-status.ts  # Deliverable statuses: complete/in-progress/pending/deferred/superseded/n-a
+├── normalized-status.ts   # Display normalization (3 buckets)
+├── format-types.ts        # Tag value parsing rules
+├── hierarchy-levels.ts    # epic/phase/task
+├── risk-levels.ts         # low/medium/high
+├── severity-types.ts      # error/warning/info
+├── layer-types.ts         # timeline/domain/integration/e2e/component/unknown
+├── generator-options.ts   # Format, groupBy, sortBy, workflow, priority, ADR enums
+└── conventions.ts         # Convention values for reference document generation
+```
+
+### TagRegistry
+
+The `buildRegistry()` function creates a `TagRegistry` containing all taxonomy definitions:
+
+```typescript
+import { buildRegistry } from '@libar-dev/architect/taxonomy';
+
+const registry = buildRegistry();
+// registry.tagPrefix       → "@architect-"
+// registry.fileOptInTag    → "@architect"
+// registry.categories      → CategoryDefinition[]
+// registry.metadataTags    → MetadataTagDefinition[]
+// registry.aggregationTags → AggregationTagDefinition[]
+// registry.formatOptions   → string[]
+```
+
+### Presets Select Taxonomy Subsets
+
+| Preset                    | Categories | Tag Prefix    | Use Case                         |
+| ------------------------- | ---------- | ------------- | -------------------------------- |
+| `libar-generic` (default) | 3          | `@architect-` | Simple projects (this package)   |
+| `ddd-es-cqrs`             | 21         | `@architect-` | DDD/Event Sourcing architectures |
+
+The preset determines which categories are available. All presets share the same status values and format types.
+
+---
+
+## Format Types
+
+Tags have different value formats:
+
+| Format         | Example                         | Parsing                        |
+| -------------- | ------------------------------- | ------------------------------ |
+| `flag`         | `@architect-core`               | Boolean presence (no value)    |
+| `value`        | `@architect-pattern MyPattern`  | Simple string                  |
+| `enum`         | `@architect-status completed`   | Constrained to predefined list |
+| `csv`          | `@architect-uses A, B, C`       | Comma-separated values         |
+| `number`       | `@architect-phase 15`           | Numeric value                  |
+| `quoted-value` | `@architect-brief:'Multi word'` | Preserves spaces               |
+
+---
+
+## Generating a Tag Reference
+
+Generate a human-readable taxonomy reference from the TypeScript taxonomy source:
+
+```bash
+# Via the docs script (recommended)
+pnpm docs:taxonomy
+
+# Direct CLI equivalent
+pnpm exec architect-generate -g taxonomy -i "src/**/*.ts" -o docs -f
+```
+
+The generated output reflects every tag the system supports — including all 21 categories available with the `ddd-es-cqrs` preset.
+
+---
+
+## Related Documentation
+
+| Topic                 | Document                                                    |
+| --------------------- | ----------------------------------------------------------- |
+| **Presets & config**  | [CONFIGURATION.md](./CONFIGURATION.md)                      |
+| **Custom categories** | [CONFIGURATION.md](./CONFIGURATION.md#custom-configuration) |