@libar-dev/architect 1.0.0-pre.3

package/docs-live/_claude-md/configuration/configuration-guide.md

@@ -0,0 +1,216 @@
+### Configuration Guide
+
+#### Quick Reference
+
+| Preset                        | Tag Prefix    | Categories | Use Case                         |
+| ----------------------------- | ------------- | ---------- | -------------------------------- |
+| **`libar-generic`** (default) | `@architect-` | 3          | Simple projects (this package)   |
+| `ddd-es-cqrs`                 | `@architect-` | 21         | DDD/Event Sourcing architectures |
+
+```typescript
+// architect.config.ts
+import { defineConfig } from '@libar-dev/architect/config';
+
+// Default: libar-generic preset (simple 3-category taxonomy)
+export default defineConfig({
+  preset: 'libar-generic',
+  sources: {
+    typescript: ['src/**/*.ts'],
+    features: ['specs/*.feature'],
+  },
+  output: { directory: 'docs-generated' },
+});
+```
+
+#### Preset Selection
+
+##### When to Use Each Preset
+
+| Preset          | Use When                                                     | Categories                                                                               |
+| --------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `libar-generic` | Simple projects, standard `@architect-` prefix               | 3 (core, api, infra)                                                                     |
+| `ddd-es-cqrs`   | DDD architecture with bounded contexts, event sourcing, CQRS | 21 (domain, ddd, bounded-context, event-sourcing, decider, cqrs, saga, projection, etc.) |
+
+**Design decision:** Presets **replace** the base taxonomy categories entirely (not merged). If you need DDD categories, use the `ddd-es-cqrs` preset.
+
+##### Default Preset Selection
+
+All entry points default to `libar-generic`:
+
+| Entry Point                    | Default Preset                 | Context                          |
+| ------------------------------ | ------------------------------ | -------------------------------- |
+| `defineConfig()`               | `libar-generic` (3 categories) | Config file                      |
+| `loadProjectConfig()` fallback | `libar-generic` (3 categories) | CLI tools (no config file found) |
+| This package's config file     | `libar-generic` (3 categories) | Standalone package usage         |
+
+#### Unified Config File
+
+The `defineConfig()` function centralizes taxonomy, sources, output, and generator overrides in a single `architect.config.ts` file. CLI tools discover this file automatically.
+
+##### Discovery Order
+
+1. Current directory: check `architect.config.ts`, then `.js`
+2. Walk up to repo root (`.git` folder), checking each directory
+3. Fall back to libar-generic preset (3 categories, `@architect-` prefix)
+
+##### Config File Format
+
+```typescript
+// architect.config.ts
+import { defineConfig } from '@libar-dev/architect/config';
+
+export default defineConfig({
+  preset: 'libar-generic',
+  sources: {
+    typescript: ['src/**/*.ts'],
+    stubs: ['architect/stubs/**/*.ts'],
+    features: ['architect/specs/*.feature'],
+  },
+  output: {
+    directory: 'docs-generated',
+    overwrite: true,
+  },
+});
+```
+
+##### Sources Configuration
+
+| Field        | Type       | Description                                          |
+| ------------ | ---------- | ---------------------------------------------------- |
+| `typescript` | `string[]` | Glob patterns for TypeScript source files (required) |
+| `features`   | `string[]` | Glob patterns for Gherkin feature files              |
+| `stubs`      | `string[]` | Glob patterns for design stub files                  |
+| `exclude`    | `string[]` | Glob patterns to exclude from all scanning           |
+
+Stubs are merged into TypeScript sources at resolution time. No parent directory traversal (`..`) is allowed in globs.
+
+##### Output Configuration
+
+| Field       | Type      | Default               | Description                         |
+| ----------- | --------- | --------------------- | ----------------------------------- |
+| `directory` | `string`  | `'docs/architecture'` | Output directory for generated docs |
+| `overwrite` | `boolean` | `false`               | Overwrite existing files            |
+
+##### Generator Overrides
+
+Some generators need different sources than the base config. Use `generatorOverrides` for per-generator customization:
+
+```typescript
+export default defineConfig({
+  preset: 'libar-generic',
+  sources: {
+    typescript: ['src/**/*.ts'],
+    features: ['architect/specs/*.feature'],
+  },
+  output: { directory: 'docs-generated', overwrite: true },
+  generatorOverrides: {
+    changelog: {
+      additionalFeatures: ['architect/decisions/*.feature'],
+    },
+    'doc-from-decision': {
+      replaceFeatures: ['architect/decisions/*.feature'],
+    },
+  },
+});
+```
+
+| Override Field       | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `additionalFeatures` | Feature globs appended to base features              |
+| `additionalInput`    | TypeScript globs appended to base TypeScript sources |
+| `replaceFeatures`    | Feature globs used INSTEAD of base features          |
+| `outputDirectory`    | Override output directory for this generator         |
+
+**Constraint:** `replaceFeatures` and `additionalFeatures` are mutually exclusive when both are non-empty.
+
+#### Monorepo Setup
+
+```my-monorepo/ architect.config.ts          # Repo-level: ddd-es-cqrs   packages/     my-package/       architect.config.ts      # Package-level: libar-generic
+
+```
+
+CLI tools use the nearest config file to the working directory. Each package can have its own preset and source globs.
+
+#### Custom Configuration
+
+##### Custom Tag Prefix
+
+Keep a preset's taxonomy but change the prefix:
+
+```typescript
+export default defineConfig({
+  preset: 'libar-generic',
+  tagPrefix: '@team-',
+  fileOptInTag: '@team',
+  sources: { typescript: ['src/**/*.ts'] },
+});
+
+// Your annotations:
+// /** @team */
+// /** @team-pattern DualSourceExtractor */
+// /** @team-core */
+```
+
+##### Custom Categories
+
+Define your own taxonomy:
+
+```typescript
+export default defineConfig({
+  tagPrefix: '@architect-',
+  fileOptInTag: '@architect',
+  categories: [
+    { tag: 'scanner', domain: 'Scanner', priority: 1, description: 'File scanning', aliases: [] },
+    {
+      tag: 'extractor',
+      domain: 'Extractor',
+      priority: 2,
+      description: 'Pattern extraction',
+      aliases: [],
+    },
+    {
+      tag: 'generator',
+      domain: 'Generator',
+      priority: 3,
+      description: 'Doc generation',
+      aliases: [],
+    },
+  ],
+  sources: { typescript: ['src/**/*.ts'] },
+});
+```
+
+#### Programmatic Config Loading
+
+For tools that need to load configuration files:
+
+```typescript
+import { loadProjectConfig } from '@libar-dev/architect/config';
+
+const result = await loadProjectConfig(process.cwd());
+
+if (!result.ok) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+const resolved = result.value;
+// resolved.instance    - ArchitectInstance (registry + regexBuilders)
+// resolved.project     - ResolvedProjectConfig (sources, output, generators)
+// resolved.isDefault   - true if no config file found
+// resolved.configPath  - config file path (if found)
+```
+
+For per-generator source resolution:
+
+```typescript
+import { mergeSourcesForGenerator } from '@libar-dev/architect/config';
+
+const effectiveSources = mergeSourcesForGenerator(
+  resolved.project.sources,
+  'changelog',
+  resolved.project.generatorOverrides
+);
+// effectiveSources.typescript - merged TypeScript globs
+// effectiveSources.features   - merged or replaced feature globs
+```

