v4.0.1 Polish Pass: examples, templates, hook scripts, backend audit parity, dogfood WORKFLOW.md

Summary

A nine-gap polish pass against v4.0.0 (shipped on main at 1094187). No new guidelines, no new philosophy, no structural changes to the framework contract — every change closes a concrete gap between what v4.0.0's release notes promised and what actually shipped. Intended as a 4.0.1 patch release.

Gaps closed

• Gap 1 — v4.0.0 worked example PRDs. examples/ previously held only two v1.x specifications that predated the Agent-Era Update. Adds three plausible-but-fictional worked examples illustrating the v4.0.0 shape end to end: a backend Lambda PRD, a frontend React component PRD with a correctly split spanning requirement, and a system-level specification populating all 14 sections including Streaming Transports and Audit & Compliance Records (with an explicit fail-closed audit decision). examples/README.md is updated to distinguish v4.0.0 reference examples from v1.x legacy examples.
• Gap 2 — system-specification template. templates/ had no template for the new System guideline. Adds templates/system-specification-template.md mirroring the 14-section spine with one-line placeholder prompts per section; optional cross-cutting sections (§6, §7) are marked "delete if not applicable."
• Gap 3 — reference hook scripts. templates/workflow-template.md §4 named three scripts (pre-commit-gate, verify-archival, session-bootstrap) but shipped only a minimal inline body for one of them. Ships all three as copy-ready .bash files under templates/scripts/, invoked via bash <path>.bash. pre-commit-gate.bash is fail-closed on jq/stdin parse errors and emits the Claude Code deny JSON shape; verify-archival.bash reports every offending implementation log; session-bootstrap.bash is a read-only one-line situational summary. Template §4 is updated to point at the shipped files.
• Gap 4 — implementation-tasks-creation-guidelines.md Process section aligned with the Agent Execution Model section at the top of the same file. Five corrections: Step 0 now names WORKFLOW.md as the authoritative source; Step 1's dangling reference to the non-existent guidelines-for-clarifying-feature-specifications.md is replaced with a pointer to the actual PRD generation guidelines; Steps 2–3 name tools explicitly (Read/Grep/Glob, Explore subagent for surveys > ~5 files); a new Step 3.5 makes it explicit that the agent spawns the PRD's Delegatable Research subagents in parallel before proposing the plan; and Step 4's prompt now tells the user to respond with "Let's boogie!" to match Step 5's wait condition (the fun phrase is deliberately preserved).
• Gap 5 — stale cross-reference in workflow-file-guidelines.md. The "How This Integrates with the Other Guidelines" section previously claimed that the System guideline's "Workflow / Policy File" section is the system's own version of the WORKFLOW.md convention. That framing was wrong: the section was renamed in v4.0.0 to "Service Policy / Configuration File" specifically to disambiguate it from the project-level WORKFLOW.md, and a service's operational configuration is a different artifact. Bullet rewritten to make the distinction explicit.
• Gap 6 — search-and-replace residue (configuration␣␣). Recorded but no-op: already fixed during v4.0.0 development in commit 1094187. Grep confirmed zero hits across the repository. The v4.0.1 changelog entry records the audit result for completeness.
• Gap 7 — blank-line formatting. Several files had blank lines removed between headings by an earlier formatter pass, leaving headings that abutted their predecessors. Inserts exactly one blank line before every ## and ### heading that needed one across seven files. Wording unchanged. Intentional Markdown hard-break trailing spaces in the exploratory guideline are preserved. Headings inside fenced code blocks (example PRD structures) are deliberately left alone.
• Gap 8 — /WORKFLOW.md at the repository root (dog food). This framework told every adopting project to place a WORKFLOW.md at its root, but the framework itself did not have one. Adds /WORKFLOW.md encoding this repository's actual rules: §1 Test Commands explicitly states the repository is documentation-only and no PreToolUse(Bash:git commit) hook is wired (with rationale so the absence isn't mistaken for an oversight); §2 Branch Policy; §3 Commit Style; §4 Hook Configuration pointing at existing .claude/settings.json and protect-env.sh; §5–6 subagent defaults and archival protocol; §7 Project-Specific Conventions covering changelog discipline, version-bump rules, directory layout, the dog-food rule, the no-abbreviations rule, and the .bash script convention. README.md and guidelines/workflow-file-guidelines.md now reference /WORKFLOW.md as a live worked example alongside the abstract template.
• Gap 9 — backend guideline parity with frontend. The backend guideline previously lacked both a named "Before Asking Anything — Use Tools First" subsection and a "PRD Review Checkpoint: Final Audit" section that frontend has at §5. Structural asymmetry sent an unintended signal that backend PRDs received less review rigor than frontend PRDs, which is the opposite of what the framework wants for the layer that holds business logic, security, and data integrity. Full parity, not trimmed: the audit is a review step the agent runs on a finished PRD — its length lives in the guideline file, not the resulting PRDs, so "keep it short to avoid bloating PRDs" was a category error. Backend has its own red-flag surface area comparable to frontend's (non-idempotent write endpoints, missing error envelopes, IAM overreach, fail-open audit on audit-relevant paths, multi-table writes without a transactional story, response shapes driven by a single current caller, and so on). Backend guideline grows from 154 to 206 lines; still materially shorter than frontend's 542 because frontend has content backend does not need.

Commits

One commit per gap in Conventional Commits style, in a sensible safest-first order:

1. 7221f08 — style(docs): normalize blank lines before headings (Gap 7)
2. 7fa12ee — docs(workflow): fix stale System Spec cross-reference (Gap 5)
3. 94e2deb — docs(tasks): align Process section with Agent Execution Model (Gap 4)
4. 5d93a74 — docs(templates): ship reference hook scripts (Gap 3)
5. 3ed5786 — docs(templates): add system-specification template (Gap 2)
6. 357d1e9 — docs(examples): add v4.0.0 worked example PRDs (Gap 1)
7. b3bd7c1 — docs: add WORKFLOW.md at repository root; dogfood v4.0.0 (Gap 8)
8. 0573c92 — docs(backend): add Final Audit and tools-first subsection (Gap 9)
9. 3621426 — docs(changelog): 4.0.1 polish pass entry

Version note

package.json is deliberately not bumped. v4.0.0 was already released on GitHub at that version string; the polish pass ships as a 4.0.1 changelog entry without rolling the package.json version forward. A v4.0.1 git tag was pushed to origin alongside this release.

Scope discipline

• No new guidelines added.
• No existing guidelines rewritten wholesale.
• No new philosophical concepts, taxonomy entries, or section types in the spines.
• .claude/settings.json, the f55fad9 env-protection changes, and infrastructure outside the guideline content are untouched.
• main was never committed to directly and was never force-pushed.

🤖 Generated with Claude Code