@libar-dev/architect 1.0.0-pre.3

package/docs/GHERKIN-PATTERNS.md

@@ -0,0 +1,366 @@
+# Gherkin Patterns Guide
+
+> **Deprecated:** This document is superseded by the auto-generated [Gherkin Authoring Guide](../docs-live/reference/GHERKIN-AUTHORING-GUIDE.md). This file is preserved for reference only. Examples below may be stale and should not be used as templates — refer to the auto-generated guide for current patterns.
+
+Practical patterns for writing Gherkin specs that work with Architect generators.
+
+---
+
+## Essential Patterns
+
+### 1. Roadmap Spec Structure
+
+Roadmap specs define planned work with Problem/Solution descriptions and a Background deliverables table.
+
+```gherkin
+@architect-pattern:ProcessGuardLinter
+@architect-status:roadmap
+@architect-phase:99
+Feature: Process Guard Linter
+
+  **Problem:**
+  During planning and implementation sessions, accidental modifications occur:
+  - Specs outside the intended scope get modified in bulk
+  - Completed/approved work gets inadvertently changed
+
+  **Solution:**
+  Implement a Decider-based linter that:
+  1. Derives process state from existing file annotations
+  2. Validates proposed changes against derived state
+  3. Enforces file protection levels per PDR-005
+
+  Background: Deliverables
+    Given the following deliverables:
+      | Deliverable                   | Status  | Location                           |
+      | State derivation              | Pending | src/lint/process-guard/derive.ts   |
+      | Git diff change detection     | Pending | src/lint/process-guard/detect.ts   |
+      | CLI integration               | Pending | src/cli/lint-process.ts            |
+```
+
+**Key elements:**
+
+- `@architect-pattern:Name` - Unique identifier (required)
+- `@architect-status:roadmap` - FSM state
+- `**Problem:**` / `**Solution:**` - Extracted by generators
+- Background deliverables table - Tracks implementation progress
+
+### 2. Rule Blocks for Business Constraints
+
+Use `Rule:` to group related scenarios under a business constraint.
+
+```gherkin
+Rule: Status transitions must follow PDR-005 FSM
+
+  @happy-path
+  Scenario Outline: Valid transitions pass validation
+    Given a file with status "<from>"
+    When the status changes to "<to>"
+    Then validation passes
+
+    Examples:
+      | from     | to        |
+      | roadmap  | active    |
+      | roadmap  | deferred  |
+      | active   | completed |
+      | deferred | roadmap   |
+
+  @edge-case
+  Scenario Outline: Invalid transitions fail validation
+    Given a file with status "<from>"
+    When the status changes to "<to>"
+    Then validation fails with "invalid-status-transition"
+
+    Examples:
+      | from      | to        |
+      | roadmap   | completed |
+      | deferred  | active    |
+      | completed | roadmap   |
+```
+
+Rules provide semantic grouping - generators extract them for business rules documentation.
+
+### 3. Scenario Outline for Variations
+
+When the same pattern applies with different inputs, use `Scenario Outline` with an `Examples` table.
+
+```gherkin
+Scenario Outline: Protection levels by status
+  Given a file with status "<status>"
+  When checking protection level
+  Then protection is "<protection>"
+  And unlock required is "<unlock>"
+
+  Examples:
+    | status    | protection | unlock |
+    | roadmap   | none       | no     |
+    | active    | scope      | no     |
+    | completed | hard       | yes    |
+    | deferred  | none       | no     |
+```
+
+### 4. Executable Test Feature
+
+Test features focus on behavior verification with section dividers for organization.
+
+```gherkin
+@behavior @scanner-core
+@architect-pattern:ScannerCore
+Feature: Scanner Core Integration
+  The scanPatterns function orchestrates file discovery and AST parsing.
+
+  **Problem:**
+  - Need to scan codebases for documentation directives efficiently
+  - Files without @architect opt-in should be skipped
+
+  **Solution:**
+  - Two-phase filtering: quick regex check, then file opt-in validation
+  - Result monad pattern captures errors without failing entire scan
+
+  Background:
+    Given a scanner integration context with temp directory
+
+  # ==========================================================================
+  # Basic Scanning
+  # ==========================================================================
+
+  @happy-path
+  Scenario: Scan files and extract directives
+    Given a file "src/auth.ts" with content:
+      """
+      /** @architect */
+
+      /** @architect-core */
+      export function authenticate() {}
+      """
+    When scanning with pattern "src/**/*.ts"
+    Then the scan should succeed with 1 file
+
+  # ==========================================================================
+  # Error Handling
+  # ==========================================================================
+
+  @error-handling
+  Scenario: Collect errors for files that fail to parse
+    Given a file "src/valid.ts" with valid content
+    And a file "src/invalid.ts" with syntax errors
+    When scanning with pattern "src/**/*.ts"
+    Then the scan should succeed with 1 file
+    And the scan should have 1 error
+```
+
+Section comments (`# ===`) improve readability in large feature files.
+
+---
+
+## DataTable and DocString Usage
+
+### Background DataTable (Reference Data)
+
+Use for data that applies to all scenarios - deliverables, definitions, etc.
+
+```gherkin
+Background: Deliverables
+  Given the following deliverables:
+    | Deliverable        | Status  | Location               | Tests |
+    | Category types     | Done    | src/types.ts           | Yes   |
+    | Validation logic   | Pending | src/validate.ts        | Yes   |
+```
+
+### Scenario DataTable (Test Data)
+
+Use for scenario-specific test inputs.
+
+```gherkin
+Scenario: Session file defines modification scope
+  Given a session file with in-scope specs:
+    | spec                        | intent |
+    | mvp-workflow-implementation | modify |
+    | short-form-tag-migration    | review |
+  When deriving process state
+  Then "mvp-workflow-implementation" is modifiable
+```
+
+### DocString for Code Examples
+
+Use `"""typescript` for code blocks. Essential when content contains pipes or special characters.
+
+```gherkin
+Scenario: Extract directive from TypeScript
+  Given a file with content:
+    """typescript
+    /** @architect */
+
+    /**
+     * @architect-core
+     * Authentication utilities
+     */
+    export function authenticate() {}
+    """
+  When scanning the file
+  Then directive should have tag "@architect-core"
+```
+
+---
+
+## Tag Conventions
+
+### Semantic Tags (Extracted by Generators)
+
+These tags are recognized by the extractor and appear in generated documentation:
+
+| Tag                    | Purpose                                           |
+| ---------------------- | ------------------------------------------------- |
+| `@acceptance-criteria` | Required for DoD validation of completed patterns |
+| `@happy-path`          | Primary success scenario                          |
+| `@validation`          | Input validation, constraint checks               |
+| `@business-rule`       | Business invariant verification                   |
+| `@business-failure`    | Expected business failure scenario                |
+| `@compensation`        | Compensating action scenario                      |
+| `@idempotency`         | Idempotency verification                          |
+| `@expiration`          | Expiration/timeout behavior                       |
+| `@workflow-state`      | Workflow state transition scenario                |
+
+### Convention Tags (Organizational)
+
+These tags are not extracted by generators but are used by convention for organizing feature files:
+
+| Tag               | Purpose                              |
+| ----------------- | ------------------------------------ |
+| `@edge-case`      | Boundary conditions, unusual inputs  |
+| `@error-handling` | Error recovery, graceful degradation |
+| `@integration`    | Cross-component behavior             |
+| `@poc`            | Proof of concept, experimental       |
+
+### Combining Tags
+
+Combine scenario-level tags with feature-level tags for filtering:
+
+```gherkin
+@behavior @scanner-core
+@architect-pattern:ScannerCore
+Feature: Scanner Core Integration
+```
+
+---
+
+## Feature File Rich Content
+
+Feature files serve dual purposes: **executable specs** and **documentation source**. Content in the Feature description section appears in generated docs.
+
+### Code-First Principle
+
+**Prefer code stubs over DocStrings for complex examples.** Feature files should reference code, not duplicate it.
+
+| Approach                     | When to Use                                                  |
+| ---------------------------- | ------------------------------------------------------------ |
+| DocStrings (`"""typescript`) | Brief examples (5-10 lines), current/target state comparison |
+| Code stub reference          | Complex APIs, interfaces, full implementations               |
+
+**Instead of large DocStrings:**
+
+```gherkin
+Rule: Reservations use atomic claim
+  See `@libar-dev/platform-core/src/reservations/reserve.ts` for API.
+```
+
+Code stubs are annotated TypeScript files with `throw new Error("not yet implemented")`.
+
+### Rule Block Structure (Recommended)
+
+For features that define business constraints, use `Rule:` blocks with structured descriptions:
+
+```gherkin
+Rule: Reservations prevent race conditions
+
+  **Invariant:** Only one reservation can exist for a given key at a time.
+
+  **Rationale:** Check-then-create patterns have TOCTOU vulnerabilities.
+
+  **Verified by:** Concurrent reservations, Expired reservation cleanup
+
+  @acceptance-criteria @happy-path
+  Scenario: Concurrent reservations
+    ...
+```
+
+| Element            | Purpose                                 | Extracted By                                |
+| ------------------ | --------------------------------------- | ------------------------------------------- |
+| `**Invariant:**`   | Business constraint (what must be true) | Business Rules generator                    |
+| `**Rationale:**`   | Business justification (why it exists)  | Business Rules generator                    |
+| `**Verified by:**` | Comma-separated scenario names          | Multiple codecs (Business Rules, Reference) |
+
+> **Note:** Rule blocks are optional. Use them when the feature defines business invariants that benefit from structured documentation.
+
+### Feature Description Patterns
+
+Choose headers that fit your pattern:
+
+| Structure        | Headers                                    | Best For                  |
+| ---------------- | ------------------------------------------ | ------------------------- |
+| Problem/Solution | `**Problem:**`, `**Solution:**`            | Pain point → fix          |
+| Value-First      | `**Business Value:**`, `**How It Works:**` | TDD-style, Gherkin spirit |
+| Context/Approach | `**Context:**`, `**Approach:**`            | Technical patterns        |
+
+The **Problem/Solution** pattern is the dominant style in this codebase.
+
+### Valid Rich Content
+
+| Content Type  | Syntax                  | Appears in Docs  |
+| ------------- | ----------------------- | ---------------- |
+| Plain text    | Regular paragraphs      | Yes              |
+| Bold/emphasis | `**bold**`, `*italic*`  | Yes              |
+| Tables        | Markdown pipe tables    | Yes              |
+| Lists         | `- item` or `1. item`   | Yes              |
+| DocStrings    | `"""typescript`...`"""` | Yes (code block) |
+| Comments      | `# comment`             | No (ignored)     |
+
+### Syntax Notes
+
+**Prefer DocStrings over code fences for portability:**
+
+```gherkin
+# Preferred - DocStrings with language hint
+Given the following code:
+  """typescript
+  const x = 1;
+  """
+
+# Avoid - markdown fences in descriptions may not render consistently
+```
+
+**Tag values cannot contain spaces.** Use hyphens:
+
+| Invalid                         | Valid                          |
+| ------------------------------- | ------------------------------ |
+| `@unlock-reason:Fix for issue`  | `@unlock-reason:Fix-for-issue` |
+| `@architect-pattern:My Pattern` | `@architect-pattern:MyPattern` |
+
+For values with spaces, use the `quoted-value` format where supported:
+
+```gherkin
+@architect-usecase "When handling command failures"
+```
+
+---
+
+## Quick Reference
+
+| Element                | Use For                                | Example Location                                         |
+| ---------------------- | -------------------------------------- | -------------------------------------------------------- |
+| Background DataTable   | Deliverables, shared reference data    | `architect/specs/process-guard-linter.feature`           |
+| Rule:                  | Group scenarios by business constraint | `tests/features/validation/*.feature`                    |
+| Scenario Outline       | Same pattern with variations           | `tests/features/validation/fsm-validator.feature`        |
+| DocString `"""`        | Code examples, content with pipes      | `tests/features/behavior/scanner-*.feature`              |
+| Section comments `#`   | Organize large feature files           | Most test features                                       |
+| `architect-lint-steps` | Catch vitest-cucumber traps statically | [VALIDATION.md — lint-steps](./VALIDATION.md#lint-steps) |
+
+---
+
+## Related Documentation
+
+| Document                                     | Purpose                                 |
+| -------------------------------------------- | --------------------------------------- |
+| [ANNOTATION-GUIDE.md](./ANNOTATION-GUIDE.md) | Annotation mechanics and tag reference  |
+| [TAXONOMY.md](./TAXONOMY.md)                 | Tag taxonomy concepts and API           |
+| [CONFIGURATION.md](./CONFIGURATION.md)       | Preset and tag prefix configuration     |
+| [VALIDATION.md](./VALIDATION.md)             | Full validation tool suite and CI setup |