wicked-garden 12.27.0

package/skills/product/requirements-graph/refs/examples.md

@@ -0,0 +1,223 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Requirements Graph: Worked Examples
+
+## Example 1: Authentication Feature
+
+### Directory Structure
+
+```
+requirements/
+  meta.md
+  _scope.md
+  _risks.md
+  _questions.md
+  auth/
+    meta.md
+    US-001/
+      meta.md
+      AC-001-valid-login.md
+      AC-002-invalid-credentials.md
+      AC-003-account-lockout.md
+    US-002/
+      meta.md
+      AC-001-reset-email.md
+      AC-002-reset-link-expiry.md
+    NFR-001-login-performance.md
+    NFR-002-password-encryption.md
+  _decisions/
+    DEC-001-bcrypt-over-argon2.md
+```
+
+### Root meta.md
+
+```yaml
+---
+type: requirements-root
+project: user-portal
+created: 2026-04-05
+status: draft
+---
+
+# Requirements: User Portal
+
+Self-service portal for user account management and dashboard access.
+
+## Areas
+
+| Area | Stories | ACs | P0 ACs | Coverage |
+|------|---------|-----|--------|----------|
+| auth | 2 | 5 | 3 | 0% |
+
+## Scope
+See: [_scope.md](_scope.md)
+
+## Open Questions
+See: [_questions.md](_questions.md)
+```
+
+### AC Node: AC-001-valid-login.md
+
+```yaml
+---
+id: auth/US-001/AC-001
+type: acceptance-criterion
+priority: P0
+category: happy-path
+story: auth/US-001
+tags: [login, session, redirect]
+---
+
+Given valid email and password
+When user submits the login form
+Then user is redirected to /dashboard and a session cookie is set
+```
+
+### AC Node with traces (after implementation):
+
+```yaml
+---
+id: auth/US-001/AC-001
+type: acceptance-criterion
+priority: P0
+category: happy-path
+story: auth/US-001
+tags: [login, session, redirect]
+traces:
+  - target: src/routes/auth/login.ts
+    type: IMPLEMENTED_BY
+  - target: src/middleware/session.ts
+    type: IMPLEMENTED_BY
+  - target: tests/auth/login.test.ts
+    type: TESTED_BY
+---
+
+Given valid email and password
+When user submits the login form
+Then user is redirected to /dashboard and a session cookie is set
+```
+
+### Story meta.md: US-001/meta.md
+
+```yaml
+---
+id: auth/US-001
+type: user-story
+priority: P0
+complexity: M
+persona: end-user
+status: draft
+traces:
+  - target: phases/design/auth-flow.md
+    type: TRACES_TO
+tags: [authentication, login]
+---
+
+# US-001: User Login
+
+**As a** end-user
+**I want** to log in with my email and password
+**So that** I can access my personalized dashboard
+
+## Acceptance Criteria
+
+| AC | Description | Priority | Category |
+|----|-------------|----------|----------|
+| AC-001 | Valid login redirects to dashboard | P0 | happy-path |
+| AC-002 | Invalid creds show error message | P0 | error |
+| AC-003 | Account locks after 3 failures | P1 | edge-case |
+
+## Dependencies
+- Session store (Redis) configured
+- Email validation library
+
+## Open Questions
+- Session timeout: 30 min or user-configurable?
+```
+
+### NFR Node: NFR-001-login-performance.md
+
+```yaml
+---
+id: auth/NFR-001
+type: nfr
+priority: P1
+category: performance
+target: "< 2s response time at 1000 concurrent logins"
+measured_by: k6 load test in CI
+tags: [performance, auth, load-testing]
+---
+
+Login endpoint must respond within 2 seconds under load of 1000
+concurrent authentication requests. Measured via k6 load test
+running against staging environment in CI pipeline.
+```
+
+### Decision Node: DEC-001-bcrypt-over-argon2.md
+
+```yaml
+---
+id: _decisions/DEC-001
+type: decision
+status: accepted
+date: 2026-04-05
+tags: [security, password-hashing]
+---
+
+# DEC-001: Use bcrypt over Argon2 for password hashing
+
+## Context
+Need a password hashing algorithm for user authentication.
+
+## Decision
+Use bcrypt with cost factor 12.
+
+## Rationale
+- Wider library support across our stack (Node.js, Python)
+- Argon2 requires native compilation — complicates CI
+- bcrypt at cost 12 meets our security bar per OWASP guidelines
+
+## Consequences
+- Slightly less memory-hard than Argon2
+- May revisit when Argon2 library support improves
+```
+
+## Example 2: Simple Feature (3 ACs)
+
+For a small feature, the graph is still lean:
+
+```
+requirements/
+  meta.md
+  csv-export/
+    meta.md
+    US-001/
+      meta.md
+      AC-001-export-button.md
+      AC-002-csv-format.md
+      AC-003-large-dataset.md
+```
+
+Total files: 6 (3 meta.md + 3 ACs). Each AC is ~10 lines.
+Compare to the old monolith: 1 file at 200+ lines.
+
+The graph approach scales down cleanly — no empty sections, no
+boilerplate for risks/assumptions/appendices unless you need them.
+
+## Token Cost Comparison
+
+Reading the auth example above:
+
+| Approach | Tokens |
+|----------|--------|
+| Old monolith (full auth requirements) | ~800 |
+| Graph: root meta.md only (depth 1) | ~100 |
+| Graph: area meta.md (depth 1) | ~80 |
+| Graph: story meta.md (depth 1) | ~120 |
+| Graph: single AC (depth 2) | ~40 |
+| Graph: all frontmatter (depth 0) | ~60 |
+
+The agent loads only what it needs. Gate checks read meta.md.
+Implementation reads specific ACs. No wasted context.

