feat: add JSON settings runtime policy flow

docs/changelog/260413.md

@@ -1,5 +1,131 @@
 # Changelog - 260413
 
+## 260413-09:14:32 - Restore verify-step retry contract
+
+### Summary
+Restored the shared verifier CLI contract so create-step retries can inspect JSON failures without aborting, and aligned the shipped create examples with the pinned verifier path.
+
+### Fixed
+- Fixed `orchestrator-helper verify-step` to return JSON with exit code `0` for ordinary verification failures, preserving retry loops that branch on `.verified` instead of shell exit status.
+- Fixed the create monitoring quick reference and retry wrapper examples to keep `--state-file` attached through build and monitor handoff.
+
+### Changed
+- Changed smoke coverage and unit tests to pin the create verifier failure contract and the updated state-file command forms.
+
+### Files
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/tests/test_success_verifiers.py`
+- `payload/.claude/skills/bmad-story-automator/data/monitoring-pattern.md`
+- `payload/.claude/skills/bmad-story-automator/data/retry-fallback-implementation.md`
+- `scripts/smoke-test.sh`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- `PYTHONPATH=source/src python3 -m unittest source.tests.test_success_verifiers`
+- `bash scripts/smoke-test.sh`
+
+## 260413-08:05:51 - Wire policy-backed success verifiers
+
+### Summary
+Moved review completion checks onto the JSON policy contract and routed monitor verification through the named verifier registry.
+
+### Added
+- Added a shared success verifier registry covering session exit, story artifact creation, review completion, and epic completion.
+- Added unit coverage for contract-driven review verification, create artifact matching, epic completion, pinned snapshot reuse, and monitor dispatch.
+
+### Changed
+- Changed `monitor-session` to resolve the active step's `success.verifier` from policy, accept `--state-file`, and verify completion through the configured verifier instead of a hard-coded review branch.
+- Changed `verify-code-review` to resolve review completion from the pinned state snapshot when provided, so review verification stays aligned with the active runtime policy.
+
+### Files
+- `source/src/story_automator/core/success_verifiers.py`
+- `source/src/story_automator/core/review_verify.py`
+- `source/src/story_automator/commands/tmux.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/tests/test_success_verifiers.py`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A
+
+## 260413-09:26:29 - Tighten state policy compatibility helpers
+
+### Summary
+Closed the remaining state-policy fallback hole and routed the legacy create validator through the shared verifier.
+
+### Changed
+- Changed `validate-story-creation check` into a compatibility wrapper around the policy-backed create success verifier and updated the CLI docs to point new callers at `orchestrator-helper verify-step create`.
+- Changed regression coverage to pin the legacy create wrapper against the shared verifier and pinned state snapshots.
+
+### Fixed
+- Fixed new-format state docs with policy-era metadata but missing snapshot metadata to fail instead of slipping into legacy defaults.
+- Fixed `state-summary` to avoid inferring `legacyPolicy: true` for malformed new-format state docs.
+
+### Files
+- `source/src/story_automator/commands/validate_story_creation.py`
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/tests/test_success_verifiers.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_state_policy_metadata.py`
+- `docs/cli-reference.md`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A
+
+## 260413-08:39:42 - Route create validation through shared verifier
+
+### Summary
+Removed the duplicate create-story file counting path and exposed the shared verifier registry as the public success-check interface.
+
+### Added
+- Added `orchestrator-helper verify-step` so workflow steps can run the configured success verifier directly, with optional pinned `--state-file` and `--output-file` inputs.
+
+### Changed
+- Changed the shipped create workflow, retry guidance, monitoring pattern, and CLI docs to use `verify-step create ... --state-file "$state_file"` instead of `validate-story-creation check`.
+- Changed docs and smoke coverage to pin the new create verifier command forms and their state-file handoff.
+- Changed regression tests to cover `verify-step create` and pinned create-policy snapshot reuse.
+
+### Files
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/tests/test_success_verifiers.py`
+- `payload/.claude/skills/bmad-story-automator/steps-c/step-03-execute.md`
+- `payload/.claude/skills/bmad-story-automator/data/retry-fallback-implementation.md`
+- `payload/.claude/skills/bmad-story-automator/data/monitoring-pattern.md`
+- `payload/.claude/skills/bmad-story-automator/data/scripts-reference.md`
+- `docs/cli-reference.md`
+- `scripts/smoke-test.sh`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- `npm run verify`
+
+## 260413-08:34:25 - Harden success verifier review fixes
+
+### Summary
+Closed the review-loop findings around contract-safe verifier loading, snapshot handoff coverage, and verifier config failure modes.
+
+### Fixed
+- Fixed review verification to load only step-local success contract paths so unrelated missing skill assets no longer turn completed reviews into `review_contract_invalid`.
+- Fixed review contract validation to reject empty or whitespace-only completion arrays and fixed verifier numeric parsing to reject malformed or boolean `expectedMatches`.
+- Fixed retrospective completion checks to accept the real bare epic identifier used by the retro step.
+
+### Changed
+- Changed the shipped code-review loop to pass `--state-file` through create/build, monitor, parse, and verify commands so pinned policy snapshots stay consistent end to end.
+- Changed smoke coverage and unit tests to pin each state-file handoff and the new verifier hardening paths.
+
+### Files
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/core/success_verifiers.py`
+- `source/tests/test_success_verifiers.py`
+- `payload/.claude/skills/bmad-story-automator/data/code-review-loop.md`
+- `scripts/smoke-test.sh`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- `npm run verify`
+
 ## 260413-11:35:00 - Verify packed npx install path
 
 ### Summary
