@sienklogic/plan-build-run 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.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.7.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.7.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/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.7.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.7.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-roadmap-sync.js

@@ -60,9 +60,18 @@ function main() {
 
       const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
       if (!roadmapStatus) {
-        logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+        logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
           reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
         });
+        logEvent('workflow', 'roadmap-sync', {
+          phase: stateInfo.phase,
+          stateStatus: stateInfo.status,
+          status: 'missing-phase'
+        });
+        const output = {
+          additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+        };
+        process.stdout.write(JSON.stringify(output));
         process.exit(0);
       }
 
@@ -80,7 +89,7 @@ function main() {
         });
 
         const output = {
-          additionalContext: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+          additionalContext: `CRITICAL: ROADMAP.md out of sync — Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
         };
         process.stdout.write(JSON.stringify(output));
       } else {
@@ -223,10 +232,17 @@ function checkSync(data) {
 
   const roadmapStatus = getRoadmapPhaseStatus(roadmapContent, stateInfo.phase);
   if (!roadmapStatus) {
-    logHook('check-roadmap-sync', 'PostToolUse', 'skip', {
+    logHook('check-roadmap-sync', 'PostToolUse', 'warn', {
       reason: `phase ${stateInfo.phase} not found in ROADMAP.md table`
     });
-    return null;
+    logEvent('workflow', 'roadmap-sync', {
+      phase: stateInfo.phase, stateStatus: stateInfo.status, status: 'missing-phase'
+    });
+    return {
+      output: {
+        additionalContext: `CRITICAL: Phase ${stateInfo.phase} has status "${stateInfo.status}" in STATE.md but is not listed in ROADMAP.md Progress table. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
+      }
+    };
   }
 
   if (roadmapStatus.toLowerCase() !== stateInfo.status) {
@@ -238,7 +254,7 @@ function checkSync(data) {
     });
     return {
       output: {
-        additionalContext: `ROADMAP.md out of sync: Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the Phase Overview table in ROADMAP.md to match.`
+        additionalContext: `CRITICAL: ROADMAP.md out of sync — Phase ${stateInfo.phase} is "${roadmapStatus}" in ROADMAP.md but "${stateInfo.status}" in STATE.md. Update the ROADMAP.md Progress table NOW before continuing. Run: \`node plugins/pbr/scripts/pbr-tools.js state load\` to check current state.`
       }
     };
   }

package/plugins/pbr/scripts/check-skill-workflow.js

@@ -10,6 +10,8 @@
  *   - /pbr:quick: Cannot write files outside .planning/ until a PLAN.md
  *     exists in .planning/quick/. This prevents the orchestrator from
  *     skipping the planning steps and jumping straight to implementation.
+ *   - /pbr:milestone, /pbr:explore, /pbr:import, /pbr:scan: Read-only skills
+ *     that cannot write files outside .planning/.
  *
  * Skills opt in by writing .planning/.active-skill at the start of
  * their execution. If the file doesn't exist, this hook does nothing.
@@ -116,9 +118,14 @@ function checkSkillRules(skill, filePath, planningDir) {
     return checkBuildRules(filePath, isInPlanning, planningDir);
   case 'statusline':
     return checkStatuslineRules(filePath, isInPlanning, planningDir);
+  case 'plan':
   case 'review':
   case 'discuss':
   case 'begin':
+  case 'milestone':
+  case 'explore':
+  case 'import':
+  case 'scan':
     return checkReadOnlySkillRules(skill, filePath, isInPlanning);
   default:
     return null;

package/plugins/pbr/scripts/progress-tracker.js

@@ -125,10 +125,10 @@ function buildContext(planningDir, stateFile) {
   }
 
   // Check for quick notes
-  const projectNotesFile = path.join(planningDir, 'NOTES.md');
-  const globalNotesFile = path.join(os.homedir(), '.claude', 'notes.md');
-  const projectNoteCount = countNotes(projectNotesFile);
-  const globalNoteCount = countNotes(globalNotesFile);
+  const projectNotesDir = path.join(planningDir, 'notes');
+  const globalNotesDir = path.join(os.homedir(), '.claude', 'notes');
+  const projectNoteCount = countNotes(projectNotesDir);
+  const globalNoteCount = countNotes(globalNotesDir);
   if (projectNoteCount > 0 || globalNoteCount > 0) {
     const noteParts = [];
     if (projectNoteCount > 0) noteParts.push(`${projectNoteCount} project`);
@@ -226,12 +226,16 @@ function findContinueFiles(dir) {
   return results;
 }
 
-function countNotes(filePath) {
+function countNotes(notesDir) {
   try {
-    if (!fs.existsSync(filePath)) return 0;
-    const content = fs.readFileSync(filePath, 'utf8');
-    const lines = content.split('\n');
-    return lines.filter(l => /^- \[/.test(l) && !l.includes('[promoted]')).length;
+    if (!fs.existsSync(notesDir)) return 0;
+    const files = fs.readdirSync(notesDir).filter(f => f.endsWith('.md'));
+    let count = 0;
+    for (const file of files) {
+      const content = fs.readFileSync(path.join(notesDir, file), 'utf8');
+      if (!content.includes('promoted: true')) count++;
+    }
+    return count;
   } catch (_e) {
     return 0;
   }

package/plugins/pbr/scripts/validate-task.js

@@ -252,6 +252,60 @@ function checkPlanExecutorGate(data) {
   };
 }
 
+/**
+ * Blocking check: when the active skill is "review" and a planner is being
+ * spawned, verify that a VERIFICATION.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ */
+function checkReviewPlannerGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:planner
+  if (subagentType !== 'pbr:planner') return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+
+  // Only gate when active skill is "review"
+  try {
+    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+    if (activeSkill !== 'review') return null;
+  } catch (_e) {
+    return null;
+  }
+
+  // Read STATE.md for current phase
+  const stateFile = path.join(planningDir, 'STATE.md');
+  try {
+    const state = fs.readFileSync(stateFile, 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)/);
+    if (!phaseMatch) return null;
+
+    const currentPhase = phaseMatch[1].padStart(2, '0');
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(currentPhase + '-'));
+    if (dirs.length === 0) return null;
+
+    const phaseDir = path.join(phasesDir, dirs[0]);
+    const hasVerification = fs.existsSync(path.join(phaseDir, 'VERIFICATION.md'));
+
+    if (!hasVerification) {
+      return {
+        block: true,
+        reason: 'Review planner gate: Cannot spawn planner for gap closure without a VERIFICATION.md. Run /pbr:review first to generate verification results.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
 function main() {
   let input = '';
 
@@ -285,6 +339,18 @@ function main() {
         return;
       }
 
+      // Blocking gate: review skill planner needs VERIFICATION.md
+      const reviewGate = checkReviewPlannerGate(data);
+      if (reviewGate && reviewGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: reviewGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: reviewGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
       // Blocking gate: plan skill cannot spawn executors
       const planGate = checkPlanExecutorGate(data);
       if (planGate && planGate.block) {
@@ -317,5 +383,5 @@ function main() {
   });
 }
 
-module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -80,7 +80,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.
@@ -154,7 +154,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/pbr/skills/note/SKILL.md

@@ -27,12 +27,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.
 
@@ -57,27 +68,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
@@ -94,11 +95,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
@@ -106,18 +107,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)`
 
 ---
 
@@ -133,7 +134,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
@@ -159,34 +160,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
@@ -229,3 +214,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/pbr/skills/quick/SKILL.md

@@ -86,7 +86,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: `Skill({ skill: "pbr:plan", args: "" })`. 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/pbr/skills/shared/context-loader-task.md

@@ -31,7 +31,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/pbr/skills/status/SKILL.md

@@ -147,9 +147,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