codeharness 0.19.2 → 0.19.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.19.2",
+  "version": "0.19.4",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {

package/patches/AGENTS.md

@@ -0,0 +1,42 @@
+# patches/ — BMAD Workflow Enforcement Patches
+
+## Purpose
+
+Markdown patch files applied to BMAD workflow targets during `codeharness init`.
+Each patch encodes operational learnings (FR33) as enforcement rules that
+prevent recurrence of observed failures.
+
+## Directory Structure (FR35)
+
+```
+patches/
+  dev/enforcement.md        — Dev agent guardrails
+  review/enforcement.md     — Review gates (proof quality, coverage)
+  verify/story-verification.md — Black-box proof requirements
+  sprint/planning.md        — Sprint planning pre-checks
+  retro/enforcement.md      — Retrospective quality metrics
+```
+
+Subdirectories map to BMAD workflow roles.
+
+## How Patches Work
+
+1. `src/templates/bmad-patches.ts` reads files via `readPatchFile(role, name)`
+2. `src/lib/bmad.ts` maps patch names to BMAD workflow target files via `PATCH_TARGETS`
+3. `src/lib/patch-engine.ts` injects patch content between `CODEHARNESS-PATCH-START/END` markers
+4. `src/commands/teardown.ts` removes patches on teardown
+
+## Editing Patches
+
+- Edit `.md` files directly — no TypeScript rebuild required (runtime `readFileSync`)
+- Each patch MUST have a `## WHY` section explaining the operational failure it prevents (FR36)
+- Do NOT change filenames without updating `readPatchFile()` calls in `bmad-patches.ts`
+- Do NOT remove inline fallback strings in `bmad-patches.ts` — they cover npm installs without `patches/`
+
+## Adding a New Patch
+
+1. Create `patches/{role}/{name}.md` with `## WHY` section
+2. Add a template function in `src/templates/bmad-patches.ts` calling `readPatchFile(role, name)`
+3. Add entry to `PATCH_TEMPLATES` in `bmad-patches.ts`
+4. Add target mapping in `PATCH_TARGETS` in `src/lib/bmad.ts`
+5. Add tests in `src/templates/__tests__/bmad-patches.test.ts`

package/patches/{dev-enforcement.md → dev/enforcement.md}

@@ -1,3 +1,12 @@
+## WHY
+
+Dev agents repeatedly shipped code without reading module conventions (AGENTS.md),
+skipped observability checks, and produced features that could not be verified
+from outside the source tree. This patch enforces architecture awareness,
+observability validation, documentation hygiene, test coverage gates, and
+black-box thinking — all operational failures observed in prior sprints.
+(FR33, FR34, NFR20)
+
 ## Codeharness Development Enforcement
 
 ### Architecture Awareness

package/patches/{retro-enforcement.md → retro/enforcement.md}

@@ -1,3 +1,12 @@
+## WHY
+
+Retrospectives produced vague observations without actionable items, and
+verification pipeline issues (hangs, false positives, verify-dev loops) were
+not systematically tracked. This patch structures retro analysis around
+verification effectiveness, pipeline health, documentation accuracy, test
+quality trends, and mandatory concrete action items with owners.
+(FR33, FR36, NFR20)
+
 ## Codeharness Retrospective Quality Metrics
 
 ### Verification Effectiveness

package/patches/{review-enforcement.md → review/enforcement.md}

@@ -1,3 +1,12 @@
+## WHY
+
+Review agents approved stories without verifying proof documents existed or
+checking that evidence was black-box (not source-grep). Stories passed review
+with fabricated output and missing coverage data. This patch enforces proof
+existence, black-box evidence quality, and coverage delta reporting as hard
+gates before a story can leave review.
+(FR33, FR34, NFR20)
+
 ## Codeharness Review Gates
 
 ### Verification Proof

package/patches/{sprint-planning.md → sprint/planning.md}

@@ -1,3 +1,12 @@
+## WHY
+
+Sprint planning repeatedly started new work while retrospective action items
+were unresolved, leading to compounding tech debt. Stories entered sprints
+with untestable ACs or missing backlog sources, causing mid-sprint scope
+discovery. This patch enforces pre-planning retro review, multi-source backlog
+import, and story readiness checks.
+(FR33, FR34, NFR20)
+
 ## Codeharness Sprint Planning Integration
 
 ### Pre-Planning Checks

package/patches/{story-verification.md → verify/story-verification.md}

@@ -1,3 +1,12 @@
+## WHY
+
+Stories were marked "done" with no proof artifact, or with proofs that only
+grepped source code instead of exercising the feature from the user's
+perspective. This patch mandates black-box proof documents, docker exec evidence,
+verification tags per AC, and test coverage targets — preventing regressions
+from being hidden behind source-level assertions.
+(FR33, FR36, NFR20)
+
 ## Verification Requirements
 
 Every story must produce a **black-box proof** — evidence that the feature works from the user's perspective, NOT from reading source code.

package/ralph/ralph.sh

@@ -38,7 +38,7 @@ LOG_DIR=""
 # Loop limits
 MAX_ITERATIONS=${MAX_ITERATIONS:-50}
 MAX_STORY_RETRIES=${MAX_STORY_RETRIES:-10}
-LOOP_TIMEOUT_SECONDS=${LOOP_TIMEOUT_SECONDS:-14400}  # 4 hours default
+LOOP_TIMEOUT_SECONDS=${LOOP_TIMEOUT_SECONDS:-43200}  # 12 hours default
 ITERATION_TIMEOUT_MINUTES=${ITERATION_TIMEOUT_MINUTES:-30}
 
 # Rate limiting