You are Claude Code. Implement an unattended, deterministic BMAD story runner for this repo.

GOAL
- Run BMAD stories end-to-end with ZERO human intervention:
  story -> implement -> verify -> commit -> merge into integration worktree/branch -> next story.
- Default mode is SEQUENTIAL and MUST be deterministic (never random order).
- Parallel/waves are OPTIONAL and must be opt-in. If waves are enabled later, merges still happen sequentially.

NON-INTERACTIVE (hard)
- Never ask questions. Never pause for confirmation.
- If anything is ambiguous, FAIL-CLOSED:
  - print a clear error message
  - exit with non-zero code
- The runner must stop immediately on any failure (verification/gates/allowlist/merge).

CONTEXT (current behavior)
- Stories already merge automatically at the end when run sequentially into folder "main-merge" which is also a separate worktree.
- Keep this behavior. Do NOT add manual steps. If something is missing, implement it so sequential "merge then next" is automatic.

CONSTRAINTS (hard)
- No broad refactors.
- Keep changes focused: max 250 lines per code file, max 15 functions per file.
- Prefer PowerShell for Windows (user runs on Windows 11) and keep scripts readable.
- Deterministic order: stories must NEVER run in random order.

SINGLE SOURCE OF TRUTH FOR ORDER (choose automatically)
- If a process file exists at docs/processes/<process>/PROCESS.md and contains section:
  "## Canonical Story Order (Sequential Default)"
  then that order is binding.
- Else, use filename order inside stories_claude/<process>/ with strict story ID naming:
  <PREFIX>-<NNN>.md (e.g., OPS-001.md, OPS-002.md). Sort by numeric <NNN> then by prefix.

STORY FORMAT EXPECTATIONS (hard)
- Each story is a .md file.
- Each Acceptance Criteria uses the literal markers:
  - Verification (repo-root): `<command>`
  - Expected: `<...>`
  or
  - Verification (cwd=<path>): `<command>`
  - Expected: `<...>`
- If markers are missing or malformed: FAIL (non-zero).

ALLOWLIST ENFORCEMENT (hard)
- Each story contains a "Touched paths allowlist" section.
- The runner must enforce allowlist using:
  `git diff --name-only <BASE_REF_SHA>...HEAD` subset-of allowlist prefixes.
  - Implementation detail (PowerShell): handle empty output as "no changed files" and avoid calling `.Trim()` on potentially null output (use `@(git ... diff --name-only ...)` and iterate the lines).
- BASE_REF_SHA MUST be a commit SHA captured BEFORE Claude starts implementing the story:
  - Set BASE_REF_SHA = `git rev-parse HEAD` in the integration worktree (main-merge) at the start of each story iteration.
  - Log BASE_REF_SHA per story.

WHAT TO BUILD
1) Folder structure (create if missing):
   - tools_claude/story-runner/
     - run_stories.ps1
     - lib/
       - parse_process.ps1
       - parse_story_verifications.ps1
       - parse_touched_paths.ps1
       - git_worktrees.ps1
       - run_commands.ps1
       - lock.ps1
     - README.md (how to use + examples)
     - sample_gates.txt

2) run_stories.ps1 (main entry)
    Inputs (flags):
   - -RepoRoot <path>         (default = current dir)
   - -Process <name>          (required; used for paths and branch names)
   - -OriginMain <ref>        (default = origin/main)
   - -IntegrationBranch <name>(default = <Process>)
   - -WorktreesRoot <path>    (default = <RepoRoot>/worktrees_claude/<Process>)
   - -StoriesDir <path>       (default = <RepoRoot>/stories_claude/<Process>)
   - -ProcessFile <path>      (default = <RepoRoot>/docs/processes/<Process>/PROCESS.md)
   - -GatesFile <path>        (optional; one repo-root command per line)
    - -ClaudeCommand <string>  (required; command template for Claude Code CLI)
    - -BaseRefShaOverride <sha> (optional; for debugging only)

   Preflight (hard):
   - Runner MUST fail early if WorktreesRoot is not writable (create+delete a small temp file in that folder).
   - Runner MUST ensure repo `.venv` is ready before running any story verification:
     - Require `scripts/venv.ps1` to exist and run it once at startup (fail-closed on error).

   Behavior per story:
   a) Ensure integration worktree exists: worktrees_claude/<Process>/main-merge on branch <IntegrationBranch>.
   a.1) Ensure `.venv` is available inside the integration worktree (prefer junction to `<RepoRoot>/.venv`, fallback to a physical copy if junction is blocked).
   b) Capture BASE_REF_SHA in integration worktree before starting story implementation.
   c) Ensure story worktree exists: worktrees_claude/<Process>/<STORY_ID> on branch <IntegrationBranch>-<STORY_ID>, startpoint=<IntegrationBranch>.
   c.1) Ensure `.venv` is available inside the story worktree (same policy as a.1).
   d) Generate a SINGLE-STORY Claude prompt file and call Claude Code in the story worktree.
   e) Parse and run story verification commands (repo-root unless cwd specified).
   e.1) Verification command execution must force `python` to resolve to the worktree venv (prepend `<worktree>/.venv/Scripts` to PATH for each command-run, or require explicit `.venv\\Scripts\\python.exe` usage).
   f) Run optional gates from GatesFile.
   g) Enforce touched paths allowlist subset check using BASE_REF_SHA.
   h) Commit if dirty.
   i) Acquire exclusive merge lock.
   j) Merge story branch into integration branch in integration worktree (main-merge) with --no-ff.
   k) Release lock.
   l) Run gates on integration worktree.
   m) Continue to next story.

