@libar-dev/architect 1.0.0-pre.3

package/docs-live/reference/GHERKIN-AUTHORING-GUIDE.md

@@ -0,0 +1,270 @@
+# Gherkin Authoring Guide
+
+**Purpose:** Reference document: Gherkin Authoring Guide
+**Detail Level:** Full reference
+
+---
+
+## Essential Patterns
+
+### Roadmap Spec Structure
+
+Roadmap specs define planned work with Problem/Solution descriptions and a Background deliverables table.
+
+```gherkin
+@architect
+@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` -- bare opt-in marker (required)
+- `@architect-pattern:Name` -- unique identifier (required)
+- `@architect-status:roadmap` -- FSM state
+- `**Problem:**` / `**Solution:**` -- extracted by generators
+- Background deliverables table -- tracks implementation progress
+
+---
+
+### Rule Blocks for Business Constraints
+
+Use `Rule:` to group related scenarios under a business constraint.
+
+```gherkin
+Rule: Status transitions must follow PDR-005 FSM
+
+  **Invariant:** Only valid FSM transitions are allowed.
+
+  **Rationale:** The FSM enforces deliberate progression through planning, implementation, and completion.
+
+  **Verified by:** Valid transitions pass, Invalid transitions fail
+
+  @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   |
+```
+
+| 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) |
+
+---
+
+### 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     |
+```
+
+---
+
+### Executable Test Features
+
+Test features focus on behavior verification with section dividers for organization.
+
+```gherkin
+@behavior @scanner-core
+@architect-pattern:ScannerCore
+Feature: Scanner Core Integration
+
+  Background:
+    Given a scanner integration context with temp directory
+
+  @happy-path
+  Scenario: Scan files and extract directives
+    Given a file "src/auth.ts" with valid content
+    When scanning with pattern "src/**/*.ts"
+    Then the scan should succeed with 1 file
+```
+
+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 */
+    export function authenticate() {}
+    """
+  When scanning the file
+  Then directive should have tag "@architect-core"
+```
+
+---
+
+## Tag Conventions
+
+### Semantic Tags (Extracted by Generators)
+
+| 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                |
+| `@edge-case`           | Boundary conditions, unusual inputs               |
+| `@error-handling`      | Error recovery, graceful degradation              |
+
+---
+
+## Feature Description Patterns
+
+Choose headers that fit your pattern:
+
+| Structure        | Headers                                    | Best For                  |
+| ---------------- | ------------------------------------------ | ------------------------- |
+| Problem/Solution | `**Problem:**`, `**Solution:**`            | Pain point to 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.
+
+---
+
+## 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               |
+
+Code stubs are annotated TypeScript files with `throw new Error("not yet implemented")`, located in `architect/stubs/{pattern-name}/`.
+
+### 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 and Gotchas
+
+### Forbidden in Feature Descriptions
+
+| Forbidden                     | Why                              | Alternative                         |
+| ----------------------------- | -------------------------------- | ----------------------------------- |
+| Code fences (triple backtick) | Not Gherkin syntax               | Use DocStrings with lang hint       |
+| `@prefix` in free text        | Interpreted as Gherkin tag       | Remove `@` or use `libar-dev`       |
+| Nested DocStrings             | Gherkin parser error             | Reference code stub file            |
+| `#` at line start             | Gherkin comment -- kills parsing | Remove, use `//`, or step DocString |
+
+### Tag Value Constraints
+
+**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                             |
+| -------------------- | -------------------------------------- | ----------------------------------- |
+| Background DataTable | Deliverables, shared reference data    | Deliverables table in roadmap specs |
+| Rule:                | Group scenarios by business constraint | Invariant + Rationale + Verified by |
+| Scenario Outline     | Same pattern with variations           | Examples tables with multiple rows  |
+| DocString `"""`      | Code examples, content with pipes      | TypeScript/Gherkin code blocks      |
+| Section comments `#` | Organize large feature files           | `# ========= Section ==========`    |
+
+---