refactor: split frontmatter parsing + VerifyOutcome out of verify.py (#242)

[pbean]

Closes #242 (assessment finding F-1).

Problem

Pure domain modules imported backward into verify.py — a 1,791-line git/subprocess module:

• stories.py → from .verify import read_frontmatter, status_of
• escalation.py → from .verify import VerifyOutcome

That drags the whole git/subprocess surface into modules that have no git needs, and leaves the pure frontmatter parsing impossible to unit-test or type-check in isolation.

Change (behavior-preserving move only — no logic edits)

1. New src/bmad_loop/frontmatter.py holding read_frontmatter, status_of, and set_frontmatter_status — pure file/markdown parsing, stdlib + PyYAML only, zero git imports. (The three functions are moved verbatim.)
2. VerifyOutcome (frozen dataclass, no git deps) moves to model.py.
3. verify.py re-exports all moved names so every existing verify.<name> and from .verify import <name> call site (devcontract, engine, runs, sweep, tests) and monkeypatch target stays valid. The re-export-only set_frontmatter_status carries an explicit # noqa: F401 (ruff's F401 autofix would otherwise silently delete it); read_frontmatter/status_of/VerifyOutcome are also used internally by verify so they need none. import yaml is dropped from verify (its only use moved out).
4. stories.py and escalation.py now import from the new homes (.frontmatter / .model).

set_frontmatter_field intentionally stays in verify.py — it is out of scope for F-1 (no pure-module imports it) and its move is not requested.

Verification

• Full suite: 2716 passed, 1 skipped. The only 2 failures (test_module_skills_sync.py — bmad-loop-setup/assets/module.yaml) are pre-existing local-install drift in .agents/skills/.claude/skills (files not even tracked on main); this branch touches no skill files.
• trunk check --no-fix on all changed files: no issues (confirms F401 does not flag the re-exports).

No CHANGELOG entry — not user-visible.

Summary by CodeRabbit

• New Features

  • Added improved handling for reading, normalizing, and updating specification status information.
  • Added support for updating individual specification metadata fields while preserving existing formatting and comments.
  • Verification results now clearly distinguish successful checks, retryable issues, and escalation conditions.

• Refactor

  • Consolidated specification metadata and verification result handling for more consistent behavior across the workflow.

---

Update — review follow-up (commit d455277)

Beyond the verbatim move, this PR now also hardens a pre-existing delimiter bug the automated reviewer flagged: text.split("---", 2) treated a --- substring inside a scalar value (e.g. title: 'restore --- review') as the closing frontmatter delimiter — so read_frontmatter returned {} (silently zeroing status) and set_frontmatter_field's insert path could corrupt the spec. That logic was pre-existing (moved verbatim from verify.py), but rather than defer it, the fix adds a shared _split_frontmatter boundary finder in frontmatter.py that recognizes --- only as a standalone delimiter line (reconstructing the file byte-for-byte), used by all three sites, plus regression tests for the read + both writer paths. This second commit is deliberately separate so the pure move stays reviewable on its own. Full suite: 2719 passed (the same 2 unrelated test_module_skills_sync.py local-install failures).

[coderabbitai]

Walkthrough

Frontmatter parsing and status mutation move into frontmatter.py, while VerifyOutcome moves into model.py. verify.py imports these symbols, adds set_frontmatter_field, and consumers update their import paths.

Changes

Frontmatter and verification refactor

Layer / File(s)	Summary
Frontmatter parsing and status rewriting src/bmad_loop/frontmatter.py	Adds pure YAML frontmatter reading, normalized status extraction, and idempotent in-place status updates.
Verification outcome and field-update wiring src/bmad_loop/model.py, src/bmad_loop/verify.py	Defines the frozen VerifyOutcome dataclass, removes its local definition, reuses extracted frontmatter helpers, and adds generic scalar frontmatter field updates.
Consumer import updates src/bmad_loop/escalation.py, src/bmad_loop/stories.py	Updates consumers to import VerifyOutcome, read_frontmatter, and status_of from their dedicated modules.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• bmad-code-org/bmad-loop#65: Builds stories-mode verification on the frontmatter and VerifyOutcome APIs changed here.
• bmad-code-org/bmad-loop#77: Uses the same frontmatter and verification outcome surfaces in verify.py.
• bmad-code-org/bmad-loop#86: Touches the related set_frontmatter_field functionality.

Poem

A rabbit hops through YAML lines,
While outcomes bloom in model pines.
Verify sheds its borrowed load,
Stories find a cleaner road.
Status flips, then rests just right—
Refactored burrow, tidy and bright!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes match #242: frontmatter helpers moved to frontmatter.py, VerifyOutcome to model.py, and callers updated.
Out of Scope Changes check	✅ Passed	All listed edits support the refactor; no unrelated code changes are evident from the summary.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main refactor: moving frontmatter parsing and VerifyOutcome out of verify.py.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/frontmatter-verifyoutcome-split

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/bmad_loop/frontmatter.py`:
- Around line 31-40: Replace delimiter-based split logic with one shared
boundary finder that recognizes opening and closing `---` only when they occupy
standalone lines. In `src/bmad_loop/frontmatter.py` lines 31-40, use it before
YAML parsing; reuse the same helper in `src/bmad_loop/frontmatter.py` lines
68-86 for status rewriting and in `src/bmad_loop/verify.py` lines 923-941 for
updating or appending fields, preserving scalar values containing `---` and
avoiding duplicated boundary logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bdeb7553-9a96-4305-a546-70b28658a021

📥 Commits

Reviewing files that changed from the base of the PR and between 9f8adc2 and b1eb5de.

📒 Files selected for processing (5)

• src/bmad_loop/escalation.py
• src/bmad_loop/frontmatter.py
• src/bmad_loop/model.py
• src/bmad_loop/stories.py
• src/bmad_loop/verify.py