3) Locking (hard)
- Implement exclusive merge lock at: worktrees_claude/<Process>/.merge.lock
- Use try/finally to guarantee release.
- If lock cannot be acquired: FAIL (non-zero).

4) Claude Code invocation template
- -ClaudeCommand is a format string with placeholders:
  {WORKDIR} {STORYFILE} {PLAYBOOK} {PROCESS} {STORY_ID} {PROMPTFILE}
- Runner writes prompt to tools_claude/story-runner/.tmp/<Process>/<StoryId>/claude_prompt.txt
- ClaudeCommand MUST:
  - run inside {WORKDIR} (do not rely on a non-existent --cwd flag)
  - pipe the prompt file content via stdin (avoid Windows command-line length limits)
  - include --dangerously-skip-permissions so the agent can run all required commands unattended
  - be enforced by the runner (fail-closed if the flag is missing)
  - NOT be made optional (do not add a disable flag/setting)
  Example template:
  pwsh -NoProfile -Command "Set-Location -LiteralPath ''{WORKDIR}''; Get-Content -LiteralPath ''{PROMPTFILE}'' -Raw | claude --dangerously-skip-permissions -p"

5) Observability
- Print story id + BASE_REF_SHA + commands run + exit codes.
- On failure: print last command + stop non-zero.

6) Tests
- Minimal Pester tests or self-check scripts for parsing:
  - Canonical order parsing
  - Verification command parsing (markers)
  - Allowlist parsing/subset check

DELIVERABLES
- All new/changed files committed.
- README explains usage and assumptions.

NOW IMPLEMENT
- Build the runner exactly as above.
- Preserve the existing "sequential merge then next" experience.

FINAL: AUTO-EXECUTE AFTER BUILD (hard)
- After implementing and committing the runner, execute it once end-to-end to prove it works.
- Auto-detect the process name:
  - If docs/processes/<process>/PROCESS.md exists for exactly one process, use that <process>.
  - Else if stories_claude/<process>/ exists for exactly one process directory, use that.
  - Else FAIL with a clear message (do not guess).

- Run command from repo root (PowerShell):
  pwsh tools_claude/story-runner/run_stories.ps1 -Process "<process>" -ClaudeCommand 'pwsh -NoProfile -Command "Set-Location -LiteralPath ''{WORKDIR}''; Get-Content -LiteralPath ''{PROMPTFILE}'' -Raw | claude --dangerously-skip-permissions -p"' -GatesFile "tools_claude/story-runner/sample_gates.txt"

- Capture and print:
  - the command used
  - stdout/stderr tail if failure
  - exit code
- If it fails, FIX and re-run until green or fail-closed with a clear root cause.

README REQUIREMENT (hard)
- tools_claude/story-runner/README.md MUST include a Quickstart section containing the exact command above (with <process> placeholder and with ClaudeCommand template), and explain that:
  - The Quickstart requires --dangerously-skip-permissions and the runner enforces it (fail-closed if missing).
  - If the LLM agent is running locally with command execution enabled (using --dangerously-skip-permissions), it can run the Quickstart command itself.
  - Otherwise, the user runs the Quickstart command once to start the autopilot.