bigpowers 1.2.2 → 1.3.0

package/scripts/yaml-tools.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Minimal YAML helpers for bigpowers specs (no external deps)."""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _parse_simple_yaml(text: str) -> dict[str, Any]:
+    """Parse flat and one-level-nested YAML (no lists of objects)."""
+    root: dict[str, Any] = {}
+    stack: list[tuple[int, dict[str, Any]]] = [(0, root)]
+    for raw in text.splitlines():
+        if not raw.strip() or raw.strip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        line = raw.strip()
+        if ":" not in line:
+            continue
+        key, _, val = line.partition(":")
+        key = key.strip()
+        val = val.strip()
+        while stack and indent < stack[-1][0]:
+            stack.pop()
+        cur = stack[-1][1]
+        if val == "":
+            nxt: dict[str, Any] = {}
+            cur[key] = nxt
+            stack.append((indent + 2, nxt))
+        else:
+            if val in ("true", "false"):
+                cur[key] = val == "true"
+            elif val.startswith('"') and val.endswith('"'):
+                cur[key] = val[1:-1]
+            elif val.startswith("'") and val.endswith("'"):
+                cur[key] = val[1:-1]
+            else:
+                try:
+                    if "." in val:
+                        cur[key] = float(val)
+                    else:
+                        cur[key] = int(val)
+                except ValueError:
+                    cur[key] = val
+    return root
+
+
+def _dump_value(val: Any, indent: int) -> str:
+    sp = " " * indent
+    if isinstance(val, dict):
+        lines = []
+        for k, v in val.items():
+            if isinstance(v, dict):
+                lines.append(f"{sp}{k}:")
+                lines.append(_dump_value(v, indent + 2).rstrip())
+            elif isinstance(v, bool):
+                lines.append(f"{sp}{k}: {'true' if v else 'false'}")
+            elif isinstance(v, (int, float)):
+                lines.append(f"{sp}{k}: {v}")
+            else:
+                s = str(v).replace('"', '\\"')
+                lines.append(f'{sp}{k}: "{s}"')
+        return "\n".join(lines) + "\n"
+    return f"{sp}{val}\n"
+
+
+def dump_yaml(data: dict[str, Any]) -> str:
+    return _dump_value(data, 0)
+
+
+def set_path(path: Path, dotted_key: str, value: str) -> None:
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    data = _parse_simple_yaml(text) if text.strip() else {}
+    parts = dotted_key.split(".")
+    cur: Any = data
+    for part in parts[:-1]:
+        if part not in cur or not isinstance(cur[part], dict):
+            cur[part] = {}
+        cur = cur[part]
+    last = parts[-1]
+    if value.lower() in ("true", "false"):
+        cur[last] = value.lower() == "true"
+    else:
+        try:
+            cur[last] = int(value)
+        except ValueError:
+            try:
+                cur[last] = float(value)
+            except ValueError:
+                cur[last] = value.strip('"').strip("'")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_yaml(data), encoding="utf-8")
+
+
+def validate_file(path: Path, required_keys: list[str]) -> list[str]:
+    errors: list[str] = []
+    if not path.exists():
+        return [f"missing: {path}"]
+    text = path.read_text(encoding="utf-8")
+    data = _parse_simple_yaml(text)
+    for key in required_keys:
+        parts = key.split(".")
+        cur: Any = data
+        for part in parts:
+            if not isinstance(cur, dict) or part not in cur:
+                errors.append(f"{path}: missing key '{key}'")
+                break
+            cur = cur[part]
+    return errors
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: yaml-tools.py set <file> <dotted.key> <value>", file=sys.stderr)
+        return 2
+    cmd = sys.argv[1]
+    if cmd == "set":
+        _, _, file, key, val = sys.argv
+        set_path(Path(file), key, val)
+        return 0
+    if cmd == "validate":
+        root = Path(sys.argv[2]) if len(sys.argv) > 2 else Path("specs")
+        errors: list[str] = []
+        errors += validate_file(root / "state.yaml", ["active_flow"])
+        errors += validate_file(
+            root / "release-plan.yaml", ["release", "release.version", "epics"]
+        )
+        errors += validate_file(
+            root / "execution-status.yaml", ["development_status"]
+        )
+        if errors:
+            for e in errors:
+                print(e)
+            return 1
+        print("OK")
+        return 0
+    print(f"unknown command: {cmd}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/session-state/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: session-state
 model: haiku
-description: Track implementation decisions and progress in specs/STATE.md to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
+description: Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.
 ---
 
 # Session State
@@ -10,82 +10,91 @@ Track the current state of implementation, including decisions made, pending tas
 
 ## Goal
 
-Maintain a single source of truth for the *current* state of the work in `specs/STATE.md`. This file acts as the project's short-term memory, complementing the long-term memory of `specs/CONTEXT.md` and the task-specific instructions in `specs/RELEASE-PLAN.md`.
+Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/plans/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.
 
-## Handoff block (cold start)
+Legacy `specs/state.yaml` is deprecated — use `state.yaml` only.
 
-When ending a session or before a context-heavy spawn, write a **Handoff** section at the top of STATE.md:
+## Handoff block (cold start)
 
-```markdown
-## Handoff
-- **Last step completed:** ...
-- **Open decisions:** ...
-- **Required reading:** CONVENTIONS.md, RELEASE-PLAN.md story X.Y, ...
-- **Next skill:** verify-work | develop-tdd | ...
+When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
+
+```yaml
+handoff:
+  last_step_completed: "e02s01 verify-work passed"
+  open_decisions:
+    - "Use folder mode for e07 (>5 stories)"
+  required_reading:
+    - CONVENTIONS.md
+    - specs/epics/e02-verification/epic.yaml
+  next_skill: develop-tdd
 ```
 
 ## Strategic compaction
 
 | Trigger | Action |
 |---------|--------|
-| Phase transition (Plan → Build → Verify) | Compact Handoff; archive verbose decisions to ADR |
+| Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR |
 | Context > 70% estimated | Run terse-mode for status only; move detail to specs/ |
-| Before `dispatch-agents` wave | STATE.md only channel between spawns |
+| Before `dispatch-agents` wave | `state.yaml` only channel between spawns |
 
 ## Workflow
 
 ### 1. Initialize (Session Start)
 
-If `specs/STATE.md` does not exist, or if starting a new major phase:
+If `specs/state.yaml` does not exist, or if starting a new major phase:
 
-- [ ] Read `specs/RELEASE-PLAN.md` and `specs/SCOPE.md`.
-- [ ] Get git metadata: `git branch --show-current` and `git rev-parse HEAD`.
-- [ ] Create `specs/STATE.md` with the current milestone, git metadata, pending tasks, and any active decisions.
+- [ ] Read `specs/release-plan.yaml` and `specs/requirements/SCOPE_LATEST.yaml`.
+- [ ] Get git metadata: `git branch --show-current` and `git rev-parse --short HEAD`.
+- [ ] Create `specs/state.yaml` with active flow, git, handoff, and epic cycle if in build.
 
 ### 2. Load (Context Refresh)
 
 When starting a new session or after a significant context flush:
 
-- [ ] Read `specs/STATE.md` to understand where the previous agent left off.
-- [ ] Verify the current state matches the actual codebase (run `git branch` and `git diff`).
-- [ ] Surface any discrepancies between recorded git hash and current hash.
+- [ ] Read `specs/state.yaml` to understand where the previous agent left off.
+- [ ] Read `specs/execution-status.yaml` for story progress (do not infer from release-plan).
+- [ ] Verify git matches `state.yaml` `git.branch` / `git.hash`.
 
 ### 3. Update (Decision Point/Milestone)
 
 Whenever a significant decision is made or a milestone is reached:
 
-- [ ] Update git metadata if the branch or hash has changed.
-- [ ] Update the `Active Decisions` section with the rationale for the choice.
-- [ ] Mark completed tasks as done.
-- [ ] Add new pending tasks discovered during implementation.
-- [ ] Record any "Open Questions" that need user clarification.
-
-## File Format: specs/STATE.md
-
-```markdown
-# Session State: [Feature Name]
-
-## Current Milestone
-[What is being worked on right now]
-
-## Git Metadata
-- **Branch**: [branch-name]
-- **Hash**: [commit-hash]
-
-## Pending Tasks
-...
-```
-- [ ] Task 2
-
-## Active Decisions
-- **Decision Name**: [Rationale and impact]
-
-## Open Questions
-- [Question for the user]
+- [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Update `handoff.open_decisions` with rationale.
+- [ ] Update `epic_cycle` when advancing `ship-epic` steps.
+- [ ] Record open questions under `handoff.open_decisions` or an ADR.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+## File Format: specs/state.yaml
+
+```yaml
+active_flow: build_epic       # planning | build_epic | fix_bug
+active_epic_id: e02
+active_story_id: e02s01       # required when epic mode: folder
+active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
+release:
+  target_version: "3.0.0"
+  last_tag: null
+  last_publish: null
+epic_cycle:
+  current_step: develop-tdd
+  next_skill: develop-tdd
+  completed_steps: [kickoff-branch]
+bug_cycle:
+  current_step: null
+  completed_steps: []
+git:
+  branch: feat/e02-verify
+  hash: abc1234
+handoff:
+  last_step_completed: null
+  open_decisions: []
+  next_skill: survey-context
 ```
 
 ## Anti-Patterns
 
-- **Duplicate Plan**: Don't just copy `specs/RELEASE-PLAN.md`. The plan is the *intended* path; the state is the *actual* progress and the deviations from that path.
-- **Stale State**: Forgetting to update `specs/STATE.md` after a major refactor or decision.
-- **Verbose History**: Keep it focused on the *current* state. Use git history for the past.
+- **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.
+- **Stale State**: Forgetting to update `state.yaml` after a major refactor or decision.
+- **Status in release-plan**: Story/epic status lives only in `execution-status.yaml`.

package/setup-environment/SKILL.md

@@ -15,7 +15,7 @@ Idempotent prep so BUILD phase commands succeed on first run.
 3. Install dependencies (`npm ci`, `bundle install`, etc.) — prefer lockfile installs.
 4. Copy `.env.example` → `.env` if documented; never commit secrets.
 5. Run smoke: lint + one fast test or `--version` on key tools.
-6. Record versions in `specs/STATE.md` under Environment.
+6. Record versions in `specs/state.yaml` under Environment.
 
 ## Verify
 

package/slice-tasks/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: slice-tasks
-description: Break a plan or PRD into independently-grabbable vertical-slice tasks in specs/TASKS.md. Use after scope-work or plan-release, before plan-work, when user wants implementation tickets or tracer-bullet slices.
+description: Break a plan or PRD into vertical-slice stories in specs/epics/ (replaces legacy TASKS.md). Use after scope-work or plan-release, before plan-work.
 model: sonnet
 ---
 
 # Slice Tasks
 
-Produce `specs/TASKS.md` — vertical slices, each independently deliverable and testable.
+Produce **epic shard stories** in `specs/epics/eNN-*.yaml` — vertical slices, each independently deliverable and testable. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use epics + `execution-status.yaml`.
 
 ## Process
 
-1. Read `specs/SCOPE.md` and/or `specs/RELEASE-PLAN.md`.
+1. Read `specs/requirements/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`.
 2. Cut **tracer-bullet slices** (thin end-to-end paths first, then depth).
-3. Each task entry: `id`, `title`, `depends-on:` (optional), `verify:` command, `story:` link.
-4. Order by WSJF within the file.
+3. Each story: `id` (e.g. `e03s01`), `title`, optional `depends-on` in task desc, `tasks[]` with `desc` + `verify`.
+4. Order by WSJF in `release-plan.yaml` epic list.
 
 > **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration.
 
 ## Verify
 
-→ verify: `test -f specs/TASKS.md && grep -c "verify:" specs/TASKS.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c 'id: e' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/survey-context/SKILL.md

@@ -14,23 +14,30 @@ Read the project's current state and give a phase map + next-skill recommendatio
 
 If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
 
-### 2. Read specs/
+### 2. Read specs/ (YAML-first)
 
 Scan the `specs/` directory if it exists:
 
 ```
 specs/
-├── CONTEXT.md          → domain model status
-├── UBIQUITOUS_LANGUAGE.md → glossary status
-├── SCOPE.md            → scope definition status
-├── TASKS.md            → task breakdown status
-├── RELEASE-PLAN.md     → implementation plan status
-├── REFACTOR.md         → refactor plan status
-├── bugs/               → bug investigations (BUG-*.md) + BUG-LOG.md
-└── SPIKE-*.md          → spike learning notes
+├── state.yaml                  → session: active_flow, epic, git, handoff
+├── release-plan.yaml           → target version, WSJF epic index
+├── execution-status.yaml       → flat story/epic status
+├── planning-status.yaml        → discover-phase checklist (optional)
+├── requirements/
+│   ├── VISION_LATEST.yaml
+│   ├── SCOPE_LATEST.yaml
+│   └── GLOSSARY_LATEST.yaml
+├── plans/                      → TECH_STACK, TEST_PLAN, etc.
+├── epics/                      → eNN shards (flat yaml or eNN/stories/)
+└── bugs/                       → BUG-*.md + registry.yaml
 ```
 
-For each file found, note: does it exist? Is it complete? Does it have open items?
+For each YAML file found, note: exists? keys populated? `handoff.next_skill`?
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if YAML exists.
+
+→ verify: `bash scripts/validate-specs-yaml.sh 2>/dev/null || echo "YAML layout incomplete"`
 
 ### 3. Read CLAUDE.md
 
@@ -44,7 +51,7 @@ git log --oneline -5
 git branch --show-current
 ```
 
-Note: is there a feature branch active? Are there uncommitted changes? Are there unpushed commits?
+Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
 
 ### 5. Map the lifecycle phase
 
@@ -52,33 +59,36 @@ Based on what you've found, identify which PMBOK phase this project is currently
 
 | Phase | Signals |
 |-------|---------|
-| **Discover** | No specs/ yet, or only rough notes |
-| **Design** | specs/SCOPE.md exists but no RELEASE-PLAN.md |
-| **Plan** | specs/TASKS.md or RELEASE-PLAN.md exists; on `main`/`master` branch |
+| **Discover** | No `requirements/SCOPE_LATEST.yaml` yet, or only rough notes |
+| **Design** | SCOPE exists but no `release-plan.yaml` |
+| **Plan** | `release-plan.yaml` exists; on `main`/`master` branch |
 | **Initiate** | On a feature branch; no code changes yet |
-| **Execute** | RELEASE-PLAN.md exists; on feature branch; steps in progress |
-| **Verify** | Implementation done; run `verify-work` or `run-evals`; awaiting UAT |
-| **Bug** | `specs/bugs/BUG-*.md` exists; on `main`/`master` |
+| **Execute** | `state.yaml` `active_flow: build_epic`; epic shard in progress |
+| **Verify** | Implementation done; run `verify-work` or `run-evals` |
+| **Bug** | `state.yaml` `active_flow: fix_bug` or open `specs/bugs/BUG-*.md` |
 | **Review** | All code written; no PR yet |
 | **Integrate** | PR open; tests passing |
 | **Sustain** | Ongoing; no active task |
 
+Prefer `specs/state.yaml` `active_flow` and `handoff.next_skill` when present.
+
 ### 6. Suggest next skill
 
 Based on the phase and state, recommend the most useful next step:
 
 - **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
-- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan`.
-- **If in Execute phase**: Suggest `develop-tdd` (continue step X) or `execute-plan`.
-- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals` (capability evals).
+- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan` or `ship-epic`.
+- **If in Execute phase**: Suggest `ship-epic` (resume) or `develop-tdd` for `active_story_id`.
+- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals`.
 
 Example:
 ```
-Phase: Plan
-Active branch: main
-RELEASE-PLAN.md: exists
+Phase: Execute
+Active branch: feat/e02-verify (state.yaml matches)
+release-plan.yaml: v3.0.0, 10 epics
+active_epic_id: e02
 
-Suggested next: kickoff-branch (to create feature/auth branch)
+Suggested next: ship-epic (resume e02s01 at develop-tdd)
 ```
 
 Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
@@ -87,8 +97,9 @@ Be specific — name the exact skill and why. If multiple options exist, list th
 
 If something looks wrong:
 - Broken tests in the baseline
-- `specs/bugs/BUG-*.md` open with no active fix branch
-- RELEASE-PLAN.md with missing verify commands or Verification Script sections
-- CONVENTIONS.md violations in recent commits
+- Open `specs/bugs/BUG-*.md` with no active fix branch
+- Epic shards missing `verify:` on tasks
+- `validate-specs-yaml.sh` fails
+- Git hash in `state.yaml` stale vs `git rev-parse`
 
 Report blockers first, before recommendations.

package/trace-requirement/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: trace-requirement
 model: haiku
-description: Link story IDs from specs/RELEASE-PLAN.md to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
+description: Link story IDs from specs/release-plan.yaml + epic shards to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
 ---
 
 # Trace Requirement
 
-Build a traceability matrix from `specs/RELEASE-PLAN.md` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
+Build a traceability matrix from `specs/release-plan.yaml + epic shards` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
 
 ## Pre-flight
 
-> **HARD GATE** — `specs/RELEASE-PLAN.md` must exist. If it doesn't, run `plan-release` first.
+> **HARD GATE** — `specs/release-plan.yaml + epic shards` must exist. If it doesn't, run `plan-release` first.
 
-→ verify: `[ -f specs/RELEASE-PLAN.md ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+→ verify: `[ -f specs/release-plan.yaml + epic shards ] && echo "ready" || echo "BLOCKED: run plan-release first"`
 
-Read `specs/RELEASE-PLAN.md` fully before proceeding.
+Read `specs/release-plan.yaml + epic shards` fully before proceeding.
 
 ## Process
 
 ### 1. Extract story IDs
 
-From RELEASE-PLAN.md, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
+From release-plan.yaml, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
 
-→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/RELEASE-PLAN.md | sort -u`
+→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/release-plan.yaml + epic shards | sort -u`
 
 ### 2. Search for story tags in code
 
@@ -41,7 +41,7 @@ For each story ID:
 - **Tested**: list test files that contain `// story: X.Y`
 - **Dark**: story has no tag in any file — flag as unimplemented
 
-For each tagged file with no matching story ID in RELEASE-PLAN.md:
+For each tagged file with no matching story ID in release-plan.yaml:
 - **Orphan**: code exists but story was removed or never planned — flag for cleanup
 
 ### 4. Write specs/TRACEABILITY.md

package/using-bigpowers/SKILL.md

@@ -6,7 +6,7 @@ description: One-time bootstrap that introduces the bigpowers skills system, the
 
 # Using bigpowers
 
-Welcome to **bigpowers** — a lifecycle of **59** agent skills for production-ready, TDD-driven software by solo developers.
+Welcome to **bigpowers** — a lifecycle of **61** agent skills for production-ready, TDD-driven software by solo developers.
 
 ## Install
 
@@ -78,23 +78,24 @@ If you work alone and do not want PR ceremony every task:
 
 You still use worktrees, protected `main`, and verification gates — only the integrate step changes.
 
-## Obsidian wiki cockpit (optional)
+## YAML cockpit and dashboard
 
-For accumulated project understanding and a read-only PM view:
+Operational source of truth:
 
-1. Read [profiles/obsidian-wiki.md](../profiles/obsidian-wiki.md).
-2. Open `specs/` as an Obsidian vault; landing page `COCKPIT.md`.
-3. Run `maintain-wiki` **sync** before merge (merge gate).
+- `specs/state.yaml` — session, active epic/story, handoff
+- `specs/release-plan.yaml` — release index and epic list
+- `specs/epics/eNN-*.yaml` — stories and tasks with `verify`
+- `specs/execution-status.yaml` — done/pending per story
 
-Operational specs (STATE, RELEASE-PLAN) stay source of truth; `specs/wiki/` is LLM-synthesized navigation.
+Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir=<abs>` and `GET /cockpit.html` for a read-only PM view.
 
 ## Key conventions
 
 - **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
 - **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
 - **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
-- **verify: every step.** Every task in `specs/RELEASE-PLAN.md` must have a `verify: <runnable command>`. Evidence over claims.
-- **59 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+- **verify: every step.** Every epic task must have `verify: <runnable command>`. Evidence over claims.
+- **61 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this
 

package/validate-fix/SKILL.md

@@ -59,7 +59,7 @@ For every bug fixed, add at least one prevention layer:
 - [ ] At least one hardening mechanism added
 - [ ] Hardening mechanism is tested
 
-### 6. Update the bug file and BUG-LOG.md
+### 6. Update the bug file and registry.yaml
 
 Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
 
@@ -74,10 +74,10 @@ Find the most recent `specs/bugs/BUG-*.md` file and append the resolution:
 **Commit:** `fix(<scope>): <description>`
 ```
 
-Also update the corresponding row in `specs/bugs/BUG-LOG.md`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
+Also update the corresponding row in `specs/bugs/registry.yaml`: set `status` to `fixed`, fill in `files_changed`, `approach`, `risk_level`, `commit_message`, and any other resolution fields.
 
 - [ ] specs/bugs/BUG-*.md updated with resolution
-- [ ] specs/bugs/BUG-LOG.md row updated with resolution fields
+- [ ] specs/bugs/registry.yaml row updated with resolution fields
 
 ### 7. Behavioral Proof (HARD GATE)
 

package/verify-work/SKILL.md

@@ -1,39 +1,34 @@
 ---
 name: verify-work
-description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code, when a story needs proof it works.
+description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.
 model: haiku
 ---
 
 # Verify Work
 
-> **HARD GATE** — No story is "done" until its `## Verification Script` from RELEASE-PLAN.md is confirmed by the user or agent with evidence.
-
-> **HARD GATE** — Do NOT run verify-work on `main` or `master`. Run from the feature branch or worktree created by `kickoff-branch`.
+> **HARD GATE** — No story is "done" until manual UAT for the active story is confirmed with evidence.
+>
+> **HARD GATE** — Do NOT run on `main` or `master`. Use the feature branch from `kickoff-branch`.
 
 Review answers "is the code good?"; Verify answers "does the built thing do what was promised?"
 
 ## Process
 
-0. **Branch check** (before any gates):
-
-```bash
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-# Must not be main or master — run kickoff-branch first
-```
+0. **Branch check** — must not be `main`/`master`.
 
-1. Read the story's `## Verification Script` from `specs/RELEASE-PLAN.md`.
+1. Read active story tasks and any **Verification Script** notes in `specs/epics/{active}.yaml` or story `.md` under `specs/epics/eNN/stories/`.
 2. **Cold-start smoke** (if app): stop server, clear caches, boot from scratch.
-3. Run mechanical gates: build → typecheck → lint → full test suite (commands from CLAUDE.md).
-4. **Step-by-step UAT**: one user-observable action at a time; record pass/fail.
-5. **Gaps loop**: failed steps → log as Gaps → feed back to `plan-work` → re-verify until pass.
+3. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md`).
+4. **Step-by-step UAT** — one user-observable action at a time.
+5. **Gaps loop** — failures → log → `plan-work` → re-verify.
 
 ## UAT dialogue
 
-- Pass: user confirms `yes` / `next` / `ok` per step.
-- Fail: capture expected vs actual; do not mark story done.
+- Pass: user confirms per step.
+- Fail: capture expected vs actual; do not mark done in `execution-status.yaml`.
 
 ## Verify
 
-→ verify: `grep -c "Verification Script" specs/RELEASE-PLAN.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `grep -c 'verify:' specs/epics/*.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`
 
 See [REFERENCE.md](REFERENCE.md) for cold-start and gaps template.