package/skills/product/requirements-graph/refs/schema.md

@@ -0,0 +1,162 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Requirements Graph: Frontmatter Schema Reference
+
+Complete field reference for all requirement node types.
+
+## Common Fields (all types)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `id` | yes | string | Path-derived slug from `requirements/` root. E.g., `auth/US-001/AC-001` |
+| `type` | yes | enum | Node type (see below) |
+| `tags` | no | string[] | Keywords for search indexing |
+| `traces` | no | object[] | Graph edges to other artifacts |
+| `compliance` | no | string[] | Regulatory controls. E.g., `["SOC2-CC6.1", "GDPR-Art.32"]` |
+
+## Node Types
+
+### `acceptance-criterion`
+
+The atomic unit. One file per criterion.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `priority` | yes | enum | `P0`, `P1`, `P2` |
+| `category` | yes | enum | `happy-path`, `error`, `edge-case`, `non-functional` |
+| `story` | yes | string | Parent story slug. E.g., `auth/US-001` |
+| `status` | no | enum | `draft`, `review`, `approved`, `implemented`, `verified` |
+
+**Body**: Given/When/Then block. Keep it to 1-5 lines. No essays.
+
+**Naming**: `AC-{NNN}-{slug}.md` where NNN is zero-padded, slug is kebab-case.
+
+### `user-story`
+
+A directory's `meta.md`. Groups acceptance criteria.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `priority` | yes | enum | `P0`, `P1`, `P2` |
+| `complexity` | yes | enum | `S`, `M`, `L`, `XL` |
+| `persona` | yes | string | Who this story is for |
+| `status` | yes | enum | `draft`, `review`, `approved`, `implemented`, `verified` |
+
+**Body**: As a/I want/So that + AC summary table + dependencies + questions.
+
+**Naming**: Directory is `US-{NNN}` (zero-padded). `meta.md` inside.
+
+### `area`
+
+Groups stories by feature/epic. Directory `meta.md`.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `status` | no | enum | `draft`, `review`, `approved` |
+
+**Body**: Summary + story table + NFR table + coverage stats.
+
+**Naming**: Directory is kebab-case feature name. `meta.md` inside.
+
+### `nfr`
+
+Non-functional requirement. Lives at area level.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `priority` | yes | enum | `P0`, `P1`, `P2` |
+| `category` | yes | enum | `performance`, `security`, `scalability`, `usability`, `reliability` |
+| `target` | yes | string | Measurable target. E.g., `< 2s at 1000 concurrent` |
+| `measured_by` | no | string | How to verify |
+
+**Naming**: `NFR-{NNN}-{slug}.md`
+
+### `decision`
+
+Lightweight ADR. Lives in `_decisions/`.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `status` | yes | enum | `proposed`, `accepted`, `superseded` |
+| `date` | yes | string | ISO date |
+| `supersedes` | no | string | ID of decision this replaces |
+
+**Naming**: `DEC-{NNN}-{slug}.md`
+
+### `requirements-root`
+
+Root `meta.md` only. One per project.
+
+| Field | Required | Type | Values |
+|-------|----------|------|--------|
+| `project` | yes | string | Project name |
+| `created` | yes | string | ISO date |
+| `status` | yes | enum | `draft`, `review`, `approved` |
+
+## Traces Schema
+
+Each trace is an edge in the graph:
+
+```yaml
+traces:
+  - target: path/to/artifact    # relative path or code file
+    type: IMPLEMENTED_BY         # edge type
+```
+
+### Edge Types
+
+| Type | From | To | Direction |
+|------|------|----|-----------|
+| `DECOMPOSES_TO` | story | AC | parent → child |
+| `TRACES_TO` | requirement | design doc | forward |
+| `IMPLEMENTED_BY` | AC | source file | forward |
+| `TESTED_BY` | AC | test file | forward |
+| `VERIFIES` | test result | AC | reverse |
+| `SATISFIES` | evidence | requirement | reverse |
+| `DEPENDS_ON` | story/AC | story/AC | lateral |
+
+### Trace Target Conventions
+
+- **Graph nodes**: relative from `requirements/` root — `auth/US-001/AC-001`
+- **Code files**: relative from project root — `src/auth/login.ts`
+- **Test files**: relative from project root — `tests/auth/login.test.ts`
+- **Design docs**: relative from project root — `phases/design/auth-flow.md`
+- **External**: full path or URL
+
+## ID Convention
+
+The `id` field is a **path-derived slug**:
+
+```
+requirements/auth/US-001/AC-001-login-success.md
+              ↓
+id: auth/US-001/AC-001
+```
+
+Rules:
+- Strip `requirements/` prefix
+- Strip file extension
+- For meta.md: use directory path (e.g., `auth/US-001`)
+- For AC/NFR files: use up to the AC/NFR number (drop the slug suffix)
+
+**Lint catches mismatches** between `id:` and actual path.
+
+## Minimal Valid AC
+
+```yaml
+---
+id: auth/US-001/AC-001
+type: acceptance-criterion
+priority: P0
+category: happy-path
+story: auth/US-001
+---
+
+Given valid email and password
+When user submits login form
+Then session is created and user sees dashboard
+```
+
+12 lines. Compare to the old monolith's 260 lines for an entire feature.

