Skip to content

docs(plan-template): track PLAN_TEMPLATE.md + adopt falsifiable-verify & blast-radius hardening#412

Merged
lantiscooperdev merged 1 commit into
mainfrom
docs/plan-template-executor-hardening
Jun 20, 2026
Merged

docs(plan-template): track PLAN_TEMPLATE.md + adopt falsifiable-verify & blast-radius hardening#412
lantiscooperdev merged 1 commit into
mainfrom
docs/plan-template-executor-hardening

Conversation

@lantisprime

Copy link
Copy Markdown
Owner

Summary

Tracks docs/PLAN_TEMPLATE.md (it was untracked) and adopts the evolved upstream pi-extensions Appendix 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)

Item What Where
A Falsifiable Verify — parent rule + deny-list (tolerant test $?, self-fulfilling grep, happy-path-only) + positive obligation (name observed + expected value) + compound-bash caveat new §A.6b
B UNGUARDED-IN-CI tag — a MUST/Safety row covered only by a skippable smoke is tagged + names the manual step (no hollow green) §4, §7
C No aspirational output — a printed "checking X" must assert X §A.2 item 9, §14
D Test-body rigor = code rigorCREATE tests with full verbatim assertions over real captured output §A.7
E One-file-per-step + CREATE/EDIT/APPEND + executor-ready gate §A.2, §A.6, §A.7
F Blast-radius patterns — red-then-green, pure-extraction-first, thin-wrapper, fixture-change ledger, discriminating sentinel, flag-high-blast-radius, mock-project E2E, non-deterministic-guard new §A.9

Plus 6 rows in §20 mapping each new rule to its enforcing section (our sync convention).

Adaptation notes

  • Re-grounded examples in .mjs/bash and real slices (P3a pure-extraction; the ESC cross-session unmask as the fixture-change-ledger cautionary tale).
  • Compound-bash caveat makes the negative-control pattern legal under this repo's compound-bash-gate.
  • Dropped pi's LLM-app specifics (--append-system-prompt, --mode json); kept only the transferable non-deterministic-guard logic.
  • Preserves all existing governance (RFC R-grounding, Rule 12 token budget, three-layer review, lessons table).

Scope

Docs-only. No hooks/scripts/patterns touched. 524 → 655 lines (one new tracked file).

🤖 Generated with Claude Code

…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 lantiscooperdev left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 lantiscooperdev merged commit b5fbf5a into main Jun 20, 2026
2 checks passed
@lantisprime lantisprime deleted the docs/plan-template-executor-hardening branch June 20, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants