codeharness 0.17.6 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.17.6",
+  "version": "0.18.0",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "bin",
+    "patches",
     "templates/Dockerfile.verify",
     "ralph/**/*.sh",
     "ralph/AGENTS.md"

package/patches/dev-enforcement.md

@@ -0,0 +1,34 @@
+## Codeharness Development Enforcement
+
+### Architecture Awareness
+
+Before writing code, read the relevant `AGENTS.md` file for the module being changed. Understand:
+- Build commands and test runners
+- Module boundaries and conventions
+- What NOT to do (common pitfalls documented from prior incidents)
+
+### Observability
+
+After running tests, verify telemetry is flowing:
+- Query VictoriaLogs to confirm log events from test runs
+- If observability is configured, traces should be visible for CLI operations
+
+### Documentation
+
+- Update `AGENTS.md` for all changed modules
+- Keep exec-plan current with implementation state
+
+### Testing
+
+- All tests pass before moving to review
+- Coverage gate: 100% of new/changed code
+- Run `npm test` / `pytest` and verify no regressions
+
+### Black-Box Thinking
+
+Write code that can be verified from the outside. Ask yourself:
+- Can a user exercise this feature from the CLI alone?
+- Is the behavior documented in README.md?
+- Would a verifier with NO source access be able to tell if this works?
+
+If the answer is "no", the feature has a testability gap — fix the CLI/docs, not the verification process.

package/patches/retro-enforcement.md

@@ -0,0 +1,34 @@
+## Codeharness Retrospective Quality Metrics
+
+### Verification Effectiveness
+
+- How many ACs were caught by black-box verification vs slipped through?
+- Were there false positives (proof said PASS but feature was broken)?
+- Were there false negatives (proof said FAIL but feature actually works)?
+- Time spent on verification — is it proportional to value?
+
+### Verification Pipeline Health
+
+- Did the verifier hang on permissions? (check for `--allowedTools` issues)
+- Did stories get stuck in verify→dev loops? (check `attempts` counter)
+- Were stories incorrectly flagged as `integration-required`?
+- Did the verify parser correctly detect `[FAIL]` verdicts?
+
+### Documentation Health
+
+- AGENTS.md accuracy for changed modules
+- Exec-plans completeness for active stories
+- Stale documentation identified and cleaned up
+
+### Test Quality
+
+- Coverage trend (improving, stable, declining)
+- Any flaky tests introduced?
+- Integration test coverage for cross-module interactions
+
+### Action Items
+
+Every retro MUST produce concrete action items with:
+- Clear description of what to fix
+- Why it matters (what fails without this fix)
+- Owner and priority

package/patches/review-enforcement.md

@@ -0,0 +1,23 @@
+## Codeharness Review Gates
+
+### Verification Proof
+
+- Proof document exists at `verification/<story-key>-proof.md`
+- Proof passes `codeharness verify --story <id>` (parser checks for FAIL/ESCALATE verdicts)
+- Every AC has functional evidence — reading docs alone is not evidence
+- No fabricated output — all evidence must be from actual command execution
+
+### Proof Quality Checks
+
+The proof must pass black-box enforcement:
+- Commands run via `docker exec` (not direct host access)
+- Less than 50% of evidence commands are `grep` against `src/`
+- Each AC section has at least one `docker exec`, `docker ps/logs`, or observability query
+- `[FAIL]` verdicts outside code blocks cause the proof to fail
+- `[ESCALATE]` is acceptable only when all automated approaches are exhausted
+
+### Code Quality
+
+- Coverage delta reported (before vs after)
+- No coverage regression in changed files
+- AGENTS.md is current for all changed modules

package/patches/sprint-planning.md

@@ -0,0 +1,21 @@
+## Codeharness Sprint Planning Integration
+
+### Pre-Planning Checks
+
+Before selecting stories, verify:
+1. All prior retrospective action items are reviewed (`_bmad-output/implementation-artifacts/session-retro-*.md`)
+2. Unresolved action items are surfaced — do not start new work while critical fixes are pending
+3. `ralph/.story_retries` is reviewed — stories with high attempt counts may need architectural changes, not more retries
+
+### Backlog Sources
+
+Import from all sources before triage:
+- `codeharness retro-import --epic N` for retrospective findings
+- `codeharness github-import` for labeled GitHub issues
+- `bd ready` to display combined backlog
+
+### Story Readiness
+
+- Each story has clear, testable acceptance criteria
+- ACs are written so they CAN be verified from CLI + Docker (avoid writing untestable ACs)
+- Dependencies between stories are explicit

package/patches/story-verification.md

@@ -0,0 +1,25 @@
+## 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.
+
+### Proof Standard
+
+- Proof document at `verification/<story-key>-proof.md`
+- Each AC gets a `## AC N:` section with `docker exec` commands and captured output
+- Evidence must come from running the installed CLI/tool, not from grepping source
+- `[FAIL]` = AC failed with evidence showing what went wrong
+- `[ESCALATE]` = AC genuinely cannot be automated (last resort — try everything first)
+
+### Verification Tags
+
+For each AC, append a tag indicating verification approach:
+- `<!-- verification: cli-verifiable -->` — default. Can be verified via CLI commands in a Docker container.
+- `<!-- verification: integration-required -->` — requires external systems not available in the test environment (e.g., paid third-party APIs, physical hardware). This is rare — most things including workflows, agent sessions, and multi-step processes CAN be verified in Docker.
+
+**Do not over-tag.** Workflows, sprint planning, user sessions, slash commands, and agent behavior are all verifiable via `docker exec ... claude --print`. Only tag `integration-required` when there is genuinely no automated path.
+
+### Testing Requirements
+
+- Unit tests for all new/changed code
+- Coverage target: 100% of new/changed lines
+- No skipped tests without justification