[KHAEntertainment]

Closes #150

Rationale

Remediation loops had no bound. Fix batches are now counted on a durable defect_episodes[] entry in the lead ledger; each PR points to it with defect_episode_ref, so the count survives new heads, worker swaps, handoffs and related PRs. Batches 1 and 2 are automatic; before batch 3 the lead writes a diagnosis entry that authorizes only a named additional batch count. A cap never clears a blocker or escalates by itself. Only material findings (P4 definition) drive a batch; advisory findings go to the debt log. Prose + template + pins only; dev_state.py is unchanged (it already accepts new keys) and "dispatch refused by the SOP" is a pinned rule for the lead, not enforcement code.

Changes (all additive under schema_version: 2):

• DEV_STATE_TEMPLATE.md: defect_episodes: [], defect_episode_ref in the PR field list, new "Defect episode record schema (Issue [v2.1.3 P5] Bounded remediation: defect-episode fix_batches and lead diagnosis before batch 3 #150)" section with a worked example
• phases/phase4.md: new "Bounded remediation" section, referenced from the fix-batch paragraph and the REQUEST CHANGES rating
• phases/phase3.5.md: QA-fails gate step (only that section)
• scripts/validate_skill.py: BOUNDED_REMEDIATION_PINS + check_bounded_remediation (self-contained)
• tests/test_backend_contract.py: BoundedRemediationTests (self-contained class)

Acceptance criteria

• AC-1 batch 3 without a diagnosis entry → dispatch refused by the SOP: ✓ pinned in phase4.md and phase3.5.md (validator + test, removal fails the validator)
• AC-2 cap reached with a blocker open → blocker stays open, no escalation by itself: ✓ pinned
• AC-3 counter carries across heads and worker swaps: ✓ lives on the episode; PR refs checked in the example test
• AC-4 related PR continues the episode count: ✓ example has PR 150 and 153 sharing ep-1; rule pinned
• AC-5 diagnosis authorizes only the named bound: ✓ limit = bound + sum(authorized_additional_batches); example uses exactly its limit; counterexamples (overrun, no diagnosis) exceed it
• AC-6 example parses with dev_state.py --validate; old ledgers stay valid: ✓ tests run the repo's dev_state.py on the example, on the template without the new key, on a PR entry without defect_episode_ref; flow syntax on the new key is still rejected

Focused checks (head 6ffa0b1; CI Verification Gate owns the full suite)

python3 scripts/validate_skill.py            -> OK: validated .../skills/dev            (exit 0)
python3 -m unittest tests.test_backend_contract -> Ran 119 tests ... OK               (exit 0)
python3 -m unittest tests.test_dev_state        -> Ran 17 tests ... OK                (exit 0)
python3 -m py_compile scripts/validate_skill.py tests/test_backend_contract.py        (exit 0)

scripts/verify.sh, the full suite and installer suites were not run (CI-owned).

Coverage-path audit

• Fix-batch entry paths: phase4 REQUEST CHANGES, phase4 consolidation paragraph, phase3.5 QA-fails, each points to the one Bounded remediation section: static (pinned) + executed validator/test.
• Ledger shapes: old ledger, template without key, new example, flow-syntax counterexample: executed.
• Not covered: the lead actually following the rule at runtime (prose SOP; no runtime code by design).
• graph_evidence: unavailable (repo not graft-indexed); dependents traced with rg/grep for "Review after fixes" and "fix batch".

Caller impact

Additive only. dev_state.py unchanged; existing pins and the P1/P4 text untouched. Merge note: P2 (#149) also edits phase3.5.md (trigger section), validate_skill.py and tests/test_backend_contract.py; my edits are self-contained blocks (new constants/function above main, new test class at end of file).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: f41ec4cc-e34f-471f-974e-df8d6bf52a90

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (5 files)

• scripts/validate_skill.py - adds BOUNDED_REMEDIATION_PINS + check_bounded_remediation; all pinned tokens verified present in target prose
• skills/dev/phases/phase3.5.md - QA fails section renumbers to insert the bounded-remediation batch-count step; consistent with phase4.md
• skills/dev/phases/phase4.md - new "Bounded remediation" section; no contradiction with phase3.5.md
• skills/dev/templates/DEV_STATE_TEMPLATE.md - adds top-level defect_episodes: [] and defect_episode_ref to pull_requests schema; worked example self-consistent
• tests/test_backend_contract.py - BoundedRemediationTests; covers both validator-pass (clean fixture) and validator-fail (5 pin-removal mutations) cases

No CRITICAL/WARNING/SUGGESTION findings in changed code. All changed-code issues reviewed in a single pass; no pre-existing unchanged-line issues reported.

---

_{Reviewed by nemotron-3.5-super-vl:free · Input: 110.9K · Output: 18.2K · Cached: 325.2K}

_{Review guidance: REVIEW.md from base branch main}