You are Codex. 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_codex/processes/<process>_codex/PROCESS.md and contains section:
  "## Canonical Story Order (Sequential Default)"
  then that order is binding.
- Else, use filename order inside stories_codex/<process>_codex/ 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 Codex 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_codex/story-runner_codex/
      - run_stories.ps1
      - run_autopilot_detached.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_codex/<Process>_codex)
   - -StoriesDir <path>       (default = <RepoRoot>/stories_codex/<Process>_codex)
   - -ProcessFile <path>      (default = <RepoRoot>/docs_codex/processes/<Process>_codex/PROCESS.md)
   - -GatesFile <path>        (optional; one repo-root command per line)
   - -CodexCommand <string>   (required; command template)
   - -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_codex/<Process>_codex/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_codex/<Process>_codex/<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 Codex prompt file and call Codex 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_codex/<Process>_codex/.merge.lock
- Use try/finally to guarantee release.
- If lock cannot be acquired: FAIL (non-zero).

4) Codex invocation template
- -CodexCommand is a format string with placeholders:
  {WORKDIR} {STORYFILE} {PLAYBOOK} {PROCESS} {STORY_ID} {PROMPTFILE}
- Runner writes prompt to tools_codex/story-runner_codex/.tmp/<Process>/<StoryId>/codex_prompt.txt

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, start it once (detached) to prove it boots, writes `status.json`, and keeps running.
- Auto-detect the process name:
  - If docs_codex/processes/<process>_codex/PROCESS.md exists for exactly one process, use that <process>.
  - Else if stories_codex/<process>_codex/ 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_codex/story-runner_codex/run_autopilot_detached.ps1 -Process "<process>" -CodexCommand 'type "{PROMPTFILE}" | codex --dangerously-bypass-approvals-and-sandbox exec -C "{WORKDIR}" -' -GatesFile "tools_codex/story-runner_codex/sample_gates.txt"

- Detach requirement (hard):
  - The above command MUST return control to the terminal quickly (runner continues in background).
  - After starting, verify within 10 seconds that a new `tools_codex/story-runner_codex/runs/<process>/<run_id>/status.json` exists and `last_update_utc` advances.

- Capture and print:
  - the command used
  - RunId + RunDir + log paths
  - the new `status.json` path + a 5-10s heartbeat/update check
- If it fails to start or `status.json` is not updating: FIX and re-run until it starts cleanly or fail-closed with a clear root cause.

README REQUIREMENT (hard)
- tools_codex/story-runner_codex/README.md MUST include a Quickstart section containing the exact command above (with <process> placeholder and with CodexCommand template), and explain that:
  - If the LLM agent is running locally with command execution enabled (e.g., skip-permissions mode), it can run the Quickstart command itself.
  - Otherwise, the user runs the Quickstart command once to start the autopilot.