@libar-dev/architect 1.0.0-pre.3

package/docs-live/TAXONOMY.md

@@ -0,0 +1,202 @@
+# Taxonomy Reference
+
+**Purpose:** Tag taxonomy configuration for code-first documentation
+**Detail Level:** Overview with links to details
+
+---
+
+## Overview
+
+**3 categories** | **60 metadata tags** | **3 aggregation tags**
+
+Current configuration uses `@architect-` prefix with `@architect` file opt-in.
+
+| Component        | Count | Description                          |
+| ---------------- | ----- | ------------------------------------ |
+| Categories       | 3     | Pattern classification by domain     |
+| Metadata Tags    | 60    | Pattern enrichment and relationships |
+| Aggregation Tags | 3     | Document routing                     |
+
+---
+
+## Categories
+
+Domain classifications for organizing patterns by priority.
+
+| Tag     | Domain         | Priority | Description    |
+| ------- | -------------- | -------- | -------------- |
+| `core`  | Core           | 1        | Core patterns  |
+| `api`   | API            | 2        | Public APIs    |
+| `infra` | Infrastructure | 3        | Infrastructure |
+
+[Full category reference](taxonomy/categories.md)
+
+---
+
+## Metadata Tags
+
+Tags for enriching patterns with additional metadata.
+
+### Core Tags
+
+| Tag       | Format       | Purpose                                      | Required | Example                                               |
+| --------- | ------------ | -------------------------------------------- | -------- | ----------------------------------------------------- |
+| `pattern` | value        | Explicit pattern name                        | Yes      | `@architect-pattern CommandOrchestrator`              |
+| `status`  | enum         | Work item lifecycle status (per PDR-005 FSM) | No       | `@architect-status roadmap`                           |
+| `core`    | flag         | Marks as essential/must-know pattern         | No       | `@architect-core`                                     |
+| `usecase` | quoted-value | Use case association                         | No       | `@architect-usecase "When handling command failures"` |
+
+### Relationship Tags
+
+| Tag          | Format | Purpose                                                                    | Required | Example                                                                |
+| ------------ | ------ | -------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
+| `uses`       | csv    | Patterns this depends on                                                   | No       | `@architect-uses CommandBus, EventStore`                               |
+| `used-by`    | csv    | Patterns that depend on this                                               | No       | `@architect-used-by SagaOrchestrator`                                  |
+| `depends-on` | csv    | Roadmap dependencies (pattern or phase names)                              | No       | `@architect-depends-on EventStore, CommandBus`                         |
+| `enables`    | csv    | Patterns this enables                                                      | No       | `@architect-enables SagaOrchestrator, ProjectionBuilder`               |
+| `implements` | csv    | Patterns this code file realizes (realization relationship)                | No       | `@architect-implements EventStoreDurability, IdempotentAppend`         |
+| `extends`    | value  | Base pattern this pattern extends (generalization relationship)            | No       | `@architect-extends ProjectionCategories`                              |
+| `see-also`   | csv    | Related patterns for cross-reference without dependency implication        | No       | `@architect-see-also AgentAsBoundedContext, CrossContextIntegration`   |
+| `api-ref`    | csv    | File paths to implementation APIs (replaces 'See:' Markdown text in Rules) | No       | `@architect-api-ref @libar-dev/platform-core/src/durability/outbox.ts` |
+
+### Timeline Tags
+
+| Tag             | Format | Purpose                                                      | Required | Example                              |
+| --------------- | ------ | ------------------------------------------------------------ | -------- | ------------------------------------ |
+| `phase`         | number | Roadmap phase number (unified across monorepo)               | No       | `@architect-phase 14`                |
+| `release`       | value  | Target release version (semver or vNEXT for unreleased work) | No       | `@architect-release v0.1.0`          |
+| `quarter`       | value  | Delivery quarter for timeline tracking                       | No       | `@architect-quarter Q1-2026`         |
+| `completed`     | value  | Completion date (YYYY-MM-DD format)                          | No       | `@architect-completed 2026-01-08`    |
+| `effort`        | value  | Estimated effort (4h, 2d, 1w format)                         | No       | `@architect-effort 2d`               |
+| `effort-actual` | value  | Actual effort spent (4h, 2d, 1w format)                      | No       | `@architect-effort-actual 3d`        |
+| `team`          | value  | Responsible team assignment                                  | No       | `@architect-team platform`           |
+| `workflow`      | enum   | Workflow discipline for process tracking                     | No       | `@architect-workflow implementation` |
+| `risk`          | enum   | Risk level for planning                                      | No       | `@architect-risk medium`             |
+| `priority`      | enum   | Priority level for roadmap ordering                          | No       | `@architect-priority high`           |
+
+### ADR Tags
+
+| Tag                 | Format | Purpose                                               | Required | Example                                |
+| ------------------- | ------ | ----------------------------------------------------- | -------- | -------------------------------------- |
+| `adr`               | value  | ADR/PDR number for decision tracking                  | No       | `@architect-adr 015`                   |
+| `adr-status`        | enum   | ADR/PDR decision status                               | No       | `@architect-adr-status accepted`       |
+| `adr-category`      | value  | ADR/PDR category (architecture, process, tooling)     | No       | `@architect-adr-category architecture` |
+| `adr-supersedes`    | value  | ADR/PDR number this decision supersedes               | No       | `@architect-adr-supersedes 012`        |
+| `adr-superseded-by` | value  | ADR/PDR number that supersedes this decision          | No       | `@architect-adr-superseded-by 020`     |
+| `adr-theme`         | enum   | Theme grouping for related decisions (from synthesis) | No       | `@architect-adr-theme persistence`     |
+| `adr-layer`         | enum   | Evolutionary layer of the decision                    | No       | `@architect-adr-layer foundation`      |
+
+### Architecture Tags
+
+| Tag            | Format | Purpose                                                           | Required | Example                             |
+| -------------- | ------ | ----------------------------------------------------------------- | -------- | ----------------------------------- |
+| `arch-role`    | enum   | Architectural role for diagram generation (component type)        | No       | `@architect-arch-role projection`   |
+| `arch-context` | value  | Bounded context this component belongs to (for subgraph grouping) | No       | `@architect-arch-context orders`    |
+| `arch-layer`   | enum   | Architectural layer for layered diagrams                          | No       | `@architect-arch-layer application` |
+
+### Other Tags
+
+| Tag                      | Format       | Purpose                                                                    | Required | Example                                                                      |
+| ------------------------ | ------------ | -------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `brief`                  | value        | Path to pattern brief markdown                                             | No       | `@architect-brief docs/briefs/decider-pattern.md`                            |
+| `product-area`           | value        | Product area for PRD grouping                                              | No       | `@architect-product-area PlatformCore`                                       |
+| `user-role`              | value        | Target user persona for this feature                                       | No       | `@architect-user-role Developer`                                             |
+| `business-value`         | value        | Business value statement (hyphenated for tag format)                       | No       | `@architect-business-value eliminates-event-replay-complexity`               |
+| `constraint`             | value        | Technical constraint affecting feature implementation                      | No       | `@architect-constraint requires-convex-backend`                              |
+| `level`                  | enum         | Hierarchy level for epic->phase->task breakdown                            | No       | `@architect-level epic`                                                      |
+| `parent`                 | value        | Parent pattern name in hierarchy (links tasks to phases, phases to epics)  | No       | `@architect-parent AggregateArchitecture`                                    |
+| `title`                  | quoted-value | Human-readable display title (supports quoted values with spaces)          | No       | `@architect-title:"Process Guard Linter"`                                    |
+| `executable-specs`       | csv          | Links roadmap spec to package executable spec locations (PDR-007)          | No       | `@architect-executable-specs platform-decider/tests/features/behavior`       |
+| `roadmap-spec`           | value        | Links package spec back to roadmap pattern for traceability (PDR-007)      | No       | `@architect-roadmap-spec DeciderPattern`                                     |
+| `behavior-file`          | value        | Path to behavior test feature file for traceability                        | No       | `@architect-behavior-file behavior/my-pattern.feature`                       |
+| `discovered-gap`         | value        | Gap identified during session retrospective                                | No       | `@architect-discovered-gap missing-error-handling`                           |
+| `discovered-improvement` | value        | Improvement identified during session retrospective                        | No       | `@architect-discovered-improvement cache-invalidation`                       |
+| `discovered-risk`        | value        | Risk identified during session retrospective                               | No       | `@architect-discovered-risk data-loss-on-migration`                          |
+| `discovered-learning`    | value        | Learning captured during session retrospective                             | No       | `@architect-discovered-learning convex-mutation-limits`                      |
+| `extract-shapes`         | csv          | TypeScript type names to extract from this file for documentation          | No       | `@architect-extract-shapes DeciderInput, ValidationResult, ProcessViolation` |
+| `shape`                  | value        | Marks declaration as documentable shape, optionally with group name        | No       | `@architect-shape api-types`                                                 |
+| `include`                | csv          | Cross-cutting document inclusion for content routing and diagram scoping   | No       | `@architect-include reference-sample,codec-system`                           |
+| `target`                 | value        | Target implementation path for stub files                                  | No       | `@architect-target src/api/stub-resolver.ts`                                 |
+| `since`                  | value        | Design session that created this pattern                                   | No       | `@architect-since DS-A`                                                      |
+| `convention`             | csv          | Convention domains for reference document generation from decision records | No       | `@architect-convention fsm-rules, testing-policy`                            |
+| `claude-module`          | value        | Module identifier for CLAUDE.md module generation (becomes filename)       | No       | `@architect-claude-module process-guard`                                     |
+| `claude-section`         | enum         | Target section directory in \_claude-md/ for module output                 | No       | `@architect-claude-section process`                                          |
+| `claude-tags`            | csv          | Variation filtering tags for modular-claude-md inclusion                   | No       | `@architect-claude-tags core-mandatory, process`                             |
+| `sequence-orchestrator`  | value        | Identifies the coordinator module for sequence diagram generation          | No       | `@architect-sequence-orchestrator:init-cli`                                  |
+| `sequence-step`          | number       | Explicit execution ordering number for sequence diagram steps              | No       | `@architect-sequence-step:1`                                                 |
+| `sequence-module`        | csv          | Maps Rule to deliverable module(s) for sequence diagram participants       | No       | `@architect-sequence-module:detect-context`                                  |
+| `sequence-error`         | flag         | Marks scenario as error/alternative path in sequence diagram               | No       | `@architect-sequence-error`                                                  |
+
+[Full metadata tag reference](taxonomy/metadata-tags.md)
+
+---
+
+## Aggregation Tags
+
+Tags that route patterns to specific aggregated documents.
+
+| Tag        | Target Document | Purpose                                     |
+| ---------- | --------------- | ------------------------------------------- |
+| `overview` | OVERVIEW.md     | Architecture overview patterns              |
+| `decision` | DECISIONS.md    | ADR-style decisions (auto-numbered)         |
+| `intro`    | None            | Package introduction (template placeholder) |
+
+---
+
+## Format Types
+
+How tag values are parsed and validated.
+
+| Format         | Description                         | Example                               |
+| -------------- | ----------------------------------- | ------------------------------------- |
+| `value`        | Simple string value                 | `@architect-pattern MyPattern`        |
+| `enum`         | Constrained to predefined values    | `@architect-status roadmap`           |
+| `quoted-value` | String in quotes (preserves spaces) | `@architect-usecase "When X happens"` |
+| `csv`          | Comma-separated values              | `@architect-uses A, B, C`             |
+| `number`       | Numeric value                       | `@architect-phase 14`                 |
+| `flag`         | Boolean presence (no value)         | `@architect-core`                     |
+
+[Format type details](taxonomy/format-types.md)
+
+---
+
+## Presets
+
+Available configuration presets.
+
+| Preset          | Tag Prefix    | Categories | Use Case                               |
+| --------------- | ------------- | ---------- | -------------------------------------- |
+| `libar-generic` | `@architect-` | 3          | Default preset with @architect- prefix |
+| `ddd-es-cqrs`   | `@architect-` | 21         | Full DDD/ES/CQRS taxonomy              |
+
+---
+
+## Architecture
+
+Taxonomy source files and pipeline flow.
+
+```plaintext
+src/taxonomy/
+├── categories.ts          # Category definitions (21 DDD-ES-CQRS)
+├── format-types.ts        # Format type constants
+├── registry-builder.ts    # Single source of truth builder
+├── status-values.ts       # Status FSM values
+├── generator-options.ts   # Generator option values
+├── hierarchy-levels.ts    # Hierarchy level values
+├── risk-levels.ts         # Risk level values
+└── index.ts               # Barrel export
+```
+
+```mermaid
+graph LR
+    Config[Configuration] --> Scanner[Scanner]
+    Scanner --> Extractor[Extractor]
+    Extractor --> Transformer[Transformer]
+    Transformer --> Codec[Codec]
+    Codec --> Markdown[Markdown]
+
+    Registry[TagRegistry] --> Scanner
+    Registry --> Extractor
+```
+
+---

