docs(debug-playbook-engine): make canMakeClaim example actually run#71
Merged
Merged
Conversation
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>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs agent-tasks
b1d8a15c-d683-49c8-b0f4-534c54b84c32.Why
The README API snippet at
packages/debug-playbook-engine/README.md:65-75looked like a happy-path tutorial forcanMakeClaim, but the call it makes (canMakeClaim(state, 'root-cause')after recordingcheck-repo-model+check-agent-process) is unsatisfiable:root-causerequiresread-docs+check-process, neither of which exist in theclawd-monitorplaybook. 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.mdonly. The new example demonstrates both states of the gate, end-to-end:check-repo-model+check-agent-process,canMakeClaim(state, 'config')correctly blocks withreason: ['Required step not completed: check-config'].check-start-mode(mandatory order enforced byrecordStep) and thencheck-config,canMakeClaim(state, 'config')returns{ allowed: true }.Also added a closing paragraph naming the unsatisfiability of
root-causeandarchitectureunder non-genericplaybooks. That is a real defect incanMakeClaim's requirements table (its step IDs are scoped to thegenericplaybook 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
handleScopeChange) turned out to be a false positive:lib.ts:236exportshandleScopeChange, andpackage.jsonmainresolves todist/lib.js, so the snippet on master already works. No grounding-wrapper change in this PR..version("1.0.0")lies across sibling packages: covered by separate sweep task163a2845.Verification
Ran the new example verbatim against
dist/lib.js:npm test(debug-playbook-engine): 21 / 21 jest green.npm run typecheck(debug-playbook-engine): clean.Test plan
lib.ts.root-cause/architecturemismatch (vs. filing a code follow-up as the primary action).