package/docs-live/_claude-md/configuration/configuration-overview.md

@@ -0,0 +1,37 @@
+### Configuration Overview
+
+**How do I configure the tool?** Configuration is the entry boundary — it transforms a user-authored `architect.config.ts` file into a fully resolved `ArchitectInstance` that powers the entire pipeline. The flow is: `defineConfig()` provides type-safe authoring (Vite convention, zero validation), `ConfigLoader` discovers and loads the file, `ProjectConfigSchema` validates via Zod, `ConfigResolver` applies defaults and merges stubs into sources, and `ArchitectFactory` builds the final instance with `TagRegistry` and `RegexBuilders`. Two presets define escalating taxonomy complexity — from 3 categories (`libar-generic`) to 21 (`ddd-es-cqrs`). `SourceMerger` computes per-generator source overrides, enabling generators like changelog to pull from different feature sets than the base config.
+
+#### Key Invariants
+
+- Preset-based taxonomy: `libar-generic` (3 categories, `@architect-`) and `ddd-es-cqrs` (21 categories, full DDD). Presets replace base categories entirely — they define prefix, categories, and metadata tags as a unit
+- Resolution pipeline: defineConfig() → ConfigLoader → ProjectConfigSchema (Zod) → ConfigResolver → ArchitectFactory → ArchitectInstance. Each stage has a single responsibility
+- Stubs merged at resolution time: Stub directory globs are appended to typescript sources, making stubs transparent to the downstream pipeline
+- Source override composition: SourceMerger applies per-generator overrides (`replaceFeatures`, `additionalFeatures`, `additionalInput`) to base sources. Exclude is always inherited from base
+
+**Components:** Config (WorkflowLoader, ConfigurationTypes, ConfigResolver, RegexBuilders, ProjectConfigTypes, ProjectConfigSchema, ConfigurationPresets, SourceMerger, ArchitectFactory, DefineConfig, ConfigurationDefaults, ConfigLoader)
+
+#### API Types
+
+| Type                    | Kind      |
+| ----------------------- | --------- |
+| ArchitectConfig         | interface |
+| ArchitectInstance       | interface |
+| RegexBuilders           | interface |
+| ArchitectProjectConfig  | interface |
+| SourcesConfig           | interface |
+| OutputConfig            | interface |
+| GeneratorSourceOverride | interface |
+| ResolvedProjectConfig   | interface |
+| ResolvedSourcesConfig   | interface |
+| CreateArchitectOptions  | interface |
+| ConfigDiscoveryResult   | interface |
+| ConfigLoadError         | interface |
+| ResolvedConfig          | type      |
+| PresetName              | type      |
+| ConfigLoadResult        | type      |
+| createRegexBuilders     | function  |
+| createArchitect         | function  |
+| findConfigFile          | function  |
+| loadConfig              | function  |
+| formatConfigError       | function  |