package/docs-live/VALIDATION-RULES.md

@@ -0,0 +1,119 @@
+# Validation Rules
+
+**Purpose:** Process Guard validation rules and FSM reference
+**Detail Level:** Overview with links to details
+
+---
+
+## Overview
+
+Process Guard validates delivery workflow changes at commit time using a Decider pattern. It enforces the 4-state FSM defined in PDR-005 and prevents common workflow violations.
+
+**6 validation rules** | **4 FSM states** | **3 protection levels**
+
+---
+
+## Validation Rules
+
+Rules are checked in order. Errors block commit; warnings are informational.
+
+| Rule ID                     | Severity | Description                                         |
+| --------------------------- | -------- | --------------------------------------------------- |
+| `completed-protection`      | error    | Completed specs require unlock-reason tag to modify |
+| `invalid-status-transition` | error    | Status transitions must follow FSM path             |
+| `scope-creep`               | error    | Active specs cannot add new deliverables            |
+| `session-scope`             | warning  | File outside session scope                          |
+| `session-excluded`          | error    | File explicitly excluded from session               |
+| `deliverable-removed`       | warning  | Deliverable was removed from spec                   |
+
+[Full error catalog with fix instructions](validation/error-catalog.md)
+
+---
+
+## FSM State Diagram
+
+Valid transitions per PDR-005 MVP Workflow:
+
+```mermaid
+stateDiagram-v2
+    [*] --> roadmap: new pattern
+    roadmap --> active
+    roadmap --> deferred
+    active --> completed
+    active --> roadmap: blocked/regressed
+    deferred --> roadmap
+    completed --> [*]: terminal
+```
+
+**Valid Transitions:**
+
+- `roadmap` -> `active` -> `completed` (normal flow)
+- `active` -> `roadmap` (blocked/regressed)
+- `roadmap` <-> `deferred` (parking)
+
+[Detailed transition matrix](validation/fsm-transitions.md)
+
+---
+
+## Protection Levels
+
+Protection levels determine what modifications are allowed per status.
+
+| Status      | Protection | Can Add Deliverables | Needs Unlock |
+| ----------- | ---------- | -------------------- | ------------ |
+| `roadmap`   | none       | Yes                  | No           |
+| `active`    | scope      | No                   | No           |
+| `completed` | hard       | No                   | Yes          |
+| `deferred`  | none       | Yes                  | No           |
+
+[Protection level details](validation/protection-levels.md)
+
+---
+
+## CLI Usage
+
+```bash
+# Pre-commit (default mode)
+lint-process --staged
+
+# CI pipeline with strict mode
+lint-process --all --strict
+
+# Override session scope checking
+lint-process --staged --ignore-session
+
+# Debug: show derived process state
+lint-process --staged --show-state
+```
+
+### Options
+
+| Flag               | Description                             |
+| ------------------ | --------------------------------------- |
+| `--staged`         | Validate staged files only (pre-commit) |
+| `--all`            | Validate all tracked files (CI)         |
+| `--strict`         | Treat warnings as errors (exit 1)       |
+| `--ignore-session` | Skip session scope validation           |
+| `--show-state`     | Debug: show derived process state       |
+| `--format json`    | Machine-readable JSON output            |
+
+### Exit Codes
+
+| Code | Meaning                                        |
+| ---- | ---------------------------------------------- |
+| `0`  | No errors (warnings allowed unless `--strict`) |
+| `1`  | Errors found or warnings with `--strict`       |
+
+---
+
+## Escape Hatches
+
+Override mechanisms for exceptional situations.
+
+| Situation                    | Solution              | Example                                  |
+| ---------------------------- | --------------------- | ---------------------------------------- |
+| Fix bug in completed spec    | Add unlock reason tag | `@architect-unlock-reason:'Fix-typo'`    |
+| Modify outside session scope | Use ignore flag       | `lint-process --staged --ignore-session` |
+| CI treats warnings as errors | Use strict flag       | `lint-process --all --strict`            |
+
+---

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