@@ -65,3 +191,160 @@ Reworked the package docs into a multi-file operator guide covering flow, runtim
 
 ### QA Notes
 - N/A
+
+## 260413-06:34:01 - Add JSON settings implementation plan
+
+### Summary
+Added a structured planning packet for moving story-automator contracts to snapshot-backed JSON settings.
+
+### Added
+- Added a dedicated plan set covering goals, architecture, code and payload touchpoints, migration strategy, testing strategy, and risk controls for the JSON settings refactor.
+- Added a sequential implementation TODO with dependencies, phase boundaries, and done criteria for executing the refactor in bounded slices.
+
+### Files
+- `docs/plans/json-settings/README.md`
+- `docs/plans/json-settings/01-why-json-settings.md`
+- `docs/plans/json-settings/02-policy-model.md`
+- `docs/plans/json-settings/03-code-and-payload-changes.md`
+- `docs/plans/json-settings/04-migration-testing-and-risks.md`
+- `docs/plans/json-settings/TODO.md`
+
+### QA Notes
+- N/A
+
+## 260413-07:29:16 - Add JSON runtime policy foundation
+
+### Summary
+Implemented the first JSON-settings slice with bundled policy data, snapshot-backed state metadata, and policy-driven prompt/parse wiring.
+
+### Added
+- Added a runtime policy loader with deterministic merge, asset resolution, environment compatibility, and snapshot writing.
+- Added bundled orchestration policy, prompt templates, parse contracts, and a structured review contract file.
+- Added Python unit coverage for policy loading, parser contracts, and state snapshot metadata.
+
+### Changed
+- Changed `tmux-wrapper build-cmd` to render prompts from policy-backed templates instead of inline string maps.
+- Changed parser contract loading, retry budget reads, smoke coverage, and `npm run verify` to use the new JSON-policy foundation.
+- Changed orchestration state documents to persist `policyVersion`, `policySnapshotFile`, and `policySnapshotHash`.
+
+### Files
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/core/workflow_paths.py`
+- `source/src/story_automator/commands/tmux.py`
+- `source/src/story_automator/commands/orchestrator_parse.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/src/story_automator/commands/state.py`
+- `payload/.claude/skills/bmad-story-automator/data/orchestration-policy.json`
+- `payload/.claude/skills/bmad-story-automator/data/prompts/`
+- `payload/.claude/skills/bmad-story-automator/data/parse/`
+- `payload/.claude/skills/bmad-story-automator-review/contract.json`
+- `scripts/smoke-test.sh`
+- `package.json`
+- `docs/development.md`
+- `docs/changelog/260413.md`
+- `source/tests/`
+
+### QA Notes
+- N/A
+
+## 260413-07:55:28 - Harden runtime policy snapshot handling
+
+### Summary
+Fixed the follow-up review findings around snapshot consumption, policy validation, and stale marker fallback behavior.
+
+### Fixed
+- Fixed runtime policy consumers to honor pinned state snapshots for prompt building, parser contract loading, and escalation budgets when a state file is available.
+- Fixed malformed override JSON and invalid nested policy shapes to fail through controlled validation paths instead of crashing later with raw exceptions.
+- Fixed implicit marker/env state lookup to fall back safely when the referenced state file is missing or the marker payload is malformed.
+- Fixed `tmux-wrapper build-cmd` to strip `--state-file` from prompt text instead of leaking the flag into child instructions.
+
+### Changed
+- Added regression tests covering snapshot reuse after override changes, invalid nested workflow shapes, malformed marker files, and state-aware prompt/build behavior.
+
+### Files
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/commands/tmux.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/src/story_automator/commands/orchestrator_parse.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_orchestrator_parse.py`
+- `source/tests/test_state_policy_metadata.py`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A
+
+## 260413-09:13:20 - Enforce snapshot-only resume semantics
+
+### Summary
+Locked resume behavior to pinned snapshots for new state docs while keeping legacy states on bundled defaults only.
+
+### Fixed
+- Fixed legacy state resumes to ignore live project overrides and legacy env knobs so old runs stay on bundled defaults.
+- Fixed marker and env discovered new-format states to fail validation when the pinned snapshot file is missing instead of silently falling back to live policy.
+
+### Changed
+- Changed `state-summary` to infer `legacyPolicy: true` for old state docs without snapshot metadata.
+- Changed tests and operator docs to pin snapshot-only resume rules and the one-release env compatibility window for `MAX_REVIEW_CYCLES` and `MAX_CRASH_RETRIES`.
+
+### Files
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_state_policy_metadata.py`
+- `docs/state-and-resume.md`
+- `docs/development.md`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A
+
+## 260413-11:00:47 - Harden parser runtime and validator compatibility
+
+### Summary
+Hardened the policy-backed parser/runtime wiring and closed the remaining legacy validator compatibility gaps.
+
+### Changed
+- Changed parser dispatch to read provider, model, and timeout settings from `runtime.parser` policy data instead of hard-coded CLI defaults.
+- Changed `tmux-wrapper build-cmd` to reject unknown steps through policy contract lookup instead of a local step allowlist.
+
+### Fixed
+- Fixed `validate-story-creation` compatibility mode to preserve `before`/`after` delta semantics, forward trailing flags like `--state-file`, preserve zero-expected contracts, and return one JSON envelope across malformed flag, positional, and policy-error paths.
+- Fixed policy-state classification so contradictory `policyVersion` and `legacyPolicy: true` metadata fails closed and `state-summary` reports the same boundary as the runtime loader.
+
+### Files
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/src/story_automator/commands/orchestrator_parse.py`
+- `source/src/story_automator/commands/tmux.py`
+- `source/src/story_automator/commands/validate_story_creation.py`
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/tests/test_orchestrator_parse.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_state_policy_metadata.py`
+- `source/tests/test_success_verifiers.py`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A
+
+## 260413-21:53:12 - Close state-summary and validator compatibility gaps
+
+### Summary
+Fixed remaining review-loop gaps in policy snapshot reporting and legacy create-validator error payloads.
+
+### Changed
+- Changed `state-summary` to validate snapshot metadata against the runtime project root and surface `policyError` when state policy metadata is contradictory, incomplete, missing, or hash-mismatched.
+- Changed `validate-story-creation check` and the positional compatibility shim to preserve parsed delta metadata across malformed trailing argument paths and reject all `--artifacts-dir` overrides consistently.
+- Changed regression coverage to pin the new state-summary error reporting and compatibility-payload branches found during the clean review loop.
+
+### Files
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/src/story_automator/commands/validate_story_creation.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_state_policy_metadata.py`
+- `source/tests/test_success_verifiers.py`
+- `docs/changelog/260413.md`
+
+### QA Notes
+- N/A

