@sienklogic/plan-build-run 2.6.0 → 2.8.0

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

@@ -252,6 +252,384 @@ 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;
+}
+
+/**
+ * Blocking check: when the active skill is "review" and a verifier is being
+ * spawned, verify that a SUMMARY*.md exists in the current phase directory.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ */
+function checkReviewVerifierGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:verifier
+  if (subagentType !== 'pbr:verifier') 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 files = fs.readdirSync(phaseDir);
+    const hasSummary = files.some(f => {
+      if (!/^SUMMARY/i.test(f)) return false;
+      try {
+        return fs.statSync(path.join(phaseDir, f)).size > 0;
+      } catch (_e) {
+        return false;
+      }
+    });
+
+    if (!hasSummary) {
+      return {
+        block: true,
+        reason: 'Review verifier gate: Cannot spawn verifier without SUMMARY.md in phase directory. Run /pbr:build first.'
+      };
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Blocking check: when the active skill is "milestone" and a general/planner agent
+ * is being spawned for a "complete" operation, verify all milestone phases have VERIFICATION.md.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ */
+function checkMilestoneCompleteGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+  const description = toolInput.description || '';
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+
+  // Only gate when active skill is "milestone"
+  try {
+    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+    if (activeSkill !== 'milestone') return null;
+  } catch (_e) {
+    return null;
+  }
+
+  // Only gate pbr:general and pbr:planner
+  if (subagentType !== 'pbr:general' && subagentType !== 'pbr:planner') return null;
+
+  // Only gate "complete" operations
+  if (!/complete/i.test(description)) return null;
+
+  // Read STATE.md for current phase
+  const stateFile = path.join(planningDir, 'STATE.md');
+  let currentPhase;
+  try {
+    const state = fs.readFileSync(stateFile, 'utf8');
+    const fmMatch = state.match(/current_phase:\s*(\d+)/);
+    if (fmMatch) {
+      currentPhase = parseInt(fmMatch[1], 10);
+    } else {
+      const bodyMatch = state.match(/Phase:\s*(\d+)/);
+      if (bodyMatch) currentPhase = parseInt(bodyMatch[1], 10);
+    }
+    if (!currentPhase) return null;
+  } catch (_e) {
+    return null;
+  }
+
+  // Read ROADMAP.md and find the milestone containing the current phase
+  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
+  try {
+    const roadmap = fs.readFileSync(roadmapFile, 'utf8');
+
+    // Split into milestone sections
+    const milestoneSections = roadmap.split(/^## Milestone:/m).slice(1);
+
+    for (const section of milestoneSections) {
+      // Parse phase numbers from table rows
+      const phaseNumbers = [];
+      const tableRowRegex = /^\|\s*(\d+)\s*\|/gm;
+      let match;
+      while ((match = tableRowRegex.exec(section)) !== null) {
+        phaseNumbers.push(parseInt(match[1], 10));
+      }
+
+      // Check if current phase is in this milestone
+      if (!phaseNumbers.includes(currentPhase)) continue;
+
+      // Found the right milestone — check all phases have VERIFICATION.md
+      const phasesDir = path.join(planningDir, 'phases');
+      if (!fs.existsSync(phasesDir)) return null;
+
+      for (const phaseNum of phaseNumbers) {
+        const paddedPhase = String(phaseNum).padStart(2, '0');
+        const pDirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + '-'));
+        if (pDirs.length === 0) {
+          return {
+            block: true,
+            reason: `Milestone complete gate: Phase ${paddedPhase} directory not found. All milestone phases must be verified before completing milestone.`
+          };
+        }
+        const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
+        if (!hasVerification) {
+          return {
+            block: true,
+            reason: `Milestone complete gate: Phase ${paddedPhase} (${pDirs[0]}) lacks VERIFICATION.md. All milestone phases must be verified before completing milestone.`
+          };
+        }
+      }
+
+      // All phases verified
+      return null;
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Blocking check: when the active skill is "build" and an executor is being
+ * spawned, verify that dependent phases (from ROADMAP.md) have VERIFICATION.md.
+ * Returns { block: true, reason: "..." } if blocked, or null if OK.
+ */
+function checkBuildDependencyGate(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  // Only gate pbr:executor
+  if (subagentType !== 'pbr:executor') 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 "build"
+  try {
+    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+    if (activeSkill !== 'build') return null;
+  } catch (_e) {
+    return null;
+  }
+
+  // Read STATE.md for current phase
+  const stateFile = path.join(planningDir, 'STATE.md');
+  let currentPhase;
+  try {
+    const state = fs.readFileSync(stateFile, 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)/);
+    if (!phaseMatch) return null;
+    currentPhase = parseInt(phaseMatch[1], 10);
+  } catch (_e) {
+    return null;
+  }
+
+  // Read ROADMAP.md, find current phase section, check dependencies
+  const roadmapFile = path.join(planningDir, 'ROADMAP.md');
+  try {
+    const roadmap = fs.readFileSync(roadmapFile, 'utf8');
+
+    // Find ### Phase N: section
+    const phaseRegex = new RegExp(`### Phase ${currentPhase}:[\\s\\S]*?(?=### Phase \\d|$)`);
+    const phaseSection = roadmap.match(phaseRegex);
+    if (!phaseSection) return null;
+
+    // Look for **Depends on:** line
+    const depMatch = phaseSection[0].match(/\*\*Depends on:\*\*\s*(.*)/);
+    if (!depMatch) return null;
+
+    const depLine = depMatch[1].trim();
+    if (!depLine || /^none$/i.test(depLine)) return null;
+
+    // Parse phase numbers from "Phase 1", "Phase 1, Phase 2", etc.
+    const depPhases = [];
+    const depRegex = /Phase\s+(\d+)/gi;
+    let match;
+    while ((match = depRegex.exec(depLine)) !== null) {
+      depPhases.push(parseInt(match[1], 10));
+    }
+
+    if (depPhases.length === 0) return null;
+
+    // Check each dependent phase has VERIFICATION.md
+    const phasesDir = path.join(planningDir, 'phases');
+    if (!fs.existsSync(phasesDir)) return null;
+
+    for (const depPhase of depPhases) {
+      const paddedPhase = String(depPhase).padStart(2, '0');
+      const pDirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(paddedPhase + '-'));
+      if (pDirs.length === 0) {
+        return {
+          block: true,
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+        };
+      }
+      const hasVerification = fs.existsSync(path.join(phasesDir, pDirs[0], 'VERIFICATION.md'));
+      if (!hasVerification) {
+        return {
+          block: true,
+          reason: `Build dependency gate: Dependent phase ${paddedPhase} lacks VERIFICATION.md. Run /pbr:review on dependent phases first.`
+        };
+      }
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Advisory check: when active skill is "build" and an executor is being
+ * spawned, warn if .checkpoint-manifest.json is missing in the phase dir.
+ * Returns a warning string or null.
+ */
+function checkCheckpointManifest(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  if (subagentType !== 'pbr:executor') return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+
+  try {
+    const activeSkill = fs.readFileSync(activeSkillFile, 'utf8').trim();
+    if (activeSkill !== 'build') return null;
+  } catch (_e) {
+    return null;
+  }
+
+  // Find current phase dir
+  const stateFile = path.join(planningDir, 'STATE.md');
+  try {
+    const state = fs.readFileSync(stateFile, 'utf8');
+    const phaseMatch = state.match(/Phase:\s*(\d+)\s+of\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 manifestFile = path.join(phaseDir, '.checkpoint-manifest.json');
+    if (!fs.existsSync(manifestFile)) {
+      return 'Build advisory: .checkpoint-manifest.json not found in phase directory. The build skill should write this before spawning executors.';
+    }
+  } catch (_e) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Advisory check: when any pbr:* agent is being spawned, warn if
+ * .planning/.active-skill doesn't exist. Without this file, all
+ * skill-specific enforcement is silently disabled.
+ * Returns a warning string or null.
+ */
+function checkActiveSkillIntegrity(data) {
+  const toolInput = data.tool_input || {};
+  const subagentType = toolInput.subagent_type || '';
+
+  if (typeof subagentType !== 'string' || !subagentType.startsWith('pbr:')) return null;
+
+  const cwd = process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only check if .planning/ exists (PBR project)
+  if (!fs.existsSync(planningDir)) return null;
+
+  const activeSkillFile = path.join(planningDir, '.active-skill');
+  if (!fs.existsSync(activeSkillFile)) {
+    return 'Active-skill integrity: .planning/.active-skill not found. Skill-specific enforcement is disabled. The invoking skill should write this file.';
+  }
+
+  return null;
+}
+
 function main() {
   let input = '';
 
@@ -285,6 +663,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) {
@@ -297,8 +687,48 @@ function main() {
         return;
       }
 
+      // Blocking gate: review verifier needs SUMMARY.md
+      const reviewVerifierGate = checkReviewVerifierGate(data);
+      if (reviewVerifierGate && reviewVerifierGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: reviewVerifierGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: reviewVerifierGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: milestone complete needs all phases verified
+      const milestoneGate = checkMilestoneCompleteGate(data);
+      if (milestoneGate && milestoneGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: milestoneGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: milestoneGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
+      // Blocking gate: build dependency check
+      const buildDepGate = checkBuildDependencyGate(data);
+      if (buildDepGate && buildDepGate.block) {
+        logHook('validate-task', 'PreToolUse', 'blocked', { reason: buildDepGate.reason });
+        process.stdout.write(JSON.stringify({
+          decision: 'block',
+          reason: buildDepGate.reason
+        }));
+        process.exit(2);
+        return;
+      }
+
       // Advisory warnings
       const warnings = checkTask(data);
+      const manifestWarning = checkCheckpointManifest(data);
+      if (manifestWarning) warnings.push(manifestWarning);
+      const activeSkillWarning = checkActiveSkillIntegrity(data);
+      if (activeSkillWarning) warnings.push(activeSkillWarning);
 
       if (warnings.length > 0) {
         for (const warning of warnings) {
@@ -317,5 +747,5 @@ function main() {
   });
 }
 
-module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+module.exports = { checkTask, checkQuickExecutorGate, checkBuildExecutorGate, checkPlanExecutorGate, checkReviewPlannerGate, checkReviewVerifierGate, checkMilestoneCompleteGate, checkBuildDependencyGate, checkCheckpointManifest, checkActiveSkillIntegrity, 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