package/docs-live/_claude-md/core-types/core-types-overview.md

@@ -0,0 +1,20 @@
+### CoreTypes Overview
+
+**What foundational types exist?** CoreTypes provides the foundational type system used across all other areas. Three pillars enforce discipline at compile time: the Result monad replaces try/catch with explicit error handling — functions return `Result.ok(value)` or `Result.err(error)` instead of throwing. The DocError discriminated union provides structured error context with type, file, line, and reason fields, enabling exhaustive pattern matching in error handlers. Branded types create nominal typing from structural TypeScript — `PatternId`, `CategoryName`, and `SourceFilePath` are compile-time distinct despite all being strings. String utilities handle slugification and case conversion with acronym-aware title casing.
+
+#### Key Invariants
+
+- Result over try/catch: All functions return `Result<T, E>` instead of throwing. Compile-time verification that errors are handled. `isOk`/`isErr` type guards enable safe narrowing
+- DocError discriminated union: 12 structured error types with `type` discriminator field. `isDocError` type guard for safe classification. Specialized union aliases (`ScanError`, `ExtractionError`) scope error handling per operation
+- Branded nominal types: `Branded<T, Brand>` creates compile-time distinct types from structural TypeScript. Prevents mixing `PatternId` with `CategoryName` even though both are `string` at runtime
+- String transformation consistency: `slugify` produces URL-safe identifiers, `camelCaseToTitleCase` preserves acronyms (e.g., "APIEndpoint" becomes "API Endpoint"), `toKebabCase` handles consecutive uppercase correctly
+
+**Components:** Other (StringUtils, FileCacheTesting, TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, KebabCaseSlugs, ErrorHandlingUnification)
+
+#### API Types
+
+| Type         | Kind      |
+| ------------ | --------- |
+| BaseDocError | interface |
+| Result       | type      |
+| DocError     | type      |

package/docs-live/_claude-md/data-api/data-api-overview.md