docs/changelog/260414.md

@@ -0,0 +1,40 @@
+# Changelog - 260414
+
+## 260414-21:51:35 - Harden snapshot and verifier review fixes
+
+### Summary
+Closed the latest CodeRabbit review pass by aligning docs/examples with shipped behavior and hardening snapshot, parser, and verifier paths.
+
+### Changed
+- Changed the development and JSON-settings docs to match the shipped verify order, supported workflow keys, and full state-policy metadata contract.
+- Changed the execute-step example and smoke coverage so dev `build-cmd` keeps the pinned `--state-file` handoff.
+- Changed regression coverage to pin the new parser, snapshot, verifier, and compatibility-wrapper failure contracts.
+
+### Fixed
+- Fixed `tmux-wrapper build-cmd` prompt escaping to quote shell input safely for both Claude and Codex child sessions.
+- Fixed `parse-output` and `verify-step` flag parsing to reject incomplete `--state-file` and `--output-file` arguments instead of silently falling back.
+- Fixed state-doc creation, review verification, and legacy create validation to normalize missing snapshot/contract failures into structured JSON responses.
+- Fixed monitor verification to surface `story_key_required` when a story-bound verifier is invoked without a story key.
+- Fixed runtime policy snapshot loading to hash prompt/schema/contract files and reject snapshot or asset paths that escape allowed roots.
+
+### Files
+- `docs/development.md`
+- `docs/plans/json-settings/02-policy-model.md`
+- `docs/plans/json-settings/README.md`
+- `payload/.claude/skills/bmad-story-automator/steps-c/step-03-execute.md`
+- `scripts/smoke-test.sh`
+- `source/src/story_automator/commands/orchestrator.py`
+- `source/src/story_automator/commands/orchestrator_parse.py`
+- `source/src/story_automator/commands/state.py`
+- `source/src/story_automator/commands/tmux.py`
+- `source/src/story_automator/commands/validate_story_creation.py`
+- `source/src/story_automator/core/review_verify.py`
+- `source/src/story_automator/core/runtime_policy.py`
+- `source/tests/test_orchestrator_parse.py`
+- `source/tests/test_runtime_policy.py`
+- `source/tests/test_state_policy_metadata.py`
+- `source/tests/test_success_verifiers.py`
+- `docs/changelog/260414.md`
+
+### QA Notes
+- N/A