@libar-dev/architect 1.0.0-pre.3

package/docs-live/reference/SESSION-WORKFLOW-GUIDE.md

@@ -0,0 +1,384 @@
+# Session Workflow Guide
+
+**Purpose:** Reference document: Session Workflow Guide
+**Detail Level:** Full reference
+
+---
+
+## Session Decision Tree
+
+Use this flowchart to determine which session type to run.
+
+```mermaid
+graph TD
+    A[Starting from pattern brief?] -->|Yes| B[Need code stubs now?]
+    A -->|No| C[Ready to code?]
+    B -->|Yes| D[Planning + Design Session]
+    B -->|No| E[Planning Session]
+    C -->|Yes| F[Complex decisions?]
+    C -->|No| E
+    F -->|Yes| G[Design Session]
+    F -->|No| H[Implementation Session]
+
+    style D fill:#e1f5fe
+    style E fill:#e8f5e9
+    style G fill:#fff3e0
+    style H fill:#fce4ec
+```
+
+## Session Type Contracts
+
+| 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`                    |
+
+---
+
+## Implementation Execution Order
+
+Implementation sessions MUST follow this strict 5-step sequence. Skipping steps causes Process Guard rejection at commit time.
+
+1. **Transition to `active` FIRST** (before any code changes)
+2. **Create executable spec stubs** (if `@architect-executable-specs` present)
+3. **For each deliverable:** implement, test, update status to `complete`
+4. **Transition to `completed`** (only when ALL deliverables done)
+5. **Regenerate docs:** `pnpm docs:all`
+
+### Implementation Do NOT
+
+| Do NOT                              | Why                                     |
+| ----------------------------------- | --------------------------------------- |
+| Add new deliverables to active spec | Scope-locked state prevents scope creep |
+| Mark completed with incomplete work | Hard-locked state cannot be undone      |
+| Skip FSM transitions                | Process Guard will reject               |
+| Edit generated docs directly        | Regenerate from source                  |
+
+---
+
+## 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
+```
+
+### Planning Checklist
+
+- [ ] **Extract metadata** from pattern brief: phase, dependencies, status
+- [ ] **Create spec file** at `{specs-directory}/{product-area}/{pattern}.feature`
+- [ ] **Structure the feature** with Problem/Solution, tags, deliverables table
+- [ ] **Convert constraints to Rule: blocks** with Invariant/Rationale
+- [ ] **Add scenarios** per Rule: 1 happy-path + 1 validation minimum
+- [ ] **Set executable specs location** via `@architect-executable-specs` tag
+
+### Planning Do NOT
+
+- Create `.ts` implementation files
+- Transition to `active`
+- Ask "Ready to implement?"
+
+---
+
+## 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
+```
+
+### When to Use Design Sessions
+
+| Use Design Session         | Skip Design Session |
+| -------------------------- | ------------------- |
+| Multiple valid approaches  | Single obvious path |
+| New patterns/capabilities  | Bug fix             |
+| Cross-context coordination | Clear requirements  |
+
+### Design Checklist
+
+- [ ] **Record decisions** as PDR `.feature` files in `architect/decisions/`
+- [ ] **Document options** with at least 2-3 approaches and pros/cons
+- [ ] **Get approval** from user on recommended approach
+- [ ] **Create code stubs** in `architect/stubs/{pattern-name}/`
+- [ ] **Verify stub identifier spelling** before committing
+- [ ] **List canonical helpers** in `@architect-uses` tags
+
+### Design Do NOT
+
+- Create markdown design documents (use decision specs instead)
+- Create implementation plans
+- Transition spec to `active`
+- Write full implementations (stubs only)
+
+---
+
+## 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        |
+
+---
+
+## Handoff Documentation
+
+For multi-session work, capture state at session boundaries using the Process Data API.
+
+```bash
+pnpm architect:query -- handoff --pattern <PatternName>
+pnpm architect:query -- handoff --pattern <PatternName> --git   # include recent commits
+```
+
+---
+
+## 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           |
+
+---
+
+## Behavior Specifications
+
+### SessionGuidesModuleSource
+
+[View SessionGuidesModuleSource source](architect/specs/session-guides-module-source.feature)
+
+**Problem:**
+CLAUDE.md contains a "Session Workflows" section (~160 lines) that is hand-maintained
+with no link to any annotated source. Three hand-written files in `_claude-md/workflow/`
+(session-workflows.md, session-details.md, fsm-handoff.md) are equally opaque: no
+machine-readable origin, no regeneration from source annotations.
+
+The prior plan proposed tagging ADR-001, ADR-003, and PDR-001 with `@architect-claude-module`
+to make them the source for generated workflow modules. Design analysis revealed this is
+fundamentally flawed: `claude-module` is a file-level tag that pulls ALL Rules from a file,
+but most Rules in those decision specs are irrelevant to session workflows (ADR-001 has 9
+Rules, only 2-3 are workflow-relevant; PDR-001 has 7 Rules about CLI implementation
+decisions, not workflow guidance).
+
+**Solution:**
+This spec file itself becomes the annotated source for session workflow content.
+Session workflow invariants are captured as Rule: blocks here, covering session type
+contracts, FSM protection, execution order, error recovery, and handoff patterns.
+
+Once ClaudeModuleGeneration (Phase 25) ships, adding `@architect-claude-module` and
+`@architect-claude-section:workflow` tags to this spec will cause the codec to produce
+`_claude-md/workflow/` modules automatically. The hand-written files are then deleted
+and the CLAUDE.md section becomes a generated include.
+
+Retain `docs/SESSION-GUIDES.md` (389 lines) as the authoritative public human reference
+deployed to libar.dev. It serves developers with comprehensive checklists and full CLI
+examples — content that cannot be expressed as compact invariants.
+
+Three-layer architecture after Phase 39:
+
+| Layer | Location | Content | Maintenance |
+| Public human reference | docs/SESSION-GUIDES.md | Full checklists, CLI examples, decision trees | Manual (editorial) |
+| Compact AI context | \_claude-md/workflow/ | Invariants, session contracts, FSM reference | Generated from this spec |
+| Machine-queryable source | Process Data API | Rules from this spec via `rules` command | Derived from annotations |
+
+**Why It Matters:**
+| Benefit | How |
+| No CLAUDE.md drift | Session workflow section generated, not hand-authored |
+| Single annotated source | This spec owns all session workflow invariants |
+| Correct audience alignment | Public guide stays in docs/, AI context in \_claude-md/ |
+| Process API coverage | Session workflow content queryable via `pnpm process:query -- rules` |
+| Immediately useful | Rule: blocks are queryable today, generation follows when Phase 25 ships |
+
+**Design Session Findings (2026-03-05):**
+| Finding | Impact |
+| claude-module is file-level, not Rule-level | Cannot selectively tag individual Rules in ADR/PDR files |
+| ADR-001 has 9 Rules, only 2-3 workflow-relevant | Tagging ADR-001 would create noisy, diluted context |
+| PDR-001 Rules are CLI implementation decisions | Not session workflow guidance, wrong audience |
+| Phase 25 claude-section enum lacks workflow value | Must add workflow to enum before annotation |
+| Self-referential spec is correct source | This spec captures invariants, SESSION-GUIDES.md has editorial content |
+
+<details>
+<summary>SESSION-GUIDES.md is the authoritative public human reference (2 scenarios)</summary>
+
+#### SESSION-GUIDES.md is the authoritative public human reference
+
+**Invariant:** `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or replaced with a redirect. Its comprehensive checklists, CLI command examples, and session decision trees serve developers on libar.dev.
+
+**Rationale:** Session workflow guidance requires two formats for two audiences. Public developers need comprehensive checklists with full examples. AI sessions need compact invariants they can apply without reading 389 lines.
+
+**Verified by:**
+
+- SESSION-GUIDES.md exists after Phase 39 completes
+- No broken links after Phase 39
+- SESSION-GUIDES.md exists after Phase 39
+
+</details>
+
+<details>
+<summary>CLAUDE.md session workflow content is derived, not hand-authored (1 scenarios)</summary>
+
+#### CLAUDE.md session workflow content is derived, not hand-authored
+
+**Invariant:** After Phase 39 generation deliverables complete, the "Session Workflows" section in CLAUDE.md contains no manually-authored content. It is composed from generated `_claude-md/workflow/` modules.
+
+**Rationale:** A hand-maintained CLAUDE.md session section creates two copies of session workflow guidance with no synchronization mechanism. Regeneration from annotated source eliminates drift.
+
+**Verified by:**
+
+- CLAUDE.md session section is a generated module reference
+
+</details>
+
+<details>
+<summary>Session type determines artifacts and FSM changes (1 scenarios)</summary>
+
+#### Session type determines artifacts and FSM changes
+
+**Invariant:** Four session types exist, each with defined input, output, and FSM impact. Mixing outputs across session types (e.g., writing code in a planning session) violates session discipline.
+
+**Rationale:** Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types.
+
+**Verified by:**
+
+- Session type contracts are enforced
+
+</details>
+
+<details>
+<summary>Planning sessions produce roadmap specs only (1 scenarios)</summary>
+
+#### Planning sessions produce roadmap specs only
+
+**Invariant:** A planning session creates a roadmap spec with metadata, deliverables table, Rule: blocks with invariants, and scenarios. It must not produce implementation code, transition to active, or prompt for implementation readiness.
+
+**Rationale:** Planning is the cheapest session type — it produces .feature file edits, no compilation needed. Mixing implementation into planning defeats the cost advantage and introduces untested code without a locked scope.
+
+**Verified by:**
+
+- Planning session output constraints
+
+</details>
+
+<details>
+<summary>Design sessions produce decisions and stubs only (1 scenarios)</summary>
+
+#### Design sessions produce decisions and stubs only
+
+**Invariant:** A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage.
+
+**Rationale:** Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts.
+
+**Verified by:**
+
+- Design session output constraints
+
+</details>
+
+<details>
+<summary>Implementation sessions follow FSM-enforced execution order (1 scenarios)</summary>
+
+#### Implementation sessions follow FSM-enforced execution order
+
+**Invariant:** Implementation sessions must follow a strict 5-step execution order. Transition to active must happen before any code changes. Transition to completed must happen only when ALL deliverables are done. Skipping steps causes Process Guard rejection at commit time.
+
+**Rationale:** The execution order ensures FSM state accurately reflects work state at every point. Writing code before transitioning to active means Process Guard sees changes to a roadmap spec (no scope protection). Marking completed with incomplete work creates a hard-locked state that requires unlock-reason to fix.
+
+**Verified by:**
+
+- Implementation execution order is enforced
+- Implementation execution order is enforced
+
+  Execution order:
+  1. Transition to active FIRST (before any code changes)
+  2. Create executable spec stubs (if @architect-executable-specs present)
+  3. For each deliverable: implement
+
+- test
+- update status to complete 4. Transition to completed (only when ALL deliverables done) 5. Regenerate docs: pnpm docs:all
+
+</details>
+
+<details>
+<summary>FSM errors have documented fixes (1 scenarios)</summary>
+
+#### FSM errors have documented fixes
+
+**Invariant:** Every Process Guard error code has a defined cause and fix. The error codes, causes, and fixes form a closed set — no undocumented error states exist.
+
+**Rationale:** Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity.
+
+**Verified by:**
+
+- All FSM errors have documented recovery paths
+- All FSM errors have documented recovery paths
+
+  Escape hatches for exceptional situations:
+
+</details>
+
+<details>
+<summary>Handoff captures session-end state for continuity (1 scenarios)</summary>
+
+#### Handoff captures session-end state for continuity
+
+**Invariant:** Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes.
+
+**Rationale:** Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes.
+
+**Verified by:**
+
+- Handoff output reflects annotation state
+- Handoff output reflects annotation state
+
+  Generate handoff via: pnpm process:query -- handoff --pattern PatternName
+  Options: --git (include recent commits)
+
+- --session (session identifier)
+
+  Output includes: deliverable statuses
+
+- blockers
+- modification date
+- and next
+  steps — all derived from current annotation state.
+
+</details>
+
+<details>
+<summary>ClaudeModuleGeneration is the generation mechanism (1 scenarios)</summary>
+
+#### ClaudeModuleGeneration is the generation mechanism
+
+**Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation.
+
+**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet.
+
+**Prerequisite:** Phase 25 must add `workflow` to the `claude-section` enum
+values (currently: core, process, testing, infrastructure).
+
+**Verified by:**
+
+- Generated modules replace hand-written workflow files
+
+</details>
+
+---

