docs(plan-template): track PLAN_TEMPLATE.md + adopt falsifiable-verify & blast-radius hardening#412
Merged
Conversation
…ble-verify & blast-radius hardening Adds docs/PLAN_TEMPLATE.md as a tracked file and folds in the evolved pi-extensions Appendix B so a lower-capability LLM can execute a plan without silent drift: - §A.6b Falsifiable Verify: parent rule + deny-list (tolerant test $?, self-fulfilling grep, happy-path-only) + positive obligation (name observed + expected value) + compound-bash caveat. - UNGUARDED-IN-CI tag (§4/§7): a MUST/Safety row covered only by a skippable smoke is tagged + names the manual step — no hollow green. - No-aspirational-output (§A.2 item 9, §14): a printed 'checking X' must assert X. - Test-body rigor = code rigor (§A.7): CREATE tests with full verbatim assertions over real captured output, never constants/author-written strings. - One-file-per-step + CREATE/EDIT/APPEND taxonomy + executor-ready gate (§A.2/§A.6/§A.7). - §A.9 Blast-radius patterns: red-then-green negative control, pure-extraction first, thin-wrapper, fixture-change ledger, discriminating sentinel, flag-high-blast-radius, mock-project E2E, non-deterministic-guard. - §20: 6 traceability rows mapping each new rule to its enforcing section. Adapted to this repo (.mjs/bash, real slices P3a/ESC); dropped pi's LLM-app specifics. Preserves our existing governance (RFC grounding, token budget, three-layer review, lessons table). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lantiscooperdev
left a comment
Collaborator
There was a problem hiding this comment.
Bot review — pre-merge coherence pass (not an approval)
Docs-only change; reviewed for internal consistency and non-regression of existing governance.
Verified
- Section ordering intact: §A.6 → §A.6b → §A.7 → §A.8 → §A.9; the 20 numbered sections + Appendix A are all present and ordered (grep over headers).
- Cross-references resolve: §A.6b ↔ §4/§7/§A.9, §A.7 ↔ §A.6/§A.6b/§A.5, and the 6 new §20 rows ↔ their enforcing sections all point at existing headers.
- No governance regression: RFC R-grounding (§4), Rule 12 token budget (§6), symlink matrix (§7), three-layer review (§19), and the lessons table (§20) are untouched — this is additive hardening of Appendix A only.
- Repo-fit: the compound-bash caveat in §A.6b keeps the red-then-green negative-control pattern legal under
compound-bash-gate; examples are re-grounded in.mjs/bash (P3a, ESC) rather than pi's LLM-app specifics.
Note (non-blocking)
- §A.6b's "greppable Verify-cell lint" is described but not yet a CI check. If we want the falsifiable-verify rule enforced rather than documented (Rule 13), a follow-up could add a lint over plan step-tables. Out of scope for a template change.
Verdict
ACCEPT (docs). No blockers. Recommend merge after human approval.
lantiscooperdev
approved these changes
Jun 20, 2026
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.
Summary
Tracks
docs/PLAN_TEMPLATE.md(it was untracked) and adopts the evolved upstreampi-extensionsAppendix B so a lower-capability LLM can execute a plan without silent drift. Net: a weak executor now gets one editable file per step, a labeled action kind, a verbatim anchor, and a verify that is required to fail on a stub — closing the three places weak models drift (multi-file edits, vague anchors, hollow greens).What was adopted (user-approved A–F)
test $?, self-fulfilling grep, happy-path-only) + positive obligation (name observed + expected value) + compound-bash caveatUNGUARDED-IN-CItag — a MUST/Safety row covered only by a skippable smoke is tagged + names the manual step (no hollow green)CREATEtests with full verbatim assertions over real captured outputPlus 6 rows in §20 mapping each new rule to its enforcing section (our sync convention).
Adaptation notes
.mjs/bash and real slices (P3a pure-extraction; the ESC cross-session unmask as the fixture-change-ledger cautionary tale).compound-bash-gate.--append-system-prompt,--mode json); kept only the transferable non-deterministic-guard logic.Scope
Docs-only. No hooks/scripts/patterns touched. 524 → 655 lines (one new tracked file).
🤖 Generated with Claude Code