@sienklogic/plan-build-run 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.7.0...plan-build-run-v2.8.0) (2026-02-20)
+
+
+### Features
+
+* **03-01:** add review verifier, milestone complete, and build dependency gates ([bda474d](https://github.com/SienkLogic/plan-build-run/commit/bda474d8b88b128464df375d62de9acdeb9dff05))
+* **04-01:** add post-artifact validation for begin/plan/build and VERIFICATION.md ([3cb4bc1](https://github.com/SienkLogic/plan-build-run/commit/3cb4bc1c0f277c6beca99f7c336fba5e7376f9ec))
+* **05-01:** add STATE.md validation, checkpoint manifest check, and active-skill integrity warning ([d780d97](https://github.com/SienkLogic/plan-build-run/commit/d780d97e620915cb05e70372ce8c9d6003fd1ac8))
+
+## [2.7.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.6.0...plan-build-run-v2.7.0) (2026-02-19)
+
+
+### Features
+
+* **02-01:** add milestone, explore, import, scan write guards to checkSkillRules ([bd21366](https://github.com/SienkLogic/plan-build-run/commit/bd21366f8f63277566035f0827e3fde2ebc39400))
+* **02-02:** add review planner gate to validate-task.js ([89ffb05](https://github.com/SienkLogic/plan-build-run/commit/89ffb05bc6384fc47fbf85ac7c875e16a29db0b9))
+* **02-02:** strengthen ROADMAP sync warnings to CRITICAL level ([7120d60](https://github.com/SienkLogic/plan-build-run/commit/7120d60fdc6678d8c9853679b0d3464116821097))
+
+
+### Bug Fixes
+
+* **tools:** auto-route quick skill to plan skill when user selects Full plan ([252a35e](https://github.com/SienkLogic/plan-build-run/commit/252a35ed9942c2b1902f38923bb80d92d819ae4e))
+
 ## [2.6.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.5.0...plan-build-run-v2.6.0) (2026-02-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/setup.sh

@@ -37,7 +37,7 @@ fi
 if command -v copilot &> /dev/null; then
   echo "Found Copilot CLI. Installing plugin via 'copilot plugin install'..."
   echo ""
-  copilot plugin install --local "$PLUGIN_DIR"
+  copilot plugin install "$PLUGIN_DIR"
   echo ""
   echo "Plugin installed successfully via Copilot CLI."
 else

package/plugins/copilot-pbr/skills/import/SKILL.md

@@ -76,7 +76,7 @@ Read all relevant context files. This context is used for conflict detection in
    - trigger equals the phase number as integer
    - trigger equals * (always matches)
 9. Pending todos — scan .planning/todos/pending/ for items related to this phase
-10. NOTES.md (if exists at .planning/NOTES.md) — check for related notes
+10. Notes (if .planning/notes/ exists) — check for related notes
 ```
 
 Collect all of this into a context bundle for use in Steps 4 and 5.
@@ -150,7 +150,7 @@ Run each of these checks. If any matches, record a `[WARNING]`:
 #### INFO checks (supplementary context):
 Run each of these checks. If any matches, record an `[INFO]`:
 
-1. **Related notes**: Are there related notes in NOTES.md?
+1. **Related notes**: Are there related notes in `.planning/notes/`?
 2. **Matching seeds**: Are there matching seeds in `.planning/seeds/` that could enhance the plan?
 3. **Prior phase patterns**: What patterns from prior phases (from SUMMARY.md `patterns` fields) should the imported plan follow?
 

package/plugins/copilot-pbr/skills/note/SKILL.md

@@ -23,12 +23,23 @@ This skill runs **inline** — no Task, no AskUserQuestion, no Bash.
 
 ---
 
-## Scope Detection
+## Storage Format
 
-Two scopes exist. Auto-detect which to use:
+Notes are stored as **individual markdown files** in a notes directory:
 
-1. **Project scope**: `.planning/NOTES.md` — used when `.planning/` directory exists in cwd
-2. **Global scope**: `~/.claude/notes.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` directory exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file has this format:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
 
 **`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
 
@@ -53,27 +64,17 @@ Parse `$ARGUMENTS` after stripping `--global`:
 
 ## Subcommand: append
 
-Append a timestamped note to the target file.
+Create a timestamped note file in the target directory.
 
 ### Steps
 
-1. Determine scope (project or global) per Scope Detection above
-2. Read the target file if it exists
-3. If the file doesn't exist, create it with this header:
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-```
-
-4. Ensure the file content ends with a newline before appending
-5. Append: `- [YYYY-MM-DD HH:mm] {note text verbatim}`
-6. Write the file
-7. Confirm with exactly one line: `Noted ({scope}): {note text}`
+1. Determine scope (project or global) per Storage Format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see Storage Format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
    - Where `{scope}` is "project" or "global"
 
 ### Constraints
@@ -90,11 +91,11 @@ Show notes from both project and global scopes.
 
 ### Steps
 
-1. Read `.planning/NOTES.md` (if exists) — these are "project" notes
-2. Read `~/.claude/notes.md` (if exists) — these are "global" notes
-3. Parse entries: lines matching `^- \[` are notes
-4. Exclude lines containing `[promoted]` from active counts (but still show them, dimmed)
-5. Number all active entries sequentially starting at 1, using plain integers (1, 2, 3...) for display (across both scopes)
+1. Glob `.planning/notes/*.md` (if directory exists) — these are "project" notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — these are "global" notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
 6. If total active entries > 20, show only the last 10 with a note about how many were omitted
 
 ### Display Format
@@ -102,18 +103,18 @@ Show notes from both project and global scopes.
 ```
 Notes:
 
-Project (.planning/NOTES.md):
+Project (.planning/notes/):
   1. [2026-02-08 14:32] refactor the hook system to support async validators
   2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
   3. [2026-02-08 15:10] consider adding a --dry-run flag to build
 
-Global (~/.claude/notes.md):
+Global (~/.claude/notes/):
   4. [2026-02-08 10:00] cross-project idea about shared config
 
 {count} active note(s). Use `/pbr:note promote <N>` to convert to a todo.
 ```
 
-If a scope has no file or no entries, show: `(no notes)`
+If a scope has no directory or no entries, show: `(no notes)`
 
 ---
 
@@ -129,7 +130,7 @@ Convert a note into a todo file.
 4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run `/pbr:begin` to initialize one, or use `/pbr:todo add` in an existing project."
 5. Ensure `.planning/todos/pending/` directory exists
 6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text, lowercase, hyphen-separated
-7. Extract the note text (everything after the timestamp)
+7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
 ```yaml
@@ -155,34 +156,18 @@ Promoted from quick note captured on {original date}.
 - [ ] {primary criterion derived from note text}
 ```
 
-9. Mark the original note as promoted: replace `- [` with `- [promoted] [` on that line
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
 10. Confirm: `Promoted note {N} to todo {id}: {note text}`
 
 ---
 
-## NOTES.md Format Reference
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-- [2026-02-08 14:32] refactor the hook system to support async validators
-- [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
-- [2026-02-08 15:10] consider adding a --dry-run flag to build
-```
-
----
-
 ## Edge Cases
 
 1. **"list" as note text**: `/pbr:note list of things` → saves note "list of things" (subcommand only when `list` is the entire arg)
-2. **No `.planning/`**: Falls back to global `~/.claude/notes.md` — works in any directory
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
 3. **Promote without project**: Warns that todos require `.planning/`, suggests `/pbr:begin`
 4. **Large files**: `list` shows last 10 when >20 active entries
-5. **Missing newline**: Always ensure trailing newline before appending
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
 6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
 7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
 8. **Empty note text after stripping flags**: Treat as `list` subcommand
@@ -225,3 +210,4 @@ Note {N} not found. Valid range: 1-{max}.
 4. **DO NOT** create `.planning/` if it doesn't exist — fall back to global
 5. **DO NOT** number promoted notes in the active count (but still display them)
 6. **DO NOT** over-format the confirmation — one line is enough
+7. **DO NOT** use a flat NOTES.md file — always use individual files in notes directory

package/plugins/copilot-pbr/skills/quick/SKILL.md

@@ -85,7 +85,7 @@ Use AskUserQuestion:
   multiSelect: false
 
 If user selects "Quick task": continue to Step 4.
-If user selects "Full plan": respond "Use `/pbr:plan` to create a full planning cycle for this task." and stop.
+If user selects "Full plan": clean up `.active-skill` if it exists, then chain directly to the plan skill. The user's task description carries over in conversation context — the plan skill will pick it up.
 If user selects "Revise": go back to Step 2 to get a new task description.
 If user types something else (freeform): interpret their response and proceed accordingly.
 

package/plugins/copilot-pbr/skills/shared/context-loader-task.md

@@ -32,7 +32,7 @@ Task({
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
-    - .planning/NOTES.md (if exists)
+    - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
     - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
 
   Return ONLY the briefing text. No preamble, no suggestions."

package/plugins/copilot-pbr/skills/status/SKILL.md

@@ -142,9 +142,9 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - Count and summarize if any exist
 
 #### Quick Notes
-- Check `.planning/NOTES.md` for active note entries
-- Count active notes (lines matching `^- \[` that don't contain `[promoted]`)
-- Also check `~/.claude/notes.md` for global notes
+- Check `.planning/notes/` directory for note files (individual `.md` files)
+- Count active notes (files where frontmatter does NOT contain `promoted: true`)
+- Also check `~/.claude/notes/` for global notes
 
 #### Quick Tasks
 - Check `.planning/quick/` for recent quick tasks

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/skills/import/SKILL.md

@@ -77,7 +77,7 @@ Read all relevant context files. This context is used for conflict detection in
    - trigger equals the phase number as integer
    - trigger equals * (always matches)
 9. Pending todos — scan .planning/todos/pending/ for items related to this phase
-10. NOTES.md (if exists at .planning/NOTES.md) — check for related notes
+10. Notes (if .planning/notes/ exists) — check for related notes
 ```
 
 Collect all of this into a context bundle for use in Steps 4 and 5.
@@ -151,7 +151,7 @@ Run each of these checks. If any matches, record a `[WARNING]`:
 #### INFO checks (supplementary context):
 Run each of these checks. If any matches, record an `[INFO]`:
 
-1. **Related notes**: Are there related notes in NOTES.md?
+1. **Related notes**: Are there related notes in `.planning/notes/`?
 2. **Matching seeds**: Are there matching seeds in `.planning/seeds/` that could enhance the plan?
 3. **Prior phase patterns**: What patterns from prior phases (from SUMMARY.md `patterns` fields) should the imported plan follow?
 

package/plugins/cursor-pbr/skills/note/SKILL.md

@@ -24,12 +24,23 @@ This skill runs **inline** — no Task, no AskUserQuestion, no Bash.
 
 ---
 
-## Scope Detection
+## Storage Format
 
-Two scopes exist. Auto-detect which to use:
+Notes are stored as **individual markdown files** in a notes directory:
 
-1. **Project scope**: `.planning/NOTES.md` — used when `.planning/` directory exists in cwd
-2. **Global scope**: `~/.claude/notes.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` directory exists in cwd
+- **Global scope**: `~/.claude/notes/{YYYY-MM-DD}-{slug}.md` — used as fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file has this format:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
 
 **`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
 
@@ -54,27 +65,17 @@ Parse `$ARGUMENTS` after stripping `--global`:
 
 ## Subcommand: append
 
-Append a timestamped note to the target file.
+Create a timestamped note file in the target directory.
 
 ### Steps
 
-1. Determine scope (project or global) per Scope Detection above
-2. Read the target file if it exists
-3. If the file doesn't exist, create it with this header:
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-```
-
-4. Ensure the file content ends with a newline before appending
-5. Append: `- [YYYY-MM-DD HH:mm] {note text verbatim}`
-6. Write the file
-7. Confirm with exactly one line: `Noted ({scope}): {note text}`
+1. Determine scope (project or global) per Storage Format above
+2. Ensure the notes directory exists (`.planning/notes/` or `~/.claude/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see Storage Format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
    - Where `{scope}` is "project" or "global"
 
 ### Constraints
@@ -91,11 +92,11 @@ Show notes from both project and global scopes.
 
 ### Steps
 
-1. Read `.planning/NOTES.md` (if exists) — these are "project" notes
-2. Read `~/.claude/notes.md` (if exists) — these are "global" notes
-3. Parse entries: lines matching `^- \[` are notes
-4. Exclude lines containing `[promoted]` from active counts (but still show them, dimmed)
-5. Number all active entries sequentially starting at 1, using plain integers (1, 2, 3...) for display (across both scopes)
+1. Glob `.planning/notes/*.md` (if directory exists) — these are "project" notes
+2. Glob `~/.claude/notes/*.md` (if directory exists) — these are "global" notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
 6. If total active entries > 20, show only the last 10 with a note about how many were omitted
 
 ### Display Format
@@ -103,18 +104,18 @@ Show notes from both project and global scopes.
 ```
 Notes:
 
-Project (.planning/NOTES.md):
+Project (.planning/notes/):
   1. [2026-02-08 14:32] refactor the hook system to support async validators
   2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
   3. [2026-02-08 15:10] consider adding a --dry-run flag to build
 
-Global (~/.claude/notes.md):
+Global (~/.claude/notes/):
   4. [2026-02-08 10:00] cross-project idea about shared config
 
 {count} active note(s). Use `/pbr:note promote <N>` to convert to a todo.
 ```
 
-If a scope has no file or no entries, show: `(no notes)`
+If a scope has no directory or no entries, show: `(no notes)`
 
 ---
 
@@ -130,7 +131,7 @@ Convert a note into a todo file.
 4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a Plan-Build-Run project. Run `/pbr:begin` to initialize one, or use `/pbr:todo add` in an existing project."
 5. Ensure `.planning/todos/pending/` directory exists
 6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text, lowercase, hyphen-separated
-7. Extract the note text (everything after the timestamp)
+7. Extract the note text from the source file (body after frontmatter)
 8. Create `.planning/todos/pending/{id}.md`:
 
 ```yaml
@@ -156,34 +157,18 @@ Promoted from quick note captured on {original date}.
 - [ ] {primary criterion derived from note text}
 ```
 
-9. Mark the original note as promoted: replace `- [` with `- [promoted] [` on that line
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
 10. Confirm: `Promoted note {N} to todo {id}: {note text}`
 
 ---
 
-## NOTES.md Format Reference
-
-```markdown
-# Notes
-
-Quick captures from `/pbr:note`. Ideas worth remembering.
-
----
-
-- [2026-02-08 14:32] refactor the hook system to support async validators
-- [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
-- [2026-02-08 15:10] consider adding a --dry-run flag to build
-```
-
----
-
 ## Edge Cases
 
 1. **"list" as note text**: `/pbr:note list of things` → saves note "list of things" (subcommand only when `list` is the entire arg)
-2. **No `.planning/`**: Falls back to global `~/.claude/notes.md` — works in any directory
+2. **No `.planning/`**: Falls back to global `~/.claude/notes/` — works in any directory
 3. **Promote without project**: Warns that todos require `.planning/`, suggests `/pbr:begin`
 4. **Large files**: `list` shows last 10 when >20 active entries
-5. **Missing newline**: Always ensure trailing newline before appending
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
 6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
 7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
 8. **Empty note text after stripping flags**: Treat as `list` subcommand
@@ -226,3 +211,4 @@ Note {N} not found. Valid range: 1-{max}.
 4. **DO NOT** create `.planning/` if it doesn't exist — fall back to global
 5. **DO NOT** number promoted notes in the active count (but still display them)
 6. **DO NOT** over-format the confirmation — one line is enough
+7. **DO NOT** use a flat NOTES.md file — always use individual files in notes directory

package/plugins/cursor-pbr/skills/quick/SKILL.md

@@ -85,7 +85,7 @@ Use AskUserQuestion:
   multiSelect: false
 
 If user selects "Quick task": continue to Step 4.
-If user selects "Full plan": respond "Use `/pbr:plan` to create a full planning cycle for this task." and stop.
+If user selects "Full plan": clean up `.active-skill` if it exists, then chain directly to the plan skill. The user's task description carries over in conversation context — the plan skill will pick it up.
 If user selects "Revise": go back to Step 2 to get a new task description.
 If user types something else (freeform): interpret their response and proceed accordingly.
 

package/plugins/cursor-pbr/skills/shared/context-loader-task.md

@@ -32,7 +32,7 @@ Task({
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
-    - .planning/NOTES.md (if exists)
+    - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
     - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
 
   Return ONLY the briefing text. No preamble, no suggestions."

package/plugins/cursor-pbr/skills/status/SKILL.md

@@ -142,9 +142,9 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - Count and summarize if any exist
 
 #### Quick Notes
-- Check `.planning/NOTES.md` for active note entries
-- Count active notes (lines matching `^- \[` that don't contain `[promoted]`)
-- Also check `~/.claude/notes.md` for global notes
+- Check `.planning/notes/` directory for note files (individual `.md` files)
+- Count active notes (files where frontmatter does NOT contain `promoted: true`)
+- Also check `~/.claude/notes/` for global notes
 
 #### Quick Tasks
 - Check `.planning/quick/` for recent quick tasks

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/scripts/check-plan-format.js

@@ -42,7 +42,9 @@ function main() {
       const isPlan = basename.endsWith('PLAN.md');
       const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
 
-      if (!isPlan && !isSummary) {
+      const isVerification = basename === 'VERIFICATION.md';
+
+      if (!isPlan && !isSummary && !isVerification) {
         process.exit(0);
       }
 
@@ -53,9 +55,11 @@ function main() {
       const content = fs.readFileSync(filePath, 'utf8');
       const result = isPlan
         ? validatePlan(content, filePath)
-        : validateSummary(content, filePath);
+        : isVerification
+          ? validateVerification(content, filePath)
+          : validateSummary(content, filePath);
 
-      const eventType = isPlan ? 'plan-validated' : 'summary-validated';
+      const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : 'summary-validated';
 
       if (result.errors.length > 0) {
         // Structural errors — block and force correction
@@ -231,16 +235,19 @@ function checkPlanWrite(data) {
   const basename = path.basename(filePath);
   const isPlan = basename.endsWith('PLAN.md');
   const isSummary = basename.includes('SUMMARY') && basename.endsWith('.md');
+  const isVerification = basename === 'VERIFICATION.md';
 
-  if (!isPlan && !isSummary) return null;
+  if (!isPlan && !isSummary && !isVerification) return null;
   if (!fs.existsSync(filePath)) return null;
 
   const content = fs.readFileSync(filePath, 'utf8');
   const result = isPlan
     ? validatePlan(content, filePath)
-    : validateSummary(content, filePath);
+    : isVerification
+      ? validateVerification(content, filePath)
+        : validateSummary(content, filePath);
 
-  const eventType = isPlan ? 'plan-validated' : 'summary-validated';
+  const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : 'summary-validated';
 
   if (result.errors.length > 0) {
     logHook('check-plan-format', 'PostToolUse', 'block', { file: basename, errors: result.errors });
@@ -266,5 +273,80 @@ function checkPlanWrite(data) {
   return null;
 }
 
-module.exports = { validatePlan, validateSummary, checkPlanWrite };
+function validateState(content, _filePath) {
+  const errors = [];
+  const warnings = [];
+
+  // STATE.md uses warnings (not errors) because it's written by multiple hooks
+  // and auto-sync processes. Blocking would create feedback loops.
+  if (!content.startsWith('---')) {
+    warnings.push('Missing YAML frontmatter');
+  } else {
+    const frontmatterEnd = content.indexOf('---', 3);
+    if (frontmatterEnd === -1) {
+      warnings.push('Unclosed YAML frontmatter');
+    } else {
+      const frontmatter = content.substring(3, frontmatterEnd);
+      const requiredFields = ['version', 'current_phase', 'total_phases', 'phase_slug', 'status'];
+      for (const field of requiredFields) {
+        if (!frontmatter.includes(`${field}:`)) {
+          warnings.push(`Frontmatter missing "${field}" field`);
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+function validateVerification(content, _filePath) {
+  const errors = [];
+  const warnings = [];
+
+  if (!content.startsWith('---')) {
+    errors.push('Missing YAML frontmatter');
+  } else {
+    const frontmatterEnd = content.indexOf('---', 3);
+    if (frontmatterEnd === -1) {
+      errors.push('Unclosed YAML frontmatter');
+    } else {
+      const frontmatter = content.substring(3, frontmatterEnd);
+      const requiredFields = ['status', 'phase', 'checked_at', 'must_haves_checked', 'must_haves_passed', 'must_haves_failed'];
+      for (const field of requiredFields) {
+        if (!frontmatter.includes(`${field}:`)) {
+          errors.push(`Frontmatter missing "${field}" field`);
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Separate STATE.md validation for use by dispatchers.
+ * Kept separate from checkPlanWrite because STATE.md routing in the
+ * dispatcher must happen AFTER roadmap sync (which also triggers on STATE.md).
+ */
+function checkStateWrite(data) {
+  const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+  const basename = path.basename(filePath);
+  if (basename !== 'STATE.md') return null;
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = validateState(content, filePath);
+
+  if (result.warnings.length > 0) {
+    logHook('check-plan-format', 'PostToolUse', 'warn', { file: basename, warnings: result.warnings });
+    logEvent('workflow', 'state-validated', { file: basename, status: 'warn', warningCount: result.warnings.length });
+    return { output: { additionalContext: `${basename} warnings:\n${result.warnings.map(i => `  - ${i}`).join('\n')}` } };
+  }
+
+  logHook('check-plan-format', 'PostToolUse', 'pass', { file: basename });
+  logEvent('workflow', 'state-validated', { file: basename, status: 'pass' });
+  return null;
+}
+
+module.exports = { validatePlan, validateSummary, validateVerification, validateState, checkPlanWrite, checkStateWrite };
 if (require.main === module || process.argv[1] === __filename) { main(); }