@@ -0,0 +1,39 @@
+### DataAPI Overview
+
+**How do I query process state?** The Data API provides direct terminal access to project state. It replaces reading generated markdown or launching explore agents — targeted queries use 5-10x less context. The `context` command assembles curated bundles tailored to session type (planning, design, implement).
+
+#### Key Invariants
+
+- One-command context assembly: `context <pattern> --session <type>` returns metadata + file paths + dependency status + architecture position in ~1.5KB
+- Session type tailoring: `planning` (~500B, brief + deps), `design` (~1.5KB, spec + stubs + deps), `implement` (deliverables + FSM + tests)
+- Direct API queries replace doc reading: JSON output is 5-10x smaller than generated docs
+
+#### Contents
+
+- [Key Invariants](#key-invariants)
+- [Shared Pipeline Factory Responsibilities](#shared-pipeline-factory-responsibilities)
+- [8-Step Dataset Build Flow](#8-step-dataset-build-flow)
+- [Consumer Architecture and PipelineOptions Differentiation](#consumer-architecture-and-pipelineoptions-differentiation)
+- [API Types](#api-types)
+
+#### 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
+
+#### API Types
+
+| Type                    | Kind      |
+| ----------------------- | --------- |
+| PipelineOptions         | interface |
+| PipelineResult          | interface |
+| MasterDatasetSchema     | const     |
+| StatusGroupsSchema      | const     |
+| StatusCountsSchema      | const     |
+| PhaseGroupSchema        | const     |
+| SourceViewsSchema       | const     |
+| RelationshipEntrySchema | const     |
+| ArchIndexSchema         | const     |

package/docs-live/_claude-md/generation/generation-overview.md

@@ -0,0 +1,30 @@
+### Generation Overview
+
+**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries.
+
+#### Key Invariants
+
+- Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output
+- Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship
+- Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/`
+- Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors
+- RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer
+- Composition order: Reference docs compose four content layers in fixed order. Product area docs compose five layers: intro, conventions, diagrams, shapes, business rules
+- Shape extraction: TypeScript shapes (`interface`, `type`, `enum`, `function`, `const`) are extracted by declaration-level `@architect-shape` tags. Shapes include source text, JSDoc, type parameters, and property documentation
+- Generator registration: Generators self-register via `registerGenerator()`. The orchestrator runs them in registration order. Each generator owns its output files and codec configuration
+
+#### API Types
+
+| Type                     | Kind      |
+| ------------------------ | --------- |
+| RuntimeMasterDataset     | interface |
+| RawDataset               | interface |
+| RenderableDocument       | type      |
+| SectionBlock             | type      |
+| HeadingBlock             | type      |
+| TableBlock               | type      |
+| ListBlock                | type      |
+| CodeBlock                | type      |
+| MermaidBlock             | type      |
+| CollapsibleBlock         | type      |
+| transformToMasterDataset | function  |

package/docs-live/_claude-md/process/process-overview.md

@@ -0,0 +1,127 @@
+### Process Overview
+
+**How does the session workflow work?** Process defines the USDP-inspired session workflow that governs how work moves through the delivery lifecycle. Three session types (planning, design, implementation) have fixed input/output contracts: planning creates roadmap specs from pattern briefs, design produces code stubs and decision records, and implementation writes code against scope-locked specs. Git is the event store — documentation artifacts are projections of annotated source code, not hand-maintained files. The FSM enforces state transitions (roadmap → active → completed) with escalating protection levels, while handoff templates preserve context across LLM session boundaries. ADR-003 established that TypeScript source owns pattern identity; tier 1 specs are ephemeral planning documents that lose value after completion.
+
+#### Key Invariants
+
+- TypeScript source owns pattern identity: `@architect-pattern` in TypeScript defines the pattern. Tier 1 specs are ephemeral working documents
+- 7 canonical product-area values: Annotation, Configuration, Generation, Validation, DataAPI, CoreTypes, Process — reader-facing sections, not source modules
+- Two distinct status domains: Pattern FSM status (4 values) vs. deliverable status (6 values). Never cross domains
+- Session types define capabilities: planning creates specs, design creates stubs, implementation writes code. Each session type has a fixed input/output contract enforced by convention
+
+#### Contents
+
+- [Key Invariants](#key-invariants)
+- [Product area canonical values](#product-area-canonical-values)
+- [ADR category canonical values](#adr-category-canonical-values)
+- [FSM status values and protection levels](#fsm-status-values-and-protection-levels)
+- [Valid FSM transitions](#valid-fsm-transitions)
+- [Tag format types](#tag-format-types)
+- [Source ownership](#source-ownership)
+- [Quarter format convention](#quarter-format-convention)
+- [Canonical phase definitions (6-phase USDP standard)](#canonical-phase-definitions-6-phase-usdp-standard)
+- [Deliverable status canonical values](#deliverable-status-canonical-values)
+
+#### 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       |
+
+**Components:** Other (ADR006SingleReadModelArchitecture, ADR003SourceFirstPatternArchitecture, ADR002GherkinOnlyTesting, ADR001TaxonomyCanonicalValues, ValidatorReadModelConsolidation, StepDefinitionCompletion, SessionFileCleanup, ProcessAPILayeredExtraction, OrchestratorPipelineFactoryMigration, MvpWorkflowImplementation, LivingRoadmapCLI, EffortVarianceTracking, ConfigBasedWorkflowDefinition, CliBehaviorTesting, SessionHandoffs, SessionFileLifecycle)

package/docs-live/_claude-md/validation/process-guard.md

@@ -0,0 +1,185 @@
+### Process Guard Reference
+
+#### 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 |
+
+#### CLI Usage
+
+```bash
+architect-guard [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
+architect-guard --staged                        # Pre-commit hook (recommended)
+architect-guard --all --strict                  # CI pipeline with strict mode
+architect-guard --file specs/my-feature.feature # Validate specific file
+architect-guard --staged --show-state           # Debug: see derived state
+architect-guard --staged --ignore-session       # Override session scope
+```
+
+#### Pre-commit Setup
+
+Configure Process Guard as a pre-commit hook using Husky.
+
+```bash
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx architect-guard --staged
+```
+
+##### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "lint:process": "architect-guard --staged",
+    "lint:process:ci": "architect-guard --all --strict"
+  }
+}
+```
+
+#### Programmatic API
+
+Use Process Guard programmatically for custom validation workflows.
+
+```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));
+  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         |
+| Validate | validateChanges(input)   | Run all validation rules          |
+| Results  | hasErrors(result)        | Check for blocking errors         |
+| Results  | summarizeResult(result)  | Human-readable summary            |
+
+#### Architecture
+
+Process Guard uses the Decider pattern: pure functions with no I/O.
+
+#### ProcessGuardDecider - Pure Validation Logic
+
+#### completed-protection
+
+**Invariant:** Completed specs are immutable without an explicit unlock reason. The unlock reason must be at least 10 characters and cannot be a placeholder.
+
+| Situation                  | Solution                           | Example                                            |
+| -------------------------- | ---------------------------------- | -------------------------------------------------- |
+| Fix typo in completed spec | Add unlock reason tag              | `@architect-unlock-reason:Fix-typo-in-FSM-diagram` |
+| Spec needs rework          | Create new spec instead            | New feature file with `roadmap` status             |
+| Legacy import              | Multiple transitions in one commit | Set `roadmap` then `completed`                     |
+
+#### invalid-status-transition
+
+**Invariant:** Status transitions must follow the PDR-005 FSM path. The only valid paths are: roadmap to active, roadmap to deferred, active to completed, active to roadmap, deferred to roadmap.
+
+| Attempted             | Why Invalid                  | Valid Path                                 |
+| --------------------- | ---------------------------- | ------------------------------------------ |
+| roadmap to completed  | Must go through active       | roadmap to active to completed             |
+| deferred to active    | Must return to roadmap first | deferred to roadmap to active              |
+| deferred to completed | Cannot skip two states       | deferred to roadmap to active to completed |
+
+#### scope-creep
+
+**Invariant:** Active specs cannot add new deliverables. Scope is locked when status transitions to `active`.
+
+| Situation                             | Solution                | Example                                                        |
+| ------------------------------------- | ----------------------- | -------------------------------------------------------------- |
+| Need new deliverable                  | Revert to roadmap first | Change status to roadmap, add deliverable, then back to active |
+| Discovered work during implementation | Create new spec         | New feature file for the discovered work                       |
+
+#### session-scope
+
+**Invariant:** Files outside the active session scope trigger warnings to prevent accidental cross-session modifications.
+
+#### session-excluded
+
+**Invariant:** Files explicitly excluded from a session cannot be modified in that session. This is a hard error, not a warning.
+
+#### deliverable-removed
+
+**Invariant:** Removing a deliverable from an active spec triggers a warning to ensure the removal is intentional and documented.