v4.0.2 polish pass: validation vocabulary, audit parity, pseudocode discipline

Summary

A second polish pass against v4.0.1, additive only. No new required PRD sections, no changes to existing PRD structure, no breaking changes to any guideline contract. v4.0.1 PRDs remain valid and conformant. Three themes: a named failure taxonomy for specification reviews, parity in the Final Audit surface across all four PRD guidelines, and reference pseudocode blocks for the two parts of the framework where ordering and error paths are most load-bearing. Shipped as a 4.0.2 patch release.

What's new

• guidelines/specification-validation-vocabulary.md (new file). ~50 named failure codes a specification reviewer (human or subagent) can cite when auditing a PRD, system spec, task list, or WORKFLOW.md. Each entry has a stable snake_case identifier, a one-line description, the guideline section it belongs to, and example failure/fix pairs. Adapted from the OpenAI Symphony SPEC.md §5.5 error-taxonomy pattern, where every validation failure has a stable name so hooks, tooling, and reviewers can reference the same concept without re-inventing vocabulary every time. Organized into Cross-Guideline, Backend, Frontend, System, Implementation Tasks, Workflow File, and Exploratory categories. Includes Conformance Profiles (Core / Extension / Integration) for tiering audits by spec type, and a forward-compatibility rule (unknown codes in audit output are ignored with a warning, never rejected).

• Final Audit parity across all four PRD guidelines. v4.0.1 added a Final Audit to the Backend guideline (Gap 9) but left the System and Exploratory guidelines without one. v4.0.2 closes that asymmetry:

  • System guideline gains a full Final Audit with Structural Completeness, Cross-Cutting Concerns (streaming and audit), Testing & Execution, and Red Flags subsections. Every checkbox and red-flag bullet cites a stable identifier from the new vocabulary.
  • Exploratory guideline gains a deliberately lightweight §6.5 Final Audit. Five checks for the failure modes that would cause downstream rework — skipped recon, contradicted constraints, ambiguous migration target. Short on purpose, because exploratory documents are scratch space for creative work, not contracts the agent will execute.

• Backpatched vocabulary citations on existing audits. Every red-flag bullet and every checkbox in the Backend §PRD Review Checkpoint and the Frontend §5 Final Audit now carries a parenthetical vocabulary code. Wording is unchanged; the codes are additive metadata that lets reviewer subagents and hooks cite findings by stable name rather than re-describing them in prose, and lets external tools grep audit output for code names.

• "When to Use This Guideline (and When Not To)" blocks on Backend and Frontend. Matches the existing block in the System guideline. An agent picking the wrong guideline catches the mistake before writing the PRD instead of after. Each block lists "use this for" with concrete cases and "do not use this for" with explicit redirects to the right guideline (streaming → System §6, audit → System §7, multi-component service → System, etc.).

• Reference pseudocode blocks in two guidelines. The framework now treats pseudocode as a first-class tool for specification authors, not a stylistic flourish:

  • guidelines/system-specification-guidelines.md — IssueState state machine. A worked pseudocode block in the Symphony-like example section. Demonstrates how pseudocode resolves the audit-write ordering question that prose §7.7 hedges around: audit write happens before the state transition, workspace release is gated on the transition completing, reconciliation distinguishes "in-flight with recent heartbeat" from "in-flight but stale." Closes ambiguity that prose alone could not.
  • guidelines/implementation-tasks-creation-guidelines.md — agent PRD-execution loop. Pins down the gates that hooks enforce: audit before branch creation, recon before plan, user confirmation as a hard gate, per-task verification, archival gated by the Stop hook. The agent's PRD-consumption loop is now a contract, not a prose narrative.

• README.md — "The Case for Pseudocode in Specifications." A new educational section between the Sample Interaction Flow and "What the Framework Aims to Produce." Covers what pseudocode is in this framework (language-neutral, ordered, named-step descriptions of control flow); why it beats prose for hard parts of a spec (with a worked before/after audit-write example); pseudocode as a forcing function for the author rather than a translation hint for the implementer; pseudocode as a contract that commits to ordering/invariants/error-paths while staying silent about syntax/libraries/types; when to write it (state machines, ordering-dependent algorithms, reconciliation logic, multi-step transactions, agent-execution loops); when not to (simple CRUD, UI rendering, configuration shapes, anything over ~30 lines); and a reading order for the two pseudocode blocks shipped here.

• guidelines/README.md indexes the new validation vocabulary file under a "Validation Vocabulary (1) — NEW in v4.0.2" subsection so adopters reading the directory index can find it.

Commits

One commit per concern, in safest-first order:

1. 55eac8c — docs(guidelines): add specification validation vocabulary
2. e985f2f — docs(guidelines): cite vocabulary codes in backend/frontend Final Audits
3. 5d13f75 — docs(system): add Final Audit and reference IssueState pseudocode
4. ec0b86b — docs(exploratory): add lightweight Final Audit (§6.5)
5. 644611f — docs(tasks): add reference pseudocode for the agent PRD-execution loop
6. e4775b9 — docs(readme): add 'The Case for Pseudocode in Specifications' section
7. 80bcd89 — docs(changelog): 4.0.2 validation vocabulary and pseudocode entry

Merged via PR #3 as merge commit 90eaee6.

Why this is a patch release

Per WORKFLOW.md §7 version-bump rules, a patch release is "corrections, clarifications, and editorial polish that do not change expectations." v4.0.2 meets that bar:

• No new required PRD sections. Every section added is either internal (Final Audit, which lives in the guideline file rather than the resulting PRD) or additive (the vocabulary file is a new artifact that existing PRDs do not need to reference).
• No structural changes to existing PRDs. v4.0.1 PRDs remain valid and conformant. The only thing that has changed is that a reviewer auditing them now has stable identifiers for findings.
• No new required artifacts at the project root. v4.0.0 already requires WORKFLOW.md; v4.0.2 does not require anything new.
• All edits are additive. Backpatching parenthetical codes onto existing checkboxes does not alter their semantics; new sections live alongside the existing structure rather than replacing it.

Version note

package.json is deliberately not bumped, mirroring v4.0.1. The polish pass ships as a 4.0.2 changelog entry. The v4.0.2 git tag was pushed to origin alongside this release.

Scope discipline

• No new guidelines added in the PRD-generating sense — specification-validation-vocabulary.md is a reference artifact for reviewers, not a guideline that produces a PRD.
• No existing guidelines rewritten wholesale — every audit edit is additive metadata or a new section appended.
• No structural change to any existing PRD spine.
• .claude/settings.json, the env-protection hook, and infrastructure outside the guideline content are untouched.
• main was never committed to directly and was never force-pushed.

🤖 Generated with Claude Code