@libar-dev/architect 1.0.0-pre.3

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

@@ -0,0 +1,37 @@
+### Validation Overview
+
+**How is the workflow enforced?** Validation is the enforcement boundary — it ensures that every change to annotated source files respects the delivery lifecycle rules defined by the FSM, protection levels, and scope constraints. The system operates in three layers: the FSM validator checks status transitions against a 4-state directed graph, the Process Guard orchestrates commit-time validation using a Decider pattern (state derived from annotations, not stored separately), and the lint engine provides pluggable rule execution with pretty and JSON output. Anti-pattern detection enforces dual-source ownership boundaries — `@architect-uses` belongs on TypeScript, `@architect-depends-on` belongs on Gherkin — preventing cross-domain tag confusion that causes documentation drift. Definition of Done validation ensures completed patterns have all deliverables marked done and at least one acceptance-criteria scenario.
+
+#### Key Invariants
+
+- Protection levels: `roadmap`/`deferred` = none (fully editable), `active` = scope-locked (no new deliverables), `completed` = hard-locked (requires `@architect-unlock-reason`)
+- Valid FSM transitions: Only roadmap→active, roadmap→deferred, active→completed, active→roadmap, deferred→roadmap. Completed is terminal
+- Decider pattern: All validation is (state, changes, options) → result. State is derived from annotations, not maintained separately
+- Dual-source ownership: Anti-pattern detection enforces tag boundaries — `uses` on TypeScript (runtime deps), `depends-on`/`quarter`/`team` on Gherkin (planning metadata). Violations are flagged before they cause documentation drift
+
+**Components:** Lint (LintRules, LintEngine, ProcessGuardDecider), Validation (DoDValidator, AntiPatternDetector, FSMValidator, FSMTransitions, FSMStates)
+
+#### API Types
+
+| Type                               | Kind      |
+| ---------------------------------- | --------- |
+| AntiPatternDetectionOptions        | interface |
+| LintRule                           | interface |
+| LintContext                        | interface |
+| ProtectionLevel                    | type      |
+| isDeliverableComplete              | function  |
+| hasAcceptanceCriteria              | function  |
+| extractAcceptanceCriteriaScenarios | function  |
+| validateDoDForPhase                | function  |
+| validateDoD                        | function  |
+| formatDoDSummary                   | function  |
+| detectAntiPatterns                 | function  |
+| detectProcessInCode                | function  |
+| detectMagicComments                | function  |
+| detectScenarioBloat                | function  |
+| detectMegaFeature                  | function  |
+| formatAntiPatternReport            | function  |
+| toValidationIssues                 | function  |
+| filterRulesBySeverity              | function  |
+| isValidTransition                  | function  |
+| getValidTransitionsFrom            | function  |

package/docs-live/_claude-md/validation/validation-tools-guide.md

@@ -0,0 +1,242 @@
+### Validation Tools Guide
+
+#### 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/_claude-md/workflow/session-workflow-guide.md

@@ -0,0 +1,141 @@
+### Session Workflow Guide
+
+#### Session Decision Tree
+
+Use this flowchart to determine which session type to run.
+
+#### 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
+
+| Rule                                                             | Description                                                                                                              |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| SESSION-GUIDES.md is the authoritative public human reference    | **Invariant:** `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or<br> replaced with a redirect. Its...    |
+| CLAUDE.md session workflow content is derived, not hand-authored | **Invariant:** After Phase 39 generation deliverables complete, the "Session<br> Workflows" section in CLAUDE.md...      |
+| Session type determines artifacts and FSM changes                | **Invariant:** Four session types exist, each with defined input, output, and<br> FSM impact. Mixing outputs across...   |
+| Planning sessions produce roadmap specs only                     | **Invariant:** A planning session creates a roadmap spec with metadata, deliverables<br> table, Rule: blocks with...     |
+| Design sessions produce decisions and stubs only                 | **Invariant:** A design session makes architectural decisions and creates code stubs<br> with interfaces. It must not... |
+| Implementation sessions follow FSM-enforced execution order      | **Invariant:** Implementation sessions must follow a strict 5-step execution order.<br> Transition to active must...     |
+| FSM errors have documented fixes                                 | **Invariant:** Every Process Guard error code has a defined cause and fix. The<br> error codes, causes, and fixes...     |
+| Handoff captures session-end state for continuity                | **Invariant:** Multi-session work requires handoff documentation generated from<br> the Process Data API. Handoff...     |
+| ClaudeModuleGeneration is the generation mechanism               | **Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding<br> `@architect-claude-module` and...       |