Skip to content

docs(debug-playbook-engine): make canMakeClaim example actually run#71

Merged
LanNguyenSi merged 2 commits into
masterfrom
docs/fix-broken-readme-examples-2026-05-11
May 11, 2026
Merged

docs(debug-playbook-engine): make canMakeClaim example actually run#71
LanNguyenSi merged 2 commits into
masterfrom
docs/fix-broken-readme-examples-2026-05-11

Conversation

@LanNguyenSi
Copy link
Copy Markdown
Owner

Refs agent-tasks b1d8a15c-d683-49c8-b0f4-534c54b84c32.

Why

The README API snippet at packages/debug-playbook-engine/README.md:65-75 looked like a happy-path tutorial for canMakeClaim, but the call it makes (canMakeClaim(state, 'root-cause') after recording check-repo-model + check-agent-process) is unsatisfiable: root-cause requires read-docs + check-process, neither of which exist in the clawd-monitor playbook. A reader who copy-pasted the snippet got { allowed: false } and the opposite of the lesson the prose was teaching.

What changed

packages/debug-playbook-engine/README.md only. The new example demonstrates both states of the gate, end-to-end:

  1. After check-repo-model + check-agent-process, canMakeClaim(state, 'config') correctly blocks with reason: ['Required step not completed: check-config'].
  2. After walking through check-start-mode (mandatory order enforced by recordStep) and then check-config, canMakeClaim(state, 'config') returns { allowed: true }.

Also added a closing paragraph naming the unsatisfiability of root-cause and architecture under non-generic playbooks. That is a real defect in canMakeClaim's requirements table (its step IDs are scoped to the generic playbook even though it accepts state from any playbook), but it is out of scope for a README PR. Worth filing as a follow-up if you want it addressed.

Out of scope

  • The sibling finding from the audit (grounding-wrapper README importing handleScopeChange) turned out to be a false positive: lib.ts:236 exports handleScopeChange, and package.json main resolves to dist/lib.js, so the snippet on master already works. No grounding-wrapper change in this PR.
  • Six .version("1.0.0") lies across sibling packages: covered by separate sweep task 163a2845.

Verification

Ran the new example verbatim against dist/lib.js:

blocked: {"allowed":false,"reason":["Required step not completed: check-config"]}
allowed: {"allowed":true}
  • npm test (debug-playbook-engine): 21 / 21 jest green.
  • npm run typecheck (debug-playbook-engine): clean.
  • slop-detector clean on commit message.

Test plan

  • Review subagent confirms the new snippet runs as documented against current lib.ts.
  • Reviewer agrees that the closing "unsatisfiability" paragraph is the right place to mention the root-cause / architecture mismatch (vs. filing a code follow-up as the primary action).
  • CI green.

nguyen-si-pp and others added 2 commits May 11, 2026 09:09
README API snippet recorded check-repo-model + check-agent-process,
then called canMakeClaim(state, 'root-cause'). That call always
returns { allowed: false } because root-cause requires read-docs +
check-process, two step IDs that exist only in the generic playbook,
not in clawd-monitor. A reader copying the snippet got the opposite
of the gating-works narrative the README was teaching.

Replaced with a clawd-monitor-internal example that:

- demonstrates the block path: canMakeClaim('config') after only
  check-repo-model + check-agent-process correctly returns false
  with reason=['Required step not completed: check-config']
- walks the mandatory order through check-start-mode so recordStep
  does not refuse the jump to check-config
- demonstrates the allow path: canMakeClaim('config') after
  check-config is recorded returns { allowed: true }
- adds a closing paragraph naming the root-cause/architecture
  unsatisfiability (cross-playbook step IDs) so the next reader
  is not caught by the same mismatch

Verified by running the example verbatim against dist/lib.js:
blocked = { allowed: false, reason: [...] }
allowed = { allowed: true }
21/21 jest green, tsc --noEmit clean.

The sibling finding for grounding-wrapper (phantom handleScopeChange
import) turned out to be a false positive from the audit: lib.ts:236
exports the symbol and package.json main resolves to dist/lib.js,
so that snippet was correct on master. No change for that package.

Refs agent-tasks b1d8a15c-d683-49c8-b0f4-534c54b84c32.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closing caveat suggested running the `generic` playbook to satisfy
`root-cause` or `architecture`. But `generic` lacks `check-repo-model`,
so it cannot satisfy either claim type either. Reworded the caveat
to name the actual cause (requirements cross playbook boundaries)
and the two real workarounds (extend a playbook, or compose facts
across runs). Review subagent nit on PR #71.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@LanNguyenSi LanNguyenSi added review:tests-pass merge-approval prereq review:checklist-complete merge-approval prereq review:comments-resolved merge-approval prereq review:scope-matches-task merge-approval prereq review:evidence-logged merge-approval prereq labels May 11, 2026
@LanNguyenSi LanNguyenSi merged commit 2fb4c1f into master May 11, 2026
3 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:checklist-complete merge-approval prereq review:comments-resolved merge-approval prereq review:evidence-logged merge-approval prereq review:scope-matches-task merge-approval prereq review:tests-pass merge-approval prereq

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants