arcwright-ai 0.1.1.dev0__tar.gz

arcwright_ai-0.1.1.dev0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy --strict src/
+      # Exit code 5 = no tests collected; acceptable until Epic 1 stories add tests
+      - run: pytest || [ $? -eq 5 ]

arcwright_ai-0.1.1.dev0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+.venv-studio/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Arcwright AI runtime (never committed)
+.arcwright-ai/tmp/
+.arcwright-ai/runs/
+
+# mypy
+.mypy_cache/
+
+# pytest
+.pytest_cache/
+
+# ruff
+.ruff_cache/

arcwright_ai-0.1.1.dev0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.7, typer>=0.12]
+        args: [--strict]

arcwright_ai-0.1.1.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcwright_ai-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: arcwright-ai
+Version: 0.1.1.dev0
+Summary: Deterministic orchestration shell for autonomous AI agent execution
+Project-URL: Homepage, https://github.com/ProductEngineerIO/arcwright-ai
+Project-URL: Repository, https://github.com/ProductEngineerIO/arcwright-ai
+Project-URL: Issues, https://github.com/ProductEngineerIO/arcwright-ai/issues
+Author: Ed Hertzog
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: claude-code-sdk>=0.0.10
+Requires-Dist: langgraph<1.0,>=0.2
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: typer[all]<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Arcwright AI
+
+Deterministic orchestration shell for autonomous AI agent execution.
+
+Arcwright AI takes BMAD planning artifacts (PRD, Architecture, Epics, Stories) and autonomously executes them through Claude, enforcing validation gates, tracking decision provenance, and writing structured run artifacts after every execution.
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Project Setup](#project-setup)
+- [Running Stories](#running-stories)
+- [Run Artifacts](#run-artifacts)
+- [Understanding the Output](#understanding-the-output)
+- [LangGraph Studio](#langgraph-studio)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+- **Python 3.11+** (3.14 recommended; see [LangGraph Studio](#langgraph-studio) for the exception)
+- **Claude API key** (Anthropic): `ARCWRIGHT_API_CLAUDE_API_KEY`
+- A project initialised with BMAD (`_spec/planning-artifacts/` containing PRD, architecture, epics, and story files)
+
+---
+
+## Installation
+
+From the `arcwright-ai/` directory:
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+Set your API key (add to your shell profile or `.env`):
+
+```bash
+export ARCWRIGHT_API_CLAUDE_API_KEY="sk-ant-..."
+```
+
+---
+
+## Project Setup
+
+Before dispatching stories, initialise Arcwright AI in your **target project** (the project whose stories you want to implement — not this repo):
+
+```bash
+# From inside the target project root:
+arcwright-ai init
+
+# Or point explicitly:
+arcwright-ai init --path /path/to/your/project
+```
+
+This creates `.arcwright-ai/` with the following layout:
+
+```
+.arcwright-ai/
+├── config.yaml       ← project-level configuration (committed)
+├── runs/             ← execution artifacts (git-ignored)
+├── worktrees/        ← git worktrees (git-ignored)
+└── tmp/              ← transient scratch space (git-ignored)
+```
+
+**`config.yaml` defaults** (edit to suit your project):
+
+```yaml
+model:
+  version: "claude-opus-4-6"
+
+limits:
+  tokens_per_story: 200000
+  cost_per_run: 10.0
+  retry_budget: 3
+  timeout_per_story: 300
+
+methodology:
+  artifacts_path: "_bmad-output"   # where your BMAD planning docs live
+  type: "bmad"
+
+scm:
+  branch_template: "arcwright-ai/{story_slug}"
+```
+
+> **API key security**: Never put your API key in `config.yaml`. Set it via
+> `ARCWRIGHT_API_CLAUDE_API_KEY` environment variable, or in the global
+> `~/.arcwright-ai/config.yaml` (user-level, outside any repo).
+
+Verify your setup:
+
+```bash
+arcwright-ai validate-setup
+```
+
+---
+
+## Running Stories
+
+Dispatch a single story by its `epic.story` identifier (e.g., story 4 of epic 2 is `2.4`):
+
+```bash
+# From inside the target project root:
+arcwright-ai dispatch --story 2.4
+
+# Dashes also work:
+arcwright-ai dispatch --story 2-4
+```
+
+The pipeline runs:
+
+```
+preflight → budget_check → agent_dispatch → validate → commit → finalize
+```
+
+Each node writes artifacts to `.arcwright-ai/runs/<run-id>/stories/<story-slug>/`.
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Story completed successfully |
+| `1`  | Unexpected error (configuration, I/O, etc.) |
+| `2`  | Story escalated (validation failed, could not auto-fix) |
+
+---
+
+## Run Artifacts
+
+Every execution produces a run directory:
+
+```
+.arcwright-ai/runs/<run-id>/
+├── run.yaml                          ← metadata: status, cost, story list
+└── stories/<story-slug>/
+    ├── context-bundle.md             ← assembled context injected into the agent
+    ├── agent-output.md               ← raw output from Claude
+    ├── validation.md                 ← V6 invariant + V3 reflexion results and decision log
+    ├── halt-report.md                ← populated only on escalation
+    └── summary.md                    ← produced by finalize node (success or halt)
+```
+
+**Run ID format**: `YYYYMMDD-HHMMSS-<4-char-id>` (e.g. `20260305-022632-4b90`)
+
+### Reading a halt report
+
+When a run escalates, check these files in order:
+
+1. **`halt-report.md`** — escalation reason, retry history, suggested fix
+2. **`validation.md`** — exact V6 invariant failures and V3 reflexion AC results
+3. **`agent-output.md`** — what Claude produced (verify files actually exist on disk before trusting V6 failures)
+
+---
+
+## Understanding the Output
+
+### `status: escalated` vs. failure
+
+`escalated` means the pipeline ran successfully but validation could not be satisfied within the retry budget. It does **not** mean the agent crashed. The agent's work (files, code) is still on disk in the target project.
+
+Escalation reasons:
+
+| Reason | Meaning |
+|--------|---------|
+| `v6_invariant_failure` | Hard rule violation (missing file, bad name, syntax error) — retries won't help without a fix |
+| `max_retries_exhausted` | V3 reflexion (AC review) kept failing after N retries |
+| `budget_exceeded` | Token/cost ceiling hit before validation passed |
+
+### False-positive V6 failures
+
+If `validation.md` shows a `file_existence` failure for a file that **does** exist on disk, check whether the path in the error has a leading backtick (e.g., `` `backend/app/routers/admin.py ``). This is a known pattern when the agent uses inline code formatting in markdown headers. The V6 checker strips backticks as of the current version. If you see this after upgrading from an older run, the files are fine — re-run to get a clean pass.
+
+---
+
+## LangGraph Studio
+
+Arcwright AI ships a [`langgraph.json`](langgraph.json) config so you can visualise and inspect the execution graph in [LangGraph Studio](https://smith.langchain.com/studio/).
+
+### Why a separate venv?
+
+The main `.venv` uses **Python 3.14**. The `langgraph-api` package (required for `langgraph dev`) depends on `pyo3`-based Rust extensions that do not yet publish wheels for Python 3.14 and cannot be compiled without matching support. A separate Python 3.13 venv is used exclusively for Studio.
+
+### One-time setup
+
+Ensure Python 3.13 is available (via Homebrew or pyenv), then:
+
+```bash
+cd arcwright-ai/
+
+# Create Studio venv with Python 3.13
+python3.13 -m venv .venv-studio
+
+# Install project + LangGraph Studio deps
+.venv-studio/bin/pip install -e ".[dev]" "langgraph-cli[inmem]"
+```
+
+### Starting Studio
+
+```bash
+cd arcwright-ai/
+.venv-studio/bin/langgraph dev
+```
+
+The server starts at `http://127.0.0.1:2024`. Open the Studio UI at:
+
+```
+https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+```
+
+You'll see the `story_graph` with all nodes and conditional edges:
+
+```
+START → preflight → budget_check ──(ok)──→ agent_dispatch → validate ──(success)──→ commit → finalize → END
+                          │                                       │
+                     (exceeded)                               (escalated)
+                          └──────────────────────────────────────┴──→ finalize → END
+                                                    ↑(retry)
+                                          validate ─┘ → budget_check
+```
+
+> A free [LangSmith](https://smith.langchain.com) account is required to use the Studio UI. The local API server itself runs without one.
+
+---
+
+## Development
+
+All development commands use the main `.venv` (Python 3.14):
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+# Prefer explicit venv invocation to avoid interpreter mismatch:
+.venv/bin/pip install -e ".[dev]"
+
+# Run tests
+.venv/bin/python -m pytest -q
+
+# Lint
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+
+# Type check
+.venv/bin/python -m mypy --strict src/
+
+# All quality gates in one pass
+.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/python -m mypy --strict src/ && .venv/bin/python -m pytest -q
+```
+
+### Python version note
+
+The project targets Python 3.11+ and is developed against 3.14. The `.venv-studio` venv (Python 3.13) is **only** for running `langgraph dev`. Do not use it for tests or type checking — results may differ.
+
+---
+
+## Troubleshooting
+
+**`ModuleNotFoundError: No module named 'arcwright_ai'`**
+
+The venv's editable install link may be stale or was not processed correctly on Python 3.14. Re-install:
+
+```bash
+cd arcwright-ai/
+.venv/bin/pip install -e .
+```
+
+This rewrites the `.pth` file. Verify with:
+
+```bash
+.venv/bin/python -c "import arcwright_ai; print(arcwright_ai.__file__)"
+```
+
+**`langgraph dev` fails with `Required package 'langgraph-api' is not installed`**
+
+You're using the main `.venv` (Python 3.14). Use `.venv-studio` instead:
+
+```bash
+.venv-studio/bin/langgraph dev
+```
+
+**Story dispatched but files don't match what validation expected**
+
+Check `.arcwright-ai/config.yaml` in the target project. The `methodology.artifacts_path` must point to the directory containing your BMAD planning artifacts (PRD, architecture, epics). Default is `_bmad-output`; adjust if your project uses `_spec/planning-artifacts` or another path.
+
+**Dev agent File List is consistently incomplete or doesn't match `git diff` output after a BMAD update**
+
+The dev-story workflow in this project includes a custom git diff audit step (Step 9 of `instructions.xml`) that was added to address a systemic issue where 67% of stories had File List discrepancies. This customization lives in `_bmad/bmm/workflows/4-implementation/dev-story/` — a directory that is gitignored and gets overwritten by BMAD framework updates.
+
+If you have recently run a BMAD update and agent File Lists are again going unaudited, the customization was likely overwritten. See the **BMAD Workflow Customizations** section in the root [`README.md`](../README.md#bmad-workflow-customizations) for the exact changes to re-apply.

arcwright_ai-0.1.1.dev0/README.md

@@ -0,0 +1,292 @@
+# Arcwright AI
+
+Deterministic orchestration shell for autonomous AI agent execution.
+
+Arcwright AI takes BMAD planning artifacts (PRD, Architecture, Epics, Stories) and autonomously executes them through Claude, enforcing validation gates, tracking decision provenance, and writing structured run artifacts after every execution.
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Project Setup](#project-setup)
+- [Running Stories](#running-stories)
+- [Run Artifacts](#run-artifacts)
+- [Understanding the Output](#understanding-the-output)
+- [LangGraph Studio](#langgraph-studio)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+- **Python 3.11+** (3.14 recommended; see [LangGraph Studio](#langgraph-studio) for the exception)
+- **Claude API key** (Anthropic): `ARCWRIGHT_API_CLAUDE_API_KEY`
+- A project initialised with BMAD (`_spec/planning-artifacts/` containing PRD, architecture, epics, and story files)
+
+---
+
+## Installation
+
+From the `arcwright-ai/` directory:
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+Set your API key (add to your shell profile or `.env`):
+
+```bash
+export ARCWRIGHT_API_CLAUDE_API_KEY="sk-ant-..."
+```
+
+---
+
+## Project Setup
+
+Before dispatching stories, initialise Arcwright AI in your **target project** (the project whose stories you want to implement — not this repo):
+
+```bash
+# From inside the target project root:
+arcwright-ai init
+
+# Or point explicitly:
+arcwright-ai init --path /path/to/your/project
+```
+
+This creates `.arcwright-ai/` with the following layout:
+
+```
+.arcwright-ai/
+├── config.yaml       ← project-level configuration (committed)
+├── runs/             ← execution artifacts (git-ignored)
+├── worktrees/        ← git worktrees (git-ignored)
+└── tmp/              ← transient scratch space (git-ignored)
+```
+
+**`config.yaml` defaults** (edit to suit your project):
+
+```yaml
+model:
+  version: "claude-opus-4-6"
+
+limits:
+  tokens_per_story: 200000
+  cost_per_run: 10.0
+  retry_budget: 3
+  timeout_per_story: 300
+
+methodology:
+  artifacts_path: "_bmad-output"   # where your BMAD planning docs live
+  type: "bmad"
+
+scm:
+  branch_template: "arcwright-ai/{story_slug}"
+```
+
+> **API key security**: Never put your API key in `config.yaml`. Set it via
+> `ARCWRIGHT_API_CLAUDE_API_KEY` environment variable, or in the global
+> `~/.arcwright-ai/config.yaml` (user-level, outside any repo).
+
+Verify your setup:
+
+```bash
+arcwright-ai validate-setup
+```
+
+---
+
+## Running Stories
+
+Dispatch a single story by its `epic.story` identifier (e.g., story 4 of epic 2 is `2.4`):
+
+```bash
+# From inside the target project root:
+arcwright-ai dispatch --story 2.4
+
+# Dashes also work:
+arcwright-ai dispatch --story 2-4
+```
+
+The pipeline runs:
+
+```
+preflight → budget_check → agent_dispatch → validate → commit → finalize
+```
+
+Each node writes artifacts to `.arcwright-ai/runs/<run-id>/stories/<story-slug>/`.
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Story completed successfully |
+| `1`  | Unexpected error (configuration, I/O, etc.) |
+| `2`  | Story escalated (validation failed, could not auto-fix) |
+
+---
+
+## Run Artifacts
+
+Every execution produces a run directory:
+
+```
+.arcwright-ai/runs/<run-id>/
+├── run.yaml                          ← metadata: status, cost, story list
+└── stories/<story-slug>/
+    ├── context-bundle.md             ← assembled context injected into the agent
+    ├── agent-output.md               ← raw output from Claude
+    ├── validation.md                 ← V6 invariant + V3 reflexion results and decision log
+    ├── halt-report.md                ← populated only on escalation
+    └── summary.md                    ← produced by finalize node (success or halt)
+```
+
+**Run ID format**: `YYYYMMDD-HHMMSS-<4-char-id>` (e.g. `20260305-022632-4b90`)
+
+### Reading a halt report
+
+When a run escalates, check these files in order:
+
+1. **`halt-report.md`** — escalation reason, retry history, suggested fix
+2. **`validation.md`** — exact V6 invariant failures and V3 reflexion AC results
+3. **`agent-output.md`** — what Claude produced (verify files actually exist on disk before trusting V6 failures)
+
+---
+
+## Understanding the Output
+
+### `status: escalated` vs. failure
+
+`escalated` means the pipeline ran successfully but validation could not be satisfied within the retry budget. It does **not** mean the agent crashed. The agent's work (files, code) is still on disk in the target project.
+
+Escalation reasons:
+
+| Reason | Meaning |
+|--------|---------|
+| `v6_invariant_failure` | Hard rule violation (missing file, bad name, syntax error) — retries won't help without a fix |
+| `max_retries_exhausted` | V3 reflexion (AC review) kept failing after N retries |
+| `budget_exceeded` | Token/cost ceiling hit before validation passed |
+
+### False-positive V6 failures
+
+If `validation.md` shows a `file_existence` failure for a file that **does** exist on disk, check whether the path in the error has a leading backtick (e.g., `` `backend/app/routers/admin.py ``). This is a known pattern when the agent uses inline code formatting in markdown headers. The V6 checker strips backticks as of the current version. If you see this after upgrading from an older run, the files are fine — re-run to get a clean pass.
+
+---
+
+## LangGraph Studio
+
+Arcwright AI ships a [`langgraph.json`](langgraph.json) config so you can visualise and inspect the execution graph in [LangGraph Studio](https://smith.langchain.com/studio/).
+
+### Why a separate venv?
+
+The main `.venv` uses **Python 3.14**. The `langgraph-api` package (required for `langgraph dev`) depends on `pyo3`-based Rust extensions that do not yet publish wheels for Python 3.14 and cannot be compiled without matching support. A separate Python 3.13 venv is used exclusively for Studio.
+
+### One-time setup
+
+Ensure Python 3.13 is available (via Homebrew or pyenv), then:
+
+```bash
+cd arcwright-ai/
+
+# Create Studio venv with Python 3.13
+python3.13 -m venv .venv-studio
+
+# Install project + LangGraph Studio deps
+.venv-studio/bin/pip install -e ".[dev]" "langgraph-cli[inmem]"
+```
+
+### Starting Studio
+
+```bash
+cd arcwright-ai/
+.venv-studio/bin/langgraph dev
+```
+
+The server starts at `http://127.0.0.1:2024`. Open the Studio UI at:
+
+```
+https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
+```
+
+You'll see the `story_graph` with all nodes and conditional edges:
+
+```
+START → preflight → budget_check ──(ok)──→ agent_dispatch → validate ──(success)──→ commit → finalize → END
+                          │                                       │
+                     (exceeded)                               (escalated)
+                          └──────────────────────────────────────┴──→ finalize → END
+                                                    ↑(retry)
+                                          validate ─┘ → budget_check
+```
+
+> A free [LangSmith](https://smith.langchain.com) account is required to use the Studio UI. The local API server itself runs without one.
+
+---
+
+## Development
+
+All development commands use the main `.venv` (Python 3.14):
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+# Prefer explicit venv invocation to avoid interpreter mismatch:
+.venv/bin/pip install -e ".[dev]"
+
+# Run tests
+.venv/bin/python -m pytest -q
+
+# Lint
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+
+# Type check
+.venv/bin/python -m mypy --strict src/
+
+# All quality gates in one pass
+.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/python -m mypy --strict src/ && .venv/bin/python -m pytest -q
+```
+
+### Python version note
+
+The project targets Python 3.11+ and is developed against 3.14. The `.venv-studio` venv (Python 3.13) is **only** for running `langgraph dev`. Do not use it for tests or type checking — results may differ.
+
+---
+
+## Troubleshooting
+
+**`ModuleNotFoundError: No module named 'arcwright_ai'`**
+
+The venv's editable install link may be stale or was not processed correctly on Python 3.14. Re-install:
+
+```bash
+cd arcwright-ai/
+.venv/bin/pip install -e .
+```
+
+This rewrites the `.pth` file. Verify with:
+
+```bash
+.venv/bin/python -c "import arcwright_ai; print(arcwright_ai.__file__)"
+```
+
+**`langgraph dev` fails with `Required package 'langgraph-api' is not installed`**
+
+You're using the main `.venv` (Python 3.14). Use `.venv-studio` instead:
+
+```bash
+.venv-studio/bin/langgraph dev
+```
+
+**Story dispatched but files don't match what validation expected**
+
+Check `.arcwright-ai/config.yaml` in the target project. The `methodology.artifacts_path` must point to the directory containing your BMAD planning artifacts (PRD, architecture, epics). Default is `_bmad-output`; adjust if your project uses `_spec/planning-artifacts` or another path.
+
+**Dev agent File List is consistently incomplete or doesn't match `git diff` output after a BMAD update**
+
+The dev-story workflow in this project includes a custom git diff audit step (Step 9 of `instructions.xml`) that was added to address a systemic issue where 67% of stories had File List discrepancies. This customization lives in `_bmad/bmm/workflows/4-implementation/dev-story/` — a directory that is gitignored and gets overwritten by BMAD framework updates.
+
+If you have recently run a BMAD update and agent File Lists are again going unaudited, the customization was likely overwritten. See the **BMAD Workflow Customizations** section in the root [`README.md`](../README.md#bmad-workflow-customizations) for the exact changes to re-apply.