package/skills/product/requirements-migrate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: requirements-migrate
+description: |
+  Convert monolithic requirements documents into graph-structured
+  requirements directories. Parses user stories and acceptance criteria
+  from existing docs and creates atomic graph nodes.
+
+  Use when: "migrate requirements", "convert to graph",
+  "split requirements", "restructure requirements"
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Requirements Migrate
+
+Convert existing monolithic requirements documents into the graph structure.
+
+## Process
+
+### 1. Parse Source Document
+
+Read the monolithic requirements file and extract:
+- User stories (As a/I want/So that blocks)
+- Acceptance criteria (Given/When/Then blocks)
+- Functional requirements (REQ-XXX entries)
+- Non-functional requirements (REQ-PERF/SEC/SCALE/UX entries)
+- Scope (in/out/future)
+- Risks, assumptions, open questions
+- Dependencies
+
+### 2. Plan Graph Structure
+
+Map extracted content to graph nodes:
+- Group stories by feature area (infer from headings or REQ prefixes)
+- Each story becomes a `US-NNN` directory
+- Each AC becomes an `AC-NNN-{slug}.md` file
+- Functional requirements that duplicate stories are merged (not duplicated)
+- NFRs become area-level `NFR-NNN-{slug}.md` files
+- Decisions/rationale become `_decisions/DEC-NNN-{slug}.md`
+
+### 3. Create Graph
+
+```
+For each area:
+  mkdir -p requirements/{area}
+  Write requirements/{area}/meta.md
+
+  For each story in area:
+    mkdir -p requirements/{area}/{US-NNN}
+    Write requirements/{area}/{US-NNN}/meta.md
+
+    For each AC in story:
+      Write requirements/{area}/{US-NNN}/{AC-NNN}-{slug}.md
+
+  For each NFR in area:
+    Write requirements/{area}/{NFR-NNN}-{slug}.md
+
+Write requirements/meta.md (root)
+Write requirements/_scope.md
+Write requirements/_risks.md
+Write requirements/_questions.md
+```
+
+### 4. Verify
+
+After migration:
+- Run navigate lint to check structure
+- Compare AC count: source doc vs graph nodes (should match)
+- Check no content was lost (stories, criteria, NFRs)
+- Verify frontmatter IDs match paths
+
+### 5. Archive Source
+
+Move the original monolith to `requirements/_archived/` so it's
+preserved but not the active source of truth.
+
+## Handling Ambiguity
+
+- **Stories without clear ACs**: Create the story directory + meta.md,
+  add a note in `_questions.md` that ACs need to be defined
+- **Functional reqs that aren't stories**: If REQ-XXX doesn't map to a
+  user story, create it as an AC under a synthetic story
+- **Inline NFRs**: Extract performance/security mentions from story text
+  into area-level NFR nodes
+- **Missing personas**: Default to the most common persona in the doc,
+  flag in `_questions.md`
+
+## Progressive Disclosure
+
+- **SKILL.md** (this file): Migration process

