@libar-dev/architect 1.0.0-pre.3

package/docs/METHODOLOGY.md

@@ -0,0 +1,240 @@
+# Architect Methodology
+
+> **Editorial Document:** This document contains design philosophy and rationale that cannot be auto-generated from code annotations. It is maintained manually.
+
+> **Git is the event store. Documentation artifacts are projections. Annotated code is the single source of truth.**
+
+This document explains the _why_ behind `@libar-dev/architect`. For _how_, see [README.md](../README.md) and [TAXONOMY.md](./TAXONOMY.md).
+
+---
+
+## Core Thesis
+
+Traditional documentation fails because it exists outside the code. Developers update code, forget to update docs, and the gap widens until docs become fiction.
+
+**The USDP (Unified Software Delivery Process) inverts this:**
+
+| Traditional Approach           | USDP Approach                      |
+| ------------------------------ | ---------------------------------- |
+| Docs are written               | Docs are generated                 |
+| Status is tracked manually     | Status is FSM-enforced             |
+| Requirements live in Jira      | Requirements are Gherkin scenarios |
+| AI agents parse stale Markdown | AI agents query typed APIs         |
+
+### The Insight
+
+Event sourcing teaches us: **derive state, don't store it**. Apply this to documentation:
+
+- **Events** = Git commits (changes to annotated code)
+- **Projections** = Generated docs (PATTERNS.md, ROADMAP.md)
+- **Read Model** = MasterDataset (consumed by codecs, validators, and Data API CLI)
+
+When you run `architect-generate`, you're rebuilding read models from the event stream. The source annotations are always authoritative.
+
+---
+
+## Dogfooding: This Package Documents Itself
+
+Every pattern in this package uses its own annotation system. Real examples:
+
+**Document Extractor** (pattern extraction):
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern Document Extractor
+ * @architect-status completed
+ * @architect-uses Pattern Scanner, Tag Registry, Zod
+ * @architect-used-by Orchestrator, Generators
+ */
+export function extractPatterns(
+  scannedFiles: readonly ScannedFile[], baseDir: string, registry?: TagRegistry
+): ExtractionResults { ... }
+```
+
+**Pattern Scanner** (file discovery):
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern Pattern Scanner
+ * @architect-status completed
+ * @architect-uses glob, AST Parser
+ * @architect-used-by Doc Extractor, Orchestrator
+ */
+export async function scanPatterns(
+  config: ScannerConfig, registry?: TagRegistry
+): Promise<Result<ScanResults, never>> { ... }
+```
+
+Run `pnpm docs:patterns` and these annotations become a searchable pattern registry with dependency graphs.
+
+---
+
+## Session Workflow
+
+| Session               | Input               | Output                      | FSM State                          |
+| --------------------- | ------------------- | --------------------------- | ---------------------------------- |
+| **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`                  |
+
+**When to skip sessions:**
+
+| Skip              | When                                                  |
+| ----------------- | ----------------------------------------------------- |
+| Design            | Single valid approach, straightforward implementation |
+| Planning + Design | Ready to code, clear scope, no decisions              |
+| Neither           | Multi-session work, architectural decisions           |
+
+---
+
+## Annotation Ownership Strategy
+
+> **Split-Ownership Principle:** Feature files own _what_ and _when_ (planning). Code stubs own _how_ and _with what_ (implementation). Neither duplicates the other.
+
+### Feature Files Own (Planning)
+
+| Tag                    | Purpose                                                  |
+| ---------------------- | -------------------------------------------------------- |
+| `@<prefix>-status`     | FSM state (`roadmap`, `active`, `completed`, `deferred`) |
+| `@<prefix>-phase`      | Milestone sequencing                                     |
+| `@<prefix>-depends-on` | Pattern-level roadmap dependencies                       |
+| `@<prefix>-enables`    | What this unblocks                                       |
+| `@<prefix>-release`    | Version targeting                                        |
+
+### Code Stubs Own (Implementation)
+
+| Tag                 | Purpose                                              |
+| ------------------- | ---------------------------------------------------- |
+| `@<prefix>-uses`    | Technical dependencies (what this calls)             |
+| `@<prefix>-used-by` | Technical consumers (what calls this)                |
+| `@<prefix>-usecase` | When/how to use                                      |
+| Category flags      | Domain classification (`core`, `api`, `infra`, etc.) |
+
+### Example Split
+
+**Feature file** (specs/my-pattern.feature):
+
+```gherkin
+@architect
+@architect-pattern:EventStoreDurability
+@architect-status:roadmap
+@architect-phase:18
+@architect-depends-on:EventStoreFoundation
+@architect-enables:SagaEngine
+Feature: Event Store Durability
+```
+
+**Code stub** (src/event-store/durability.ts):
+
+```typescript
+/**
+ * @architect
+ * @architect-status roadmap
+ * @architect-event-sourcing
+ * @architect-uses EventStoreFoundation, Workpool
+ * @architect-used-by SagaEngine, CommandOrchestrator
+ */
+```
+
+Note: Code stubs must NOT use `@<prefix>-pattern`. The feature file is the canonical pattern definition.
+
+---
+
+## Two-Tier Spec Architecture
+
+| Tier        | Location                | Purpose                                     | Executable |
+| ----------- | ----------------------- | ------------------------------------------- | ---------- |
+| **Roadmap** | `architect/specs/`      | Planning, deliverables, acceptance criteria | No         |
+| **Package** | `{pkg}/tests/features/` | Implementation proof, regression testing    | Yes        |
+
+**Traceability:**
+
+- Roadmap spec: `@<prefix>-executable-specs:{package}/tests/features/behavior/{feature}`
+- Package spec: `@<prefix>-implements:{PatternName}`
+
+This separation keeps test output clean (no roadmap noise) while maintaining bidirectional traceability.
+
+---
+
+## Code Stubs
+
+Code is the source of truth. Feature files reference code, not duplicate it.
+
+```typescript
+/**
+ * @architect
+ * @architect-status roadmap
+ *
+ * ## Reservation Pattern - TTL-Based Pre-Creation Uniqueness
+ */
+export function reserve(ctx: MutationCtx, args: ReserveArgs): Promise<ReservationResult> {
+  throw new Error('ReservationPattern not yet implemented - roadmap pattern');
+}
+```
+
+| Level         | Contains                  | When                       |
+| ------------- | ------------------------- | -------------------------- |
+| **Minimal**   | JSDoc annotations only    | Quick exploration          |
+| **Interface** | Types + stub functions    | API contracts              |
+| **Partial**   | Working code + some stubs | Progressive implementation |
+
+---
+
+## Stubs Architecture
+
+Two types of stubs serve different purposes and live in different locations:
+
+### Code Stubs (Design Session Artifacts)
+
+Design session code stubs define API shapes with `throw new Error("Not implemented")`. They live **outside `src/`** to avoid TypeScript compilation and ESLint issues:
+
+```
+architect/
+├── stubs/                    # Design session code stubs (not compiled)
+│   └── {pattern-name}/      # One directory per pattern
+│       └── *.ts             # API shapes, interfaces, throw-not-implemented
+├── specs/                    # Tier 1 roadmap specs
+└── ...
+```
+
+| Phase          | Location                     | Status                               |
+| -------------- | ---------------------------- | ------------------------------------ |
+| Design         | `architect/stubs/{pattern}/` | `throw new Error("Not implemented")` |
+| Implementation | Move/copy to `src/`          | Replace with real logic              |
+| Completed      | `src/`                       | Production code                      |
+
+Stubs are scanned by the documentation pipeline (via `-i 'architect/stubs/**/*.ts'`) but excluded from TypeScript compilation (`tsconfig.json` includes only `src/**/*`) and ESLint (`eslint` targets `src tests`).
+
+### Planning Stubs (Test Step Definition Stubs)
+
+Step definitions created during Planning sessions go in a separate directory excluded from test execution:
+
+```
+tests/
+├── steps/              # Executable (included in test runner)
+├── planning-stubs/     # Not yet implemented (excluded)
+└── features/           # Feature files
+```
+
+| Phase          | Location          | Status                               |
+| -------------- | ----------------- | ------------------------------------ |
+| Planning       | `planning-stubs/` | `throw new Error("Not implemented")` |
+| Implementation | Move to `steps/`  | Replace with real logic              |
+| Completed      | `steps/`          | Fully executable                     |
+
+This avoids `.skip()` (forbidden by test safety policy) while preserving planning artifacts.
+
+---
+
+## Related Documentation
+
+| Document                                     | Purpose                                      |
+| -------------------------------------------- | -------------------------------------------- |
+| [README.md](../README.md)                    | Quick start, FSM diagram, Data API CLI usage |
+| [PROCESS-GUARD.md](./PROCESS-GUARD.md)       | FSM validation rules, protection levels, CLI |
+| [CONFIGURATION.md](./CONFIGURATION.md)       | Tag prefixes, presets, customization         |
+| [GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md) | Writing effective specs                      |
+| [TAXONOMY.md](./TAXONOMY.md)                 | Tag taxonomy concepts and API                |

package/docs/PROCESS-API.md

@@ -0,0 +1,65 @@
+# Data API CLI
+
+> **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/PROCESS-API-REFERENCE.md) and [Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes).
+>
+> Query process state directly from annotated source code.
+
+> **For AI coding agents:** Start every session with these three commands:
+>
+> 1. `overview` — project health
+> 2. `scope-validate <pattern> <session-type>` — catches blockers before you start
+> 3. `context <pattern> --session <type>` — curated context bundle
+
+---
+
+## Generated References
+
+> This document retains operational reference (JSON envelope, exit codes, piping).
+> For full CLI documentation, see the generated references below.
+
+- **[CLI Reference Tables](../docs-live/reference/PROCESS-API-REFERENCE.md)** — all flags, options, filters, and modifiers
+- **[Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md)** — command descriptions, usage examples, and common recipes
+
+---
+
+## Output Reference
+
+### JSON Envelope
+
+All JSON commands wrap output in a `QueryResult` envelope:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "metadata": {
+    "timestamp": "2026-02-21T04:31:31.633Z",
+    "patternCount": 318
+  }
+}
+```
+
+On error:
+
+```json
+{
+  "success": false,
+  "error": "Pattern not found: \"Orchestrator\"\nDid you mean: OrchestratorPipelineFactoryMigration?",
+  "code": "PATTERN_NOT_FOUND"
+}
+```
+
+### Exit Codes
+
+| Code | Meaning                        |
+| ---- | ------------------------------ |
+| `0`  | Success                        |
+| `1`  | Error (with message on stderr) |
+
+### JSON Piping
+
+`pnpm` outputs a banner line to stdout (`> @libar-dev/...`). For clean JSON piping, use `npx tsx src/cli/process-api.ts` directly:
+
+```bash
+npx tsx src/cli/process-api.ts list --status roadmap --names-only | jq '.data[]'
+```