@@ -0,0 +1,26 @@
+### Annotation Overview
+
+**How do I annotate code?** The annotation system is the ingestion boundary — it transforms annotated TypeScript and Gherkin files into `ExtractedPattern[]` objects that feed the entire downstream pipeline. Two parallel scanning paths (TypeScript AST + Gherkin parser) converge through dual-source merging. The system is fully data-driven: the `TagRegistry` defines all tags, formats, and categories — adding a new annotation requires only a registry entry, zero parser changes.
+
+#### Key Invariants
+
+- Source ownership enforced: `uses`/`used-by`/`category` belong in TypeScript only; `depends-on`/`quarter`/`team`/`phase` belong in Gherkin only. Anti-pattern detector validates at lint time
+- Data-driven tag dispatch: Both AST parser and Gherkin parser use `TagRegistry.metadataTags` to determine extraction. 6 format types (`value`/`enum`/`csv`/`number`/`flag`/`quoted-value`) cover all tag shapes — zero parser changes for new tags
+- Pipeline data preservation: Gherkin `Rule:` blocks, deliverables, scenarios, and all metadata flow through scanner → extractor → `ExtractedPattern` → generators without data loss
+- Dual-source merge with conflict detection: Same pattern name in both TypeScript and Gherkin produces a merge conflict error. Phase mismatches between sources produce validation errors
+
+**Components:** Extractor (GherkinExtractor, DualSourceExtractor, Document Extractor), Scanner (Pattern Scanner, GherkinScanner, GherkinASTParser, TypeScript AST Parser)
+
+#### API Types
+
+| Type                             | Kind      |
+| -------------------------------- | --------- |
+| TagRegistry                      | interface |
+| MetadataTagDefinitionForRegistry | interface |
+| CategoryDefinition               | interface |
+| TagDefinition                    | type      |
+| CategoryTag                      | type      |
+| buildRegistry                    | function  |
+| METADATA_TAGS_BY_GROUP           | const     |
+| CATEGORIES                       | const     |
+| CATEGORY_TAGS                    | const     |

