@libar-dev/architect 1.0.0-pre.3

package/dist/validation-schemas/workflow-config.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @architect
+ * @architect-validation @architect-config
+ * @architect-pattern WorkflowConfigSchema
+ * @architect-status completed
+ * @architect-used-by WorkflowLoader, ConfigurableWorkflows
+ *
+ * ## WorkflowConfigSchema - Workflow Configuration Validation
+ *
+ * Zod schemas for validating workflow configuration files that define
+ * status models, phase definitions, and artifact mappings.
+ *
+ * ### When to Use
+ *
+ * - When validating workflow configuration (inline defaults or custom files)
+ * - When validating custom workflow configurations
+ * - When creating new workflow definitions
+ */
+import { z } from 'zod';
+/**
+ * Status definition within a workflow
+ *
+ * Each status has a name, display emoji, and optional transition rules.
+ */
+export declare const WorkflowStatusSchema: z.ZodObject<{
+    name: z.ZodString;
+    emoji: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    transitionsTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    terminal: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type WorkflowStatus = z.infer<typeof WorkflowStatusSchema>;
+/**
+ * Artifact mapping for a workflow phase
+ *
+ * Defines which artifacts are read/written during each phase.
+ */
+export declare const PhaseArtifactsSchema: z.ZodObject<{
+    reads: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type PhaseArtifacts = z.infer<typeof PhaseArtifactsSchema>;
+/**
+ * Phase definition within a workflow
+ *
+ * Phases are the stages of work delivery (e.g., Inception, Construction).
+ */
+export declare const WorkflowPhaseSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    statusOnEntry: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodOptional<z.ZodObject<{
+        reads: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    order: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type WorkflowPhase = z.infer<typeof WorkflowPhaseSchema>;
+/**
+ * Complete workflow configuration
+ *
+ * Defines a delivery workflow with statuses, phases, and metadata.
+ * Multiple workflows can be defined (e.g., 6-phase-standard, 3-phase-minimal).
+ */
+export declare const WorkflowConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    statuses: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        emoji: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        transitionsTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        terminal: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    phases: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        statusOnEntry: z.ZodOptional<z.ZodString>;
+        artifacts: z.ZodOptional<z.ZodObject<{
+            reads: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    defaultStatus: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        author: z.ZodOptional<z.ZodString>;
+        lastUpdated: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>;
+/**
+ * Loaded workflow with computed lookup maps
+ *
+ * Runtime representation that includes fast status/phase lookup.
+ */
+export interface LoadedWorkflow {
+    /** Original config */
+    readonly config: WorkflowConfig;
+    /** Status lookup by name (case-insensitive) */
+    readonly statusMap: Map<string, WorkflowStatus>;
+    /** Phase lookup by name (case-insensitive) */
+    readonly phaseMap: Map<string, WorkflowPhase>;
+}
+/**
+ * Create a LoadedWorkflow from a WorkflowConfig
+ *
+ * Builds lookup maps for efficient status/phase resolution.
+ *
+ * @param config - Validated workflow configuration
+ * @returns LoadedWorkflow with lookup maps
+ */
+export declare function createLoadedWorkflow(config: WorkflowConfig): LoadedWorkflow;
+/**
+ * Runtime type guard for WorkflowConfig
+ *
+ * @param value - Value to check
+ * @returns True if value conforms to WorkflowConfigSchema
+ */
+export declare function isWorkflowConfig(value: unknown): value is WorkflowConfig;
+//# sourceMappingURL=workflow-config.d.ts.map

package/dist/validation-schemas/workflow-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-config.d.ts","sourceRoot":"","sources":["../../src/validation-schemas/workflow-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;kBAoBtB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;kBAQtB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;kBAiBrB,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAkCtB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAEhD,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAgB3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/validation-schemas/workflow-config.js

@@ -0,0 +1,138 @@
+/**
+ * @architect
+ * @architect-validation @architect-config
+ * @architect-pattern WorkflowConfigSchema
+ * @architect-status completed
+ * @architect-used-by WorkflowLoader, ConfigurableWorkflows
+ *
+ * ## WorkflowConfigSchema - Workflow Configuration Validation
+ *
+ * Zod schemas for validating workflow configuration files that define
+ * status models, phase definitions, and artifact mappings.
+ *
+ * ### When to Use
+ *
+ * - When validating workflow configuration (inline defaults or custom files)
+ * - When validating custom workflow configurations
+ * - When creating new workflow definitions
+ */
+import { z } from 'zod';
+/**
+ * Status definition within a workflow
+ *
+ * Each status has a name, display emoji, and optional transition rules.
+ */
+export const WorkflowStatusSchema = z
+    .object({
+    /** Status identifier (e.g., "roadmap", "active", "completed") */
+    name: z.string().min(1),
+    /** Display emoji for this status */
+    emoji: z.string().min(1),
+    /** Human-readable label (optional, defaults to capitalized name) */
+    label: z.string().optional(),
+    /** Human-readable description of what this status means */
+    description: z.string().optional(),
+    /** Status IDs this status can transition to (for validation) */
+    transitionsTo: z.array(z.string()).optional(),
+    /** Whether this is a terminal status (no further transitions) */
+    terminal: z.boolean().optional(),
+})
+    .strict();
+/**
+ * Artifact mapping for a workflow phase
+ *
+ * Defines which artifacts are read/written during each phase.
+ */
+export const PhaseArtifactsSchema = z
+    .object({
+    /** Artifacts read during this phase */
+    reads: z.array(z.string()).optional(),
+    /** Artifacts produced during this phase */
+    writes: z.array(z.string()).optional(),
+})
+    .strict();
+/**
+ * Phase definition within a workflow
+ *
+ * Phases are the stages of work delivery (e.g., Inception, Construction).
+ */
+export const WorkflowPhaseSchema = z
+    .object({
+    /** Phase name (e.g., "Inception", "Construction") */
+    name: z.string().min(1),
+    /** Human-readable description of this phase */
+    description: z.string().optional(),
+    /** Status assigned when entering this phase */
+    statusOnEntry: z.string().optional(),
+    /** Artifact read/write mappings for this phase */
+    artifacts: PhaseArtifactsSchema.optional(),
+    /** Order index for sorting phases (lower = earlier) */
+    order: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * Complete workflow configuration
+ *
+ * Defines a delivery workflow with statuses, phases, and metadata.
+ * Multiple workflows can be defined (e.g., 6-phase-standard, 3-phase-minimal).
+ */
+export const WorkflowConfigSchema = z
+    .object({
+    /** Workflow name (e.g., "6-phase-standard") */
+    name: z.string().min(1),
+    /** Semantic version for config compatibility */
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver format'),
+    /** Human-readable description */
+    description: z.string().optional(),
+    /** Status definitions for this workflow */
+    statuses: z.array(WorkflowStatusSchema).min(1),
+    /** Phase definitions for this workflow */
+    phases: z.array(WorkflowPhaseSchema).min(1),
+    /** Default status for new items */
+    defaultStatus: z.string().optional(),
+    /** Metadata for this workflow config */
+    metadata: z
+        .object({
+        /** Author or team who created this workflow */
+        author: z.string().optional(),
+        /** When this config was last updated */
+        lastUpdated: z.string().optional(),
+        /** Tags for categorization */
+        tags: z.array(z.string()).optional(),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * Create a LoadedWorkflow from a WorkflowConfig
+ *
+ * Builds lookup maps for efficient status/phase resolution.
+ *
+ * @param config - Validated workflow configuration
+ * @returns LoadedWorkflow with lookup maps
+ */
+export function createLoadedWorkflow(config) {
+    const statusMap = new Map();
+    for (const status of config.statuses) {
+        statusMap.set(status.name.toLowerCase(), status);
+    }
+    const phaseMap = new Map();
+    for (const phase of config.phases) {
+        phaseMap.set(phase.name.toLowerCase(), phase);
+    }
+    return {
+        config,
+        statusMap,
+        phaseMap,
+    };
+}
+/**
+ * Runtime type guard for WorkflowConfig
+ *
+ * @param value - Value to check
+ * @returns True if value conforms to WorkflowConfigSchema
+ */
+export function isWorkflowConfig(value) {
+    return WorkflowConfigSchema.safeParse(value).success;
+}
+//# sourceMappingURL=workflow-config.js.map

package/dist/validation-schemas/workflow-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-config.js","sourceRoot":"","sources":["../../src/validation-schemas/workflow-config.ts"],"names":[],"mappings":"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"}

package/docs/ANNOTATION-GUIDE.md

@@ -0,0 +1,271 @@
+# Annotation Guide
+
+> **Deprecated:** This document is superseded by the auto-generated [Annotation Reference Guide](../docs-live/reference/ANNOTATION-REFERENCE.md) which includes all content from this guide plus auto-updated tag tables. This file is preserved for reference only.
+
+How to annotate TypeScript and Gherkin files for pattern extraction, documentation generation, and architecture diagrams.
+
+For the **complete tag reference** (all 50+ tags with formats, values, and examples), generate the taxonomy: `pnpm docs:taxonomy` or see [TAXONOMY.md](./TAXONOMY.md) for the taxonomy architecture.
+
+---
+
+## Getting Started
+
+### File-Level Opt-In
+
+Every file that participates in the annotation system must have a `@architect` opt-in marker. Files without this marker are invisible to the scanner.
+
+**TypeScript** — file-level JSDoc block:
+
+```typescript
+/**
+ * @architect
+ * @architect-pattern MyPattern
+ * @architect-status roadmap
+ * @architect-uses EventStore, CommandBus
+ *
+ * ## My Pattern - Description
+ *
+ * Paragraph describing the pattern's purpose.
+ */
+```
+
+**Gherkin** — file-level tags before `Feature:`:
+
+```gherkin
+@architect
+@architect-pattern:MyPattern
+@architect-status:roadmap
+@architect-phase:14
+@architect-depends-on:EventStore,CommandBus
+Feature: My Pattern
+
+  **Problem:**
+  Description of the problem.
+```
+
+### Tag Prefix by Preset
+
+The tag prefix is configurable via presets. All examples in this guide use the default `@architect-` prefix.
+
+| Preset                    | Prefix        | Categories | Use Case                     |
+| ------------------------- | ------------- | ---------- | ---------------------------- |
+| `libar-generic` (default) | `@architect-` | 3          | Simple projects              |
+| `ddd-es-cqrs`             | `@architect-` | 21         | DDD/Event Sourcing monorepos |
+
+See [CONFIGURATION.md](./CONFIGURATION.md) for preset details and custom configuration.
+
+### Dual-Source Ownership
+
+Annotations are split between TypeScript and Gherkin by domain:
+
+| 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`   |
+
+Anti-pattern validation enforces these boundaries — see [VALIDATION.md](./VALIDATION.md).
+
+---
+
+## 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, RelationshipEntry
+ */
+```
+
+Names appear in the generated output in the order listed.
+
+### Mode 2: File-Level Wildcard
+
+Extract all exported declarations automatically:
+
+```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;
+}
+
+/** @architect-shape api-types */
+export type CommandResult = Result<void, CommandError>;
+```
+
+Declaration-level shapes work on both exported and non-exported declarations. 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
+
+> For the complete tag reference with all values, see the [generated Taxonomy Reference](../docs-live/TAXONOMY.md).
+
+Tags are organized into 12 functional groups. This table shows representative tags per group — for the **complete reference** with all formats, values, and examples, run `pnpm docs:taxonomy`.
+
+| 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)         |
+
+### Format Types
+
+| Format         | Syntax Example                | Parsing                        |
+| -------------- | ----------------------------- | ------------------------------ |
+| `flag`         | `@architect-core`             | Boolean presence (no value)    |
+| `value`        | `@architect-pattern Foo`      | Simple string                  |
+| `enum`         | `@architect-status roadmap`   | Constrained to predefined list |
+| `csv`          | `@architect-uses A, B, C`     | Comma-separated values         |
+| `number`       | `@architect-phase 14`         | Numeric value                  |
+| `quoted-value` | `@architect-title:'My Title'` | Preserves spaces in value      |
+
+---
+
+## 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)      |
+
+---
+
+## Related Documentation
+
+| Topic                     | Document                                       |
+| ------------------------- | ---------------------------------------------- |
+| Taxonomy architecture     | [TAXONOMY.md](./TAXONOMY.md)                   |
+| Presets and configuration | [CONFIGURATION.md](./CONFIGURATION.md)         |
+| Pipeline and codecs       | [ARCHITECTURE.md](./ARCHITECTURE.md)           |
+| Gherkin writing patterns  | [GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md)   |
+| Anti-pattern validation   | [VALIDATION.md](./VALIDATION.md)               |
+| Product area enrichment   | [CLAUDE.md — Product Area Guide](../CLAUDE.md) |