package/docs-live/reference/VALIDATION-TOOLS-GUIDE.md

@@ -0,0 +1,263 @@
+# Validation Tools Guide
+
+**Purpose:** Reference document: Validation Tools Guide
+**Detail Level:** Full reference
+
+---
+
+## Which Command Do I Run?
+
+```text
+Need to check annotation quality?
+  Yes -> architect-lint-patterns
+
+Need to check vitest-cucumber compatibility?
+  Yes -> architect-lint-steps
+
+Need FSM workflow validation?
+  Yes -> architect-guard
+
+Need cross-source or DoD validation?
+  Yes -> architect-validate
+
+Running pre-commit hook?
+  architect-guard --staged (default)
+```
+
+## Command Summary
+
+| Command                   | Purpose                           | When to Use                                   |
+| ------------------------- | --------------------------------- | --------------------------------------------- |
+| `architect-lint-patterns` | Annotation quality                | Ensure patterns have required tags            |
+| `architect-lint-steps`    | vitest-cucumber compatibility     | After writing/modifying feature or step files |
+| `architect-guard`         | FSM workflow enforcement          | Pre-commit hooks, CI pipelines                |
+| `architect-validate`      | Cross-source + DoD + anti-pattern | Release validation, comprehensive             |
+
+---
+
+## architect-lint-patterns
+
+Validates `@<prefix>-*` annotation quality in TypeScript files.
+
+```bash
+npx architect-lint-patterns -i "src/**/*.ts"
+npx architect-lint-patterns -i "src/**/*.ts" --strict   # CI
+```
+
+### CLI Flags
+
+| Flag                     | Short | Description                         | Default  |
+| ------------------------ | ----- | ----------------------------------- | -------- |
+| `--input <pattern>`      | `-i`  | Glob pattern (required, repeatable) | required |
+| `--exclude <pattern>`    | `-e`  | Exclude pattern (repeatable)        | -        |
+| `--base-dir <dir>`       | `-b`  | Base directory                      | cwd      |
+| `--strict`               |       | Treat warnings as errors            | false    |
+| `--format <type>`        | `-f`  | Output: `pretty` or `json`          | `pretty` |
+| `--quiet`                | `-q`  | Only show errors                    | false    |
+| `--min-severity <level>` |       | `error`, `warning`, `info`          | -        |
+
+### Rules
+
+| Rule                             | Severity | What It Checks                                     |
+| -------------------------------- | -------- | -------------------------------------------------- |
+| `missing-pattern-name`           | error    | Must have `@<prefix>-pattern`                      |
+| `invalid-status`                 | error    | Status must be valid FSM value                     |
+| `tautological-description`       | error    | Description cannot just repeat name                |
+| `pattern-conflict-in-implements` | error    | Pattern cannot implement itself (circular ref)     |
+| `missing-relationship-target`    | warning  | Relationship targets must reference known patterns |
+| `missing-status`                 | warning  | Should have status tag                             |
+| `missing-when-to-use`            | warning  | Should have "When to Use" section                  |
+| `missing-relationships`          | info     | Consider adding uses/used-by                       |
+
+---
+
+## architect-lint-steps
+
+Static analyzer for vitest-cucumber feature/step compatibility. Catches mismatches that cause cryptic runtime failures.
+
+```bash
+pnpm lint:steps              # Standard check
+pnpm lint:steps --strict     # CI
+```
+
+12 rules across 3 categories (9 error, 3 warning).
+
+### Feature File Rules
+
+| Rule ID                  | Severity | What It Catches                                                           |
+| ------------------------ | -------- | ------------------------------------------------------------------------- |
+| `hash-in-description`    | error    | `#` at line start inside `"""` block in description -- terminates parsing |
+| `keyword-in-description` | error    | Description line starting with Given/When/Then/And/But -- breaks parser   |
+| `duplicate-and-step`     | error    | Multiple `And` steps with identical text in same scenario                 |
+| `dollar-in-step-text`    | warning  | `$` in step text (outside quotes) causes matching issues                  |
+| `hash-in-step-text`      | warning  | Mid-line `#` in step text (outside quotes) silently truncates the step    |
+
+### Step Definition Rules
+
+| Rule ID                   | Severity | What It Catches                                             |
+| ------------------------- | -------- | ----------------------------------------------------------- |
+| `regex-step-pattern`      | error    | Regex pattern in step registration -- use string patterns   |
+| `unsupported-phrase-type` | error    | `{phrase}` in step string -- use `{string}` instead         |
+| `repeated-step-pattern`   | error    | Same pattern registered twice -- second silently overwrites |
+
+### Cross-File Rules
+
+| Rule ID                            | Severity | What It Catches                                                      |
+| ---------------------------------- | -------- | -------------------------------------------------------------------- |
+| `scenario-outline-function-params` | error    | Function params in ScenarioOutline callback (should use variables)   |
+| `missing-and-destructuring`        | error    | Feature has `And` steps but step file does not destructure `And`     |
+| `missing-rule-wrapper`             | error    | Feature has `Rule:` blocks but step file does not destructure `Rule` |
+| `outline-quoted-values`            | warning  | Quoted values in Outline steps instead of `<placeholder>` syntax     |
+
+### CLI Reference
+
+| Flag               | Short | Description                | Default  |
+| ------------------ | ----- | -------------------------- | -------- |
+| `--strict`         |       | Treat warnings as errors   | false    |
+| `--format <type>`  |       | Output: `pretty` or `json` | `pretty` |
+| `--base-dir <dir>` | `-b`  | Base directory for paths   | cwd      |
+
+---
+
+## architect-guard
+
+FSM validation for delivery workflow. Enforces status transitions and protection levels.
+
+```bash
+npx architect-guard --staged          # Pre-commit (default)
+npx architect-guard --all --strict    # CI pipeline
+```
+
+**What it validates:**
+
+- Status transitions follow FSM (`roadmap` -> `active` -> `completed`)
+- Completed specs require unlock reason to modify
+- Active specs cannot add new deliverables (scope protection)
+- Session scope rules (optional)
+
+For detailed rules, escape hatches, and error fixes, see the [Process Guard Reference](PROCESS-GUARD-REFERENCE.md).
+
+---
+
+## architect-validate
+
+Cross-source validator combining multiple checks.
+
+```bash
+npx architect-validate \
+  -i "src/**/*.ts" \
+  -F "specs/**/*.feature" \
+  --dod \
+  --anti-patterns
+```
+
+### CLI Flags
+
+| Flag              | Short | Description                                      | Default  |
+| ----------------- | ----- | ------------------------------------------------ | -------- |
+| `--input`         | `-i`  | Glob for TypeScript files (required, repeatable) | required |
+| `--features`      | `-F`  | Glob for Gherkin files (required, repeatable)    | required |
+| `--exclude`       | `-e`  | Exclude pattern (repeatable)                     | -        |
+| `--base-dir`      | `-b`  | Base directory                                   | cwd      |
+| `--strict`        |       | Treat warnings as errors (exit 2)                | false    |
+| `--verbose`       |       | Show info-level messages                         | false    |
+| `--format`        | `-f`  | Output: `pretty` or `json`                       | `pretty` |
+| `--dod`           |       | Enable Definition of Done validation             | false    |
+| `--anti-patterns` |       | Enable anti-pattern detection                    | false    |
+
+### Anti-Pattern Detection
+
+Detects process metadata tags that belong in feature files but appear in TypeScript code:
+
+| Tag Suffix (Feature-Only) | What It Tracks       |
+| ------------------------- | -------------------- |
+| `@<prefix>-quarter`       | Timeline metadata    |
+| `@<prefix>-team`          | Ownership metadata   |
+| `@<prefix>-effort`        | Estimation metadata  |
+| `@<prefix>-completed`     | Completion timestamp |
+
+Additional checks:
+
+| ID                | Severity | What It Detects                     |
+| ----------------- | -------- | ----------------------------------- |
+| `process-in-code` | error    | Feature-only tags found in TS code  |
+| `magic-comments`  | warning  | Generator hints in feature files    |
+| `scenario-bloat`  | warning  | Too many scenarios per feature file |
+| `mega-feature`    | warning  | Feature file exceeds line threshold |
+
+### DoD Validation
+
+For patterns with `completed` status, checks:
+
+- All deliverables are in a terminal state (`complete`, `n/a`, or `superseded`)
+- At least one `@acceptance-criteria` scenario exists in the spec
+
+---
+
+## CI/CD Integration
+
+### Recommended package.json Scripts
+
+```json
+{
+  "scripts": {
+    "lint:patterns": "architect-lint-patterns -i 'src/**/*.ts'",
+    "lint:steps": "architect-lint-steps",
+    "lint:steps:ci": "architect-lint-steps --strict",
+    "lint:process": "architect-guard --staged",
+    "lint:process:ci": "architect-guard --all --strict",
+    "validate:all": "architect-validate -i 'src/**/*.ts' -F 'specs/**/*.feature' --dod --anti-patterns"
+  }
+}
+```
+
+### Pre-commit Hook
+
+```bash
+npx architect-guard --staged
+```
+
+### GitHub Actions
+
+```yaml
+- name: Lint annotations
+  run: npx architect-lint-patterns -i "src/**/*.ts" --strict
+
+- name: Lint steps
+  run: npx architect-lint-steps --strict
+
+- name: Validate patterns
+  run: npx architect-validate -i "src/**/*.ts" -F "specs/**/*.feature" --dod --anti-patterns
+```
+
+---
+
+## Exit Codes
+
+| Code | architect-lint-patterns / architect-lint-steps / architect-guard | architect-validate                  |
+| ---- | ---------------------------------------------------------------- | ----------------------------------- |
+| `0`  | No errors (warnings allowed unless --strict)                     | No issues found                     |
+| `1`  | Errors found (or warnings with --strict)                         | Errors found                        |
+| `2`  | --                                                               | Warnings found (with --strict only) |
+
+---
+
+## Programmatic API
+
+All validation tools expose programmatic APIs:
+
+```typescript
+// Pattern linting
+import { lintFiles, hasFailures } from '@libar-dev/architect/lint';
+
+// Step linting
+import { runStepLint, STEP_LINT_RULES } from '@libar-dev/architect/lint';
+
+// Process guard
+import { deriveProcessState, validateChanges } from '@libar-dev/architect/lint';
+
+// Anti-patterns and DoD
+import { detectAntiPatterns, validateDoD } from '@libar-dev/architect/validation';
+```
+
+---

package/docs-live/taxonomy/categories.md

@@ -0,0 +1,33 @@
+# Category Reference
+
+**Purpose:** Complete category definitions with aliases and domain groupings
+
+---
+
+## Category Definitions
+
+3 categories sorted by priority.
+
+| Tag     | Domain         | Priority | Description    | Aliases          |
+| ------- | -------------- | -------- | -------------- | ---------------- |
+| `core`  | Core           | 1        | Core patterns  | -                |
+| `api`   | API            | 2        | Public APIs    | -                |
+| `infra` | Infrastructure | 3        | Infrastructure | `infrastructure` |
+
+## Categories by Domain
+
+### Core
+
+`core`
+
+### API
+
+`api`
+
+### Infrastructure
+
+`infra`
+
+---
+
+[Back to Taxonomy Reference](../TAXONOMY.md)