package/docs-live/_claude-md/annotation/annotation-reference.md

@@ -0,0 +1,213 @@
+### Annotation Reference Guide
+
+#### Getting Started
+
+Every file that participates in the annotation system must have a `@architect` opt-in marker. Files without this marker are invisible to the scanner.
+
+##### File-Level Opt-In
+
+**TypeScript** -- file-level JSDoc block:
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern MyPattern
+ * @architect-status roadmap
+ * @architect-uses EventStore, CommandBus
+ *
+ * ## My Pattern - Description
+ */
+```
+
+**Gherkin** -- file-level tags before `Feature:`:
+
+```gherkin
+@architect
+@architect-pattern:MyPattern
+@architect-status:roadmap
+@architect-phase:14
+Feature: My Pattern
+
+  **Problem:**
+  Description of the problem.
+```
+
+##### Tag Prefix by Preset
+
+| Preset                    | Prefix        | Categories | Use Case                     |
+| ------------------------- | ------------- | ---------- | ---------------------------- |
+| `libar-generic` (default) | `@architect-` | 3          | Simple projects              |
+| `ddd-es-cqrs`             | `@architect-` | 21         | DDD/Event Sourcing monorepos |
+
+##### Dual-Source Ownership
+
+| Source         | Owns                                            | Example Tags                                 |
+| -------------- | ----------------------------------------------- | -------------------------------------------- |
+| **TypeScript** | Implementation: runtime deps, category, shapes  | `uses`, `used-by`, `extract-shapes`, `shape` |
+| **Gherkin**    | Planning: status, phase, timeline, dependencies | `status`, `phase`, `depends-on`, `quarter`   |
+
+#### Shape Extraction
+
+Shape extraction pulls TypeScript type definitions (interfaces, type aliases, enums, functions, consts) into generated documentation. There are three modes:
+
+##### Mode 1: File-Level Explicit Names
+
+List specific declaration names in the file-level JSDoc:
+
+```typescript
+/**
+ * @architect
+ * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema
+ */
+```
+
+Names appear in the generated output in the order listed.
+
+##### Mode 2: File-Level Wildcard
+
+```typescript
+/**
+ * @architect
+ * @architect-extract-shapes *
+ */
+```
+
+Wildcard must be the sole value -- `*, Foo` is invalid.
+
+##### Mode 3: Declaration-Level Tagging
+
+Tag individual declarations with `@architect-shape`, optionally with a group name:
+
+```typescript
+/** @architect-shape api-types */
+export interface CommandInput {
+  readonly aggregateId: string;
+  readonly payload: unknown;
+}
+```
+
+The optional group name (`api-types`) enables filtering in diagram scopes and product area documents via `@architect-include`.
+
+#### Critical Gotcha: Zod Schemas
+
+For Zod files, extract the **schema constant** (with `Schema` suffix), not the inferred type alias:
+
+| Wrong (type alias)                       | Correct (schema constant)                 |
+| ---------------------------------------- | ----------------------------------------- |
+| `@extract-shapes MasterDataset`          | `@extract-shapes MasterDatasetSchema`     |
+| Shows: `z.infer<typeof ...>` (unhelpful) | Shows: `z.object({...})` (full structure) |
+
+#### Annotation Patterns by File Type
+
+##### Zod Schema Files
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern MasterDataset
+ * @architect-status completed
+ * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, PhaseGroupSchema
+ */
+```
+
+##### Interface / Type Files
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern DocumentGenerator
+ * @architect-status completed
+ * @architect-extract-shapes DocumentGenerator, GeneratorContext, GeneratorOutput
+ */
+```
+
+##### Function / Service Files
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern TransformDataset
+ * @architect-status completed
+ * @architect-arch-context generator
+ * @architect-arch-layer application
+ * @architect-extract-shapes transformToMasterDataset, RuntimeMasterDataset
+ */
+```
+
+##### Gherkin Feature Files
+
+```gherkin
+@architect
+@architect-pattern:ProcessGuardLinter
+@architect-status:roadmap
+@architect-phase:99
+@architect-depends-on:StateMachine,ValidationRules
+Feature: Process Guard Linter
+
+  Background: Deliverables
+    Given the following deliverables:
+      | Deliverable      | Status  | Location             |
+      | State derivation | Pending | src/lint/derive.ts   |
+
+  Rule: Completed specs require unlock reason
+
+    **Invariant:** A completed spec cannot be modified without explicit unlock.
+    **Rationale:** Prevents accidental regression of validated work.
+
+    @acceptance-criteria @happy-path
+    Scenario: Reject modification without unlock
+      Given a spec with status "completed"
+      When I modify a deliverable
+      Then validation fails with "completed-protection"
+```
+
+#### Tag Groups Quick Reference
+
+Tags are organized into 12 functional groups. For the complete reference with all values, see the generated [Taxonomy Reference](../docs-live/TAXONOMY.md).
+
+| Group            | Tags (representative)                                | Format Types              |
+| ---------------- | ---------------------------------------------------- | ------------------------- |
+| **Core**         | `pattern`, `status`, `core`, `brief`                 | value, enum, flag         |
+| **Relationship** | `uses`, `used-by`, `implements`, `depends-on`        | csv, value                |
+| **Process**      | `phase`, `quarter`, `effort`, `team`, `priority`     | number, value, enum       |
+| **PRD**          | `product-area`, `user-role`, `business-value`        | value                     |
+| **ADR**          | `adr`, `adr-status`, `adr-category`, `adr-theme`     | value, enum               |
+| **Hierarchy**    | `level`, `parent`, `title`                           | enum, value, quoted-value |
+| **Traceability** | `executable-specs`, `roadmap-spec`, `behavior-file`  | csv, value                |
+| **Discovery**    | `discovered-gap`, `discovered-improvement`           | value (repeatable)        |
+| **Architecture** | `arch-role`, `arch-context`, `arch-layer`, `include` | enum, value, csv          |
+| **Extraction**   | `extract-shapes`, `shape`                            | csv, value                |
+| **Stub**         | `target`, `since`                                    | value                     |
+| **Convention**   | `convention`                                         | csv (enum values)         |
+
+#### Verification
+
+##### CLI Commands
+
+```bash
+# Tag usage inventory (counts per tag and value)
+pnpm architect:query -- tags
+
+# Find files missing @architect opt-in marker
+pnpm architect:query -- unannotated --path src/types
+
+# File inventory by type (TS, Gherkin, Stubs)
+pnpm architect:query -- sources
+
+# Full pattern JSON including extractedShapes
+pnpm architect:query -- query getPattern MyPattern
+
+# Generate complete tag reference
+pnpm docs:taxonomy
+```
+
+#### Common Issues
+
+| Symptom                         | Cause                              | Fix                                             |
+| ------------------------------- | ---------------------------------- | ----------------------------------------------- |
+| Pattern not in scanner output   | Missing `@architect` opt-in marker | Add file-level `@architect` JSDoc/tag           |
+| Shape shows `z.infer<>` wrapper | Extracted type alias, not schema   | Use schema constant name (e.g., `FooSchema`)    |
+| Shape not in product area doc   | Missing `@architect-product-area`  | Add product-area tag to file-level annotation   |
+| Declaration-level shape missing | No `@architect-shape` on decl      | Add `@architect-shape` JSDoc to the declaration |
+| Tag value rejected              | Wrong format or invalid enum value | Check format type in taxonomy reference         |
+| Anti-pattern validation error   | Tag on wrong source type           | Move tag to correct source (TS vs Gherkin)      |