package/docs/PROCESS-GUARD.md

@@ -0,0 +1,341 @@
+# Process Guard
+
+> **Deprecated:** This document is superseded by the auto-generated [Process Guard Reference](../docs-live/reference/PROCESS-GUARD-REFERENCE.md) which includes quick reference tables, error guides, CLI usage, and programmatic API. This file is preserved for reference only.
+
+Process Guard validates delivery workflow changes at commit time. For FSM concepts and state definitions, see [METHODOLOGY.md](./METHODOLOGY.md#fsm-enforced-workflow).
+
+---
+
+## Quick Reference
+
+### Protection Levels
+
+| Status      | Level | Allowed                    | Blocked                               |
+| ----------- | ----- | -------------------------- | ------------------------------------- |
+| `roadmap`   | none  | Full editing               | -                                     |
+| `deferred`  | none  | Full editing               | -                                     |
+| `active`    | scope | Edit existing deliverables | Adding new deliverables               |
+| `completed` | hard  | Nothing                    | Any change without `@*-unlock-reason` |
+
+### Valid Transitions
+
+| From        | To                     | Notes                           |
+| ----------- | ---------------------- | ------------------------------- |
+| `roadmap`   | `active`, `deferred`   | Start work or postpone          |
+| `active`    | `completed`, `roadmap` | Finish or regress if blocked    |
+| `deferred`  | `roadmap`              | Resume planning                 |
+| `completed` | _(none)_               | Terminal — use unlock to modify |
+
+### Escape Hatches
+
+| Situation                     | Solution                           | Example                                       |
+| ----------------------------- | ---------------------------------- | --------------------------------------------- |
+| Fix bug in completed spec     | Add `@*-unlock-reason:'reason'`    | `@architect-unlock-reason:'Fix typo'`         |
+| Modify outside session scope  | `--ignore-session` flag            | `architect-guard --staged --ignore-session`   |
+| CI treats warnings as errors  | `--strict` flag                    | `architect-guard --all --strict`              |
+| Skip workflow (legacy import) | Multiple transitions in one commit | Set `roadmap` then `completed` in same commit |
+
+---
+
+## Error Messages and Fixes
+
+### `completed-protection`
+
+**Error:**
+
+```text
+[ERROR] specs/phase-state-machine.feature
+  Cannot modify completed spec without unlock reason
+  Suggestion: Add @architect-unlock-reason:'reason for modification'
+```
+
+**Cause:** File has `@architect-status:completed` but no unlock annotation.
+
+**Fix:** Add unlock reason explaining why modification is necessary:
+
+```gherkin
+@architect
+@architect-pattern:PhaseStateMachine
+@architect-status:completed
+@architect-unlock-reason:'Fix incorrect FSM diagram in documentation'
+Feature: Phase State Machine
+```
+
+**Unlock reason requirements:**
+
+- Minimum **10 characters** (short reasons like "fix" are rejected)
+- Cannot be a placeholder: `test`, `xxx`, `bypass`, `temp`, `todo`, `fixme`
+- If the reason is invalid, the error still fires — Process Guard treats it as no unlock reason
+
+**Alternative:** If this should be new work, create a new spec instead of modifying completed work.
+
+---
+
+### `invalid-status-transition`
+
+**Error:**
+
+```text
+[ERROR] specs/my-feature.feature
+  Invalid status transition: roadmap -> completed
+  Suggestion: Valid transitions from roadmap: active, deferred
+```
+
+**Cause:** Attempted to skip `active` phase.
+
+**Fix:** Follow the FSM path:
+
+```gherkin
+# Step 1: Move to active
+@architect-status:active
+
+# Step 2: After implementation complete, move to completed
+@architect-status:completed
+```
+
+**Common invalid transitions:**
+
+| Attempted             | Why Invalid                  | Valid Path                             |
+| --------------------- | ---------------------------- | -------------------------------------- |
+| `roadmap->completed`  | Must go through `active`     | `roadmap->active->completed`           |
+| `deferred->active`    | Must return to roadmap first | `deferred->roadmap->active`            |
+| `deferred->completed` | Cannot skip two states       | `deferred->roadmap->active->completed` |
+| `completed->*`        | Terminal state               | Use `@*-unlock-reason` to modify       |
+
+---
+
+### `scope-creep`
+
+**Error:**
+
+```text
+[ERROR] specs/process-guard-linter.feature
+  Cannot add deliverables to active spec: "New unplanned feature"
+  Suggestion: Remove new deliverable or revert status to roadmap
+```
+
+**Cause:** Added a row to the deliverables table while status is `active`.
+
+**Fix options:**
+
+1. **Remove the new deliverable** — Keep scope locked during implementation
+2. **Revert to roadmap** — If scope genuinely needs to expand:
+   ```gherkin
+   @architect-status:roadmap  # Temporarily revert
+   # Add deliverable, then:
+   @architect-status:active   # Resume implementation
+   ```
+
+**Why this rule exists:** Prevents scope creep during implementation. Plan fully before starting; implement what was planned.
+
+---
+
+### `session-scope` (Warning)
+
+**Warning:**
+
+```text
+[WARN] specs/unrelated-feature.feature
+  File not in active session scope
+  Suggestion: Add to session scope or use --ignore-session
+```
+
+**Cause:** Modifying a file not listed in the current session's `scopedSpecs`.
+
+**Fix options:**
+
+1. **Add to session scope** — If this file should be in scope
+2. **Use `--ignore-session`** — For intentional out-of-scope changes:
+   ```bash
+   architect-guard --staged --ignore-session
+   ```
+
+---
+
+### `session-excluded`
+
+**Error:**
+
+```text
+[ERROR] specs/legacy-feature.feature
+  File is explicitly excluded from session
+  Suggestion: Remove from exclusion list or use --ignore-session
+```
+
+**Cause:** File is in the session's `excludedSpecs` list.
+
+**Fix options:**
+
+1. **Remove from exclusion list** — If exclusion was a mistake
+2. **Use `--ignore-session`** — For emergency changes:
+   ```bash
+   architect-guard --staged --ignore-session
+   ```
+
+---
+
+### `deliverable-removed` (Warning)
+
+**Warning:**
+
+```text
+[WARN] specs/active-feature.feature
+  Deliverable removed: "Unit tests"
+  Suggestion: Document if descoped or completed elsewhere
+```
+
+**Cause:** A deliverable was removed from an active spec.
+
+**Fix:** This is informational. If intentional, no action needed. Consider documenting why in a commit message.
+
+---
+
+## CLI Usage
+
+```bash
+lint-process [options]
+```
+
+### Modes
+
+| Flag       | Description                       | Use Case           |
+| ---------- | --------------------------------- | ------------------ |
+| `--staged` | Validate staged changes (default) | Pre-commit hooks   |
+| `--all`    | Validate all changes vs main      | CI/CD pipelines    |
+| `--files`  | Validate specific files           | Development checks |
+
+### Options
+
+| Flag                | Description                            |
+| ------------------- | -------------------------------------- |
+| `--strict`          | Treat warnings as errors (exit 1)      |
+| `--ignore-session`  | Skip session scope rules               |
+| `--show-state`      | Debug: show derived process state      |
+| `--format json`     | Machine-readable output                |
+| `-f, --file <path>` | Specific file to validate (repeatable) |
+| `-b, --base-dir`    | Base directory for file resolution     |
+
+### Exit Codes
+
+| Code | Meaning                                      |
+| ---- | -------------------------------------------- |
+| `0`  | No errors (warnings allowed unless --strict) |
+| `1`  | Errors found                                 |
+
+### Examples
+
+```bash
+# Pre-commit hook (recommended)
+architect-guard --staged
+
+# CI pipeline with strict mode
+architect-guard --all --strict
+
+# Validate specific file
+architect-guard --file specs/my-feature.feature
+
+# Debug: see what state was derived
+architect-guard --staged --show-state
+
+# Override session scope for emergency fix
+architect-guard --staged --ignore-session
+```
+
+---
+
+## Pre-commit Setup
+
+### Husky
+
+```bash
+# .husky/pre-commit
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx architect-guard --staged
+```
+
+### package.json
+
+```json
+{
+  "scripts": {
+    "lint:process": "architect-guard --staged",
+    "lint:process:ci": "architect-guard --all --strict"
+  }
+}
+```
+
+---
+
+## Programmatic API
+
+```typescript
+import {
+  deriveProcessState,
+  detectStagedChanges,
+  validateChanges,
+  hasErrors,
+  summarizeResult,
+} from '@libar-dev/architect/lint';
+
+// 1. Derive state from annotations
+const state = (await deriveProcessState({ baseDir: '.' })).value;
+
+// 2. Detect changes
+const changes = detectStagedChanges('.').value;
+
+// 3. Validate
+const { result } = validateChanges({
+  state,
+  changes,
+  options: { strict: false, ignoreSession: false },
+});
+
+// 4. Handle results
+if (hasErrors(result)) {
+  console.log(summarizeResult(result));
+  for (const v of result.violations) {
+    console.log(`[${v.rule}] ${v.file}: ${v.message}`);
+    if (v.suggestion) console.log(`  Fix: ${v.suggestion}`);
+  }
+  process.exit(1);
+}
+```
+
+### API Functions
+
+| Category | Function                    | Description                       |
+| -------- | --------------------------- | --------------------------------- |
+| State    | `deriveProcessState(cfg)`   | Build state from file annotations |
+| Changes  | `detectStagedChanges(dir)`  | Parse staged git diff             |
+| Changes  | `detectBranchChanges(dir)`  | Parse all changes vs main         |
+| Changes  | `detectFileChanges(dir, f)` | Parse specific files              |
+| Validate | `validateChanges(input)`    | Run all validation rules          |
+| Results  | `hasErrors(result)`         | Check for blocking errors         |
+| Results  | `hasWarnings(result)`       | Check for warnings                |
+| Results  | `summarizeResult(result)`   | Human-readable summary            |
+
+---
+
+## Architecture
+
+Process Guard uses the **Decider pattern**: pure functions with no I/O.
+
+```
+deriveProcessState() ─┐
+                      ├─► validateChanges() ─► ValidationResult
+detectChanges()  ─────┘
+```
+
+State is derived from file annotations — there is no separate state file to maintain.
+
+---
+
+## Related Documentation
+
+| Document                           | Content                         |
+| ---------------------------------- | ------------------------------- |
+| [METHODOLOGY.md](./METHODOLOGY.md) | FSM concepts, state definitions |
+| [README.md](../README.md)          | Package overview, quick start   |
+| [TAXONOMY.md](./TAXONOMY.md)       | Tag taxonomy concepts and API   |