package/skills/product/requirements-navigate/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: requirements-navigate
+description: |
+  Navigate, query, and maintain requirements graphs. Regenerates meta.md
+  on demand, checks coverage, finds gaps, and lints the graph structure.
+
+  Use when: navigating or querying a requirements graph, generating a coverage
+  report, refreshing meta.md, or linting graph structure for gaps.
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Requirements Navigate
+
+Read, query, and maintain requirements graph structures. Generates and
+refreshes meta.md files. Checks coverage and finds gaps.
+
+## Commands
+
+### Navigate (read graph)
+
+Read a requirements node or area with progressive depth:
+
+**Depth 0** — frontmatter only (~5 tokens per node):
+```bash
+# Read just the frontmatter of all ACs in a story
+for f in requirements/auth/US-001/AC-*.md; do
+  head -20 "$f"  # frontmatter block
+done
+```
+
+**Depth 1** — meta.md (summary + tables):
+```bash
+# Read the story summary
+cat requirements/auth/US-001/meta.md
+```
+
+**Depth 2** — full content of specific nodes:
+```bash
+# Read a specific AC
+cat requirements/auth/US-001/AC-001-login-success.md
+```
+
+**Always start at depth 1** (meta.md) unless you need specific AC content.
+
+### Refresh meta.md
+
+Regenerate a meta.md from its children when stale:
+
+1. Read all sibling/child files in the directory
+2. Parse frontmatter from each
+3. Rebuild the summary table (counts, priorities, coverage stats)
+4. Write updated meta.md preserving the `id` and `type` fields
+
+**Staleness check**: Compare `generated_at` in meta.md frontmatter against
+`stat()` mtimes of children. If any child is newer, regenerate.
+
+**When to refresh**:
+- Before displaying requirements status to user
+- Before crew gate evaluation
+- After batch AC creation
+- On explicit user request
+
+### Coverage Query
+
+Check which ACs have trace links:
+
+```
+For each AC in requirements/**/*.md where type: acceptance-criterion:
+  - Has IMPLEMENTED_BY? → code coverage
+  - Has TESTED_BY? → test coverage
+  - Has VERIFIES? → verification coverage
+```
+
+**Output format**:
+```
+Coverage: auth
+  US-001: 3/3 ACs, 1/3 implemented, 0/3 tested
+  US-002: 2/2 ACs, 0/2 implemented, 0/2 tested
+  Total: 5 ACs, 1 implemented (20%), 0 tested (0%)
+```
+
+### Gap Analysis
+
+Find structural problems:
+
+- **Orphan ACs**: AC files not referenced in parent story meta.md
+- **Empty stories**: Story directories with meta.md but no AC files
+- **Missing traces**: P0 ACs without IMPLEMENTED_BY or TESTED_BY
+- **Broken traces**: Trace targets that don't exist on disk
+- **Stale meta.md**: Generated timestamps older than children
+- **ID mismatches**: `id:` field doesn't match file path
+
+### Lint
+
+Validate graph structure:
+
+```
+For each .md in requirements/**/:
+  1. Has valid YAML frontmatter with required fields
+  2. id: matches relative path from requirements/
+  3. type: is a valid node type
+  4. traces: targets exist (warn, don't fail — code may not exist yet)
+  5. ACs have: priority, category, story
+  6. Stories have: priority, complexity, persona, status
+  7. meta.md tables match actual children
+```
+
+**Fix mode**: `--fix` auto-corrects:
+- Regenerate stale meta.md files
+- Update `id:` to match current path
+- Add missing AC references to parent meta.md
+
+## Integration with traceability.py
+
+The navigate skill reads graph nodes directly. For cross-phase queries
+that span beyond requirements (design, code, tests, evidence),
+`traceability.py` provides BFS traversal.
+
+**Bridge**: When navigate finds `IMPLEMENTED_BY` or `TESTED_BY` traces
+in frontmatter, these are the authoritative links for the requirement
+layer. `traceability.py` can read these as an additional data source
+alongside its DomainStore links.
+
+## Integration with search
+
+Requirements graph nodes are indexable by `search:index`:
+
+```bash
+/wicked-garden:search:index requirements/
+```
+
+Enables queries like:
+- "All P0 ACs without TESTED_BY" (frontmatter + FTS5)
+- "All ACs tagged 'authentication'" (tag search)
+- "Which stories trace to src/auth/" (reverse trace)
+
+## Progressive Disclosure
+
+- **SKILL.md** (this file): Commands, query patterns, integration
+- **refs/meta-templates.md**: Copy-paste meta.md templates for each level