@sienklogic/plan-build-run 2.56.3 → 2.58.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.58.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.57.0...plan-build-run-v2.58.0) (2026-03-05)
+
+
+### Features
+
+* **hook-events:** add native agent_type support, continue:false halt signals, and InstructionsLoaded hook ([8f09dcb](https://github.com/SienkLogic/plan-build-run/commit/8f09dcbad39c4f0e19d7f26f4f5fa694bc2b5f2e))
+
+
+### Bug Fixes
+
+* **hook-events:** add InstructionsLoaded to hooks schema and valid events list ([cd6601c](https://github.com/SienkLogic/plan-build-run/commit/cd6601c66ac806e1c884e86b829596001fc81c3f))
+* **hook-events:** fix sessionLoad bug in halt conditions, add missing agent_type and halt tests ([aab8ec6](https://github.com/SienkLogic/plan-build-run/commit/aab8ec6b9346a66fcb6e9a1f038ec5bef4c8cf6f))
+
+## [2.57.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.3...plan-build-run-v2.57.0) (2026-03-05)
+
+
+### Features
+
+* **quick-021:** add heuristic-first classification for file intent and commits ([a70167e](https://github.com/SienkLogic/plan-build-run/commit/a70167e0d9c7449339c056ccd44d7be819ae6ce3))
+
 ## [2.56.3](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.2...plan-build-run-v2.56.3) (2026-03-03)
 
 

package/package.json

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

package/plugins/codex-pbr/references/model-profiles.md

@@ -4,6 +4,24 @@ How Plan-Build-Run maps agents to models and how to configure model selection.
 
 ---
 
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
 ## Agent-to-Model Mapping
 
 Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.

package/plugins/codex-pbr/references/model-selection.md

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

package/plugins/codex-pbr/skills/begin/SKILL.md

@@ -132,6 +132,7 @@ Use AskUserQuestion:
       description: "Walk through model selection, features, and preferences step by step."
 
 **If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
 - Write `.planning/config.json` immediately using the default config below (no further questions):
   ```json
   {
@@ -213,6 +214,8 @@ Use AskUserQuestion:
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

package/plugins/codex-pbr/skills/setup/SKILL.md

@@ -57,6 +57,8 @@ Stop. Do not proceed further.
 
 ## Step 2: Model Selection
 
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

package/plugins/copilot-pbr/hooks/hooks.json

@@ -15,6 +15,19 @@
         ]
       }
     ],
+    "instructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" instructions-loaded.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') instructions-loaded.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
     "postToolUse": [
       {
         "matcher": "Write|Edit",

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.3",
+  "version": "2.58.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/references/model-profiles.md

@@ -4,6 +4,24 @@ How Plan-Build-Run maps agents to models and how to configure model selection.
 
 ---
 
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
 ## Agent-to-Model Mapping
 
 Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.

package/plugins/copilot-pbr/references/model-selection.md

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

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

@@ -132,6 +132,7 @@ Use AskUserQuestion:
       description: "Walk through model selection, features, and preferences step by step."
 
 **If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
 - Write `.planning/config.json` immediately using the default config below (no further questions):
   ```json
   {
@@ -213,6 +214,8 @@ Use AskUserQuestion:
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

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

@@ -57,6 +57,8 @@ Stop. Do not proceed further.
 
 ## Step 2: Model Selection
 
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.3",
+  "version": "2.58.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/hooks/hooks.json

@@ -13,6 +13,17 @@
         ]
       }
     ],
+    "InstructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" instructions-loaded.js",
+            "statusMessage": "Detecting instruction reload..."
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/plugins/cursor-pbr/references/model-profiles.md

@@ -4,6 +4,24 @@ How Plan-Build-Run maps agents to models and how to configure model selection.
 
 ---
 
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
 ## Agent-to-Model Mapping
 
 Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.

package/plugins/cursor-pbr/references/model-selection.md

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

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

@@ -132,6 +132,7 @@ Use AskUserQuestion:
       description: "Walk through model selection, features, and preferences step by step."
 
 **If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
 - Write `.planning/config.json` immediately using the default config below (no further questions):
   ```json
   {
@@ -213,6 +214,8 @@ Use AskUserQuestion:
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

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

@@ -57,6 +57,8 @@ Stop. Do not proceed further.
 
 ## Step 2: Model Selection
 
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.56.3",
+  "version": "2.58.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/hooks/hooks.json

@@ -18,6 +18,17 @@
         ]
       }
     ],
+    "InstructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" instructions-loaded.js",
+            "statusMessage": "Detecting instruction reload..."
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/plugins/pbr/references/model-profiles.md

@@ -4,6 +4,24 @@ How Plan-Build-Run maps agents to models and how to configure model selection.
 
 ---
 
+## Session Model (Orchestrator)
+
+The orchestrator is your main Claude Code session -- it reads skills, manages state, and routes work to agents. Its model is whatever you selected in Claude Code (not controlled by PBR's `config.json`).
+
+**Cost impact:** The orchestrator accounts for roughly 40% of total session cost. Agents set to `inherit` (planner, executor, debugger, general in the `balanced` profile) also use this model. Switching your session from Opus to Sonnet reduces cost for both the orchestrator and all `inherit` agents.
+
+**Recommendations:**
+
+| Goal | Session Model | Config Adjustment |
+|------|---------------|-------------------|
+| Maximum quality | Opus | None needed -- `inherit` agents get Opus |
+| Balanced cost/quality | Sonnet | None needed -- `inherit` agents get Sonnet, which handles most tasks well |
+| Cheap orchestration, Opus agents | Sonnet | Set `planner: "opus"`, `executor: "opus"`, `debugger: "opus"` to override inherit |
+
+Sonnet 4.6 handles orchestration tasks (state reading, routing decisions, context assembly) effectively. Reserve Opus for agents doing complex reasoning, architecture, or novel code generation.
+
+---
+
 ## Agent-to-Model Mapping
 
 Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.

package/plugins/pbr/references/model-selection.md

@@ -14,7 +14,7 @@ Plan-Build-Run uses adaptive model selection to balance cost and capability.
 |-----------|-------|-----------|
 | simple | haiku | Fast, cheap — sufficient for mechanical changes |
 | medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
+| complex | inherit | Uses session model — see `model-profiles.md` Session Model section for cost implications |
 
 ## Override Mechanisms
 

package/plugins/pbr/scripts/check-subagent-output.js

@@ -421,7 +421,7 @@ async function main() {
   }
 
   // Extract agent type from the Task completion data
-  const agentType = data.tool_input?.subagent_type || data.subagent_type || '';
+  const agentType = data.agent_type || data.tool_input?.subagent_type || data.subagent_type || '';
 
   // Only check known Plan-Build-Run agent types
   const outputSpec = AGENT_OUTPUTS[agentType];

package/plugins/pbr/scripts/hooks-schema.json

@@ -10,6 +10,7 @@
       "type": "object",
       "properties": {
         "SessionStart": { "$ref": "#/definitions/hookEntryList" },
+        "InstructionsLoaded": { "$ref": "#/definitions/hookEntryList" },
         "PreToolUse": { "$ref": "#/definitions/hookEntryList" },
         "PostToolUse": { "$ref": "#/definitions/hookEntryList" },
         "PostToolUseFailure": { "$ref": "#/definitions/hookEntryList" },

package/plugins/pbr/scripts/instructions-loaded.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * InstructionsLoaded hook: Lightweight PBR state reminder after CLAUDE.md loads.
+ *
+ * Fires each time Claude Code loads CLAUDE.md or .claude/rules/*.md files.
+ * For PBR projects: injects a brief reminder that PBR workflow is active.
+ * Debounces mid-session re-fires using .session.json load timestamp.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) { /* empty or non-JSON stdin */ }
+  return {};
+}
+
+function main() {
+  const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
+
+  // Only relevant for PBR projects
+  if (!fs.existsSync(planningDir)) {
+    process.exit(0);
+  }
+
+  // Debounce: only emit additionalContext on first fire per session.
+  // .session.json is written by progress-tracker.js at SessionStart.
+  // If it exists with a sessionStart timestamp, this is a mid-session reload.
+  let isMidSession = false;
+  try {
+    const sessionFile = path.join(planningDir, '.session.json');
+    if (fs.existsSync(sessionFile)) {
+      const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+      if (session.sessionStart) {
+        isMidSession = true;
+      }
+    }
+  } catch (_e) { /* non-fatal */ }
+
+  logHook('instructions-loaded', 'InstructionsLoaded', isMidSession ? 'mid-session-reload' : 'initial-load', {
+    instructions_file: data.instructions_file || null
+  });
+
+  // Mid-session: note that instructions reloaded (CLAUDE.md may have changed)
+  if (isMidSession) {
+    process.stdout.write(JSON.stringify({
+      additionalContext: '[Plan-Build-Run] Project CLAUDE.md was reloaded mid-session. If PBR workflow rules changed, current skill invocation may be affected. Check .planning/STATE.md for current position.'
+    }));
+    process.exit(0);
+  }
+
+  // Initial load: no additionalContext needed — progress-tracker.js already
+  // injected full state at SessionStart. Avoid double-injection.
+  process.exit(0);
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main };

package/plugins/pbr/scripts/lib/gates/helpers.js

@@ -15,6 +15,13 @@ const path = require('path');
  * @returns {string|null}
  */
 function readActiveSkill(planningDir) {
+  // Check .session.json first (consistent with check-subagent-output.js and log-subagent.js)
+  try {
+    const { sessionLoad } = require('../../pbr-tools');
+    const session = sessionLoad(planningDir);
+    if (session && session.activeSkill) return session.activeSkill;
+  } catch (_e) { /* pbr-tools unavailable */ }
+  // Fall back to legacy .active-skill file
   try {
     return fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim();
   } catch (_e) {

package/plugins/pbr/scripts/local-llm/operations/classify-commit.js

@@ -6,6 +6,52 @@ const { route } = require('../router');
 
 const VALID_CLASSIFICATIONS = ['correct', 'type_mismatch', 'vague'];
 
+const CONVENTIONAL_COMMIT_RE = /^(feat|fix|refactor|test|docs|chore|wip|perf|ci|build|revert)(\(.*?\))?!?:/;
+
+const TEST_FILE_RE = /(?:^|[/\\])tests[/\\]|\.test\.[jt]sx?$|\.spec\.[jt]sx?$/;
+const MARKDOWN_RE = /\.mdx?$/i;
+const CONFIG_TOOLING_RE = /\.(?:json|ya?ml|toml|ini|env|lock)$|(?:^|[/\\])(?:\.github|\.husky|scripts)[/\\]|(?:Makefile|Dockerfile|\.eslintrc|\.prettierrc|babel\.config|jest\.config|tsconfig|webpack\.config|rollup\.config)/i;
+
+/**
+ * Heuristic-first classifier for git commit messages.
+ * Runs before the LLM path and returns early for unambiguous cases.
+ *
+ * @param {string} commitMessage - the commit message to classify
+ * @param {string[]} [stagedFiles] - optional list of staged file paths
+ * @returns {{ classification: string, confidence: number }|null} result or null (fall through to LLM)
+ */
+function classifyCommitHeuristic(commitMessage, stagedFiles) {
+  const match = CONVENTIONAL_COMMIT_RE.exec(commitMessage);
+  if (!match) return null;
+
+  const type = match[1];
+  const files = stagedFiles && stagedFiles.length > 0 ? stagedFiles : [];
+
+  // Check for "fix" type but description implies addition
+  const descriptionPart = commitMessage.slice(match[0].length).trim();
+  if (type === 'fix' && /^(?:add|adds|adding|new\b)/i.test(descriptionPart)) {
+    return { classification: 'type_mismatch', confidence: 0.9 };
+  }
+
+  // Type-to-file alignment checks (only when staged files are known)
+  if (files.length > 0) {
+    if (type === 'test' && files.every(f => TEST_FILE_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+
+    if (type === 'docs' && files.every(f => MARKDOWN_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+
+    if ((type === 'chore' || type === 'ci' || type === 'build') && files.every(f => CONFIG_TOOLING_RE.test(f))) {
+      return { classification: 'correct', confidence: 1.0 };
+    }
+  }
+
+  // Type parsed cleanly — most conventional commits are typed correctly
+  return { classification: 'correct', confidence: 0.8 };
+}
+
 /**
  * Classifies a git commit message for semantic correctness using the local LLM.
  * Goes beyond regex validation — checks whether the commit type matches the
@@ -22,6 +68,29 @@ async function classifyCommit(config, planningDir, commitMessage, stagedFiles, s
   if (!config.enabled || !config.features.commit_classification) return null;
   if (isDisabled('commit-classification', config.advanced.disable_after_failures)) return null;
 
+  // Heuristic-first: skip LLM for unambiguous cases
+  const heuristic = classifyCommitHeuristic(commitMessage, stagedFiles);
+  if (heuristic !== null) {
+    logMetric(planningDir, {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'commit-classification',
+      model: 'heuristic',
+      latency_ms: 0,
+      tokens_used_local: 0,
+      tokens_saved_frontier: 150,
+      result: heuristic.classification,
+      fallback_used: false,
+      confidence: heuristic.confidence
+    });
+    return {
+      classification: heuristic.classification,
+      confidence: heuristic.confidence,
+      latency_ms: 0,
+      fallback_used: false
+    };
+  }
+
   const filesContext = stagedFiles && stagedFiles.length > 0
     ? '\nStaged files: ' + stagedFiles.slice(0, 20).join(', ')
     : '';
@@ -65,4 +134,4 @@ async function classifyCommit(config, planningDir, commitMessage, stagedFiles, s
   }
 }
 
-module.exports = { classifyCommit, VALID_CLASSIFICATIONS };
+module.exports = { classifyCommit, classifyCommitHeuristic, VALID_CLASSIFICATIONS };

package/plugins/pbr/scripts/local-llm/operations/classify-file-intent.js

@@ -3,10 +3,83 @@
 const { complete, tryParseJSON, isDisabled } = require('../client');
 const { logMetric } = require('../metrics');
 const { route } = require('../router');
+const path = require('path');
 
 const VALID_FILE_TYPES = ['plan', 'state', 'code', 'test', 'config', 'docs', 'template', 'other'];
 const VALID_INTENTS = ['create', 'update', 'fix', 'refactor', 'delete'];
 
+// Normalize path separators to forward slashes for consistent pattern matching.
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Heuristic-based file classification. Runs before the LLM path and returns a
+ * result object for clear-cut cases, or null for ambiguous inputs that should
+ * fall through to the LLM.
+ *
+ * @param {string} filePath - the target file path
+ * @param {string} contentSnippet - first ~200 chars of the content being written
+ * @returns {{ file_type: string, intent: string, confidence: number }|null}
+ */
+function classifyFileIntentHeuristic(filePath, contentSnippet) {
+  const normalized = normalizePath(filePath);
+  const basename = path.basename(normalized);
+  const snippet = contentSnippet || '';
+
+  // --- Extension map (test extensions checked before generic ones) ---
+  if (/\.(test|spec)\.(js|ts|mjs|cjs)$/.test(basename)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(tmpl|ejs)$/.test(basename)) {
+    return { file_type: 'template', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(json|yaml|yml)$/.test(basename)) {
+    return { file_type: 'config', intent: 'update', confidence: 1.0 };
+  }
+  if (/\.(js|ts|mjs|cjs)$/.test(basename)) {
+    // Even if in tests/ directory the double-extension rule above already caught it,
+    // but check path pattern here too as an extra safety net.
+    if (/(?:^|\/)(?:tests?|__tests__)\//.test(normalized)) {
+      return { file_type: 'test', intent: 'update', confidence: 1.0 };
+    }
+    return { file_type: 'code', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- Path patterns (checked before .md extension so directory wins) ---
+  if (/(?:^|\/)(?:tests?|__tests__)\//.test(normalized)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+  if (/(?:^|\/)docs\//.test(normalized)) {
+    return { file_type: 'docs', intent: 'update', confidence: 1.0 };
+  }
+  if (/(?:^|\/)scripts\//.test(normalized)) {
+    return { file_type: 'code', intent: 'update', confidence: 1.0 };
+  }
+  // .planning/ special cases — STATE.md first, then general plan
+  if (/(?:^|\/)\.planning\//.test(normalized)) {
+    if (basename === 'STATE.md') {
+      return { file_type: 'state', intent: 'update', confidence: 1.0 };
+    }
+    return { file_type: 'plan', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- Content signals (apply to any extension) ---
+  const trimmed = snippet.trimStart();
+  if (/^(?:describe|test|it)\s*\(/.test(trimmed)) {
+    return { file_type: 'test', intent: 'update', confidence: 1.0 };
+  }
+
+  // --- .md extension: only classify when in a recognized path, else null ---
+  if (/\.md$/.test(basename)) {
+    // docs/ and .planning/ were already handled above; all other .md is ambiguous.
+    return null;
+  }
+
+  // Anything else is ambiguous — let the LLM decide.
+  return null;
+}
+
 /**
  * Classifies the type and intent of a Write/Edit operation using the local LLM.
  * Uses the file path and a short content snippet to determine what kind of file
@@ -25,6 +98,31 @@ async function classifyFileIntent(config, planningDir, filePath, contentSnippet,
 
   const snippet = contentSnippet.length > 800 ? contentSnippet.slice(0, 800) : contentSnippet;
 
+  // --- Heuristic fast-path: skip the LLM for deterministic cases ---
+  const heuristic = classifyFileIntentHeuristic(filePath, snippet);
+  if (heuristic !== null) {
+    logMetric(planningDir, {
+      session_id: sessionId || 'unknown',
+      timestamp: new Date().toISOString(),
+      operation: 'file-intent',
+      model: 'heuristic',
+      latency_ms: 0,
+      tokens_used_local: 0,
+      tokens_saved_frontier: 150,
+      result: heuristic.file_type + '/' + heuristic.intent,
+      fallback_used: false,
+      confidence: heuristic.confidence
+    });
+    return {
+      file_type: heuristic.file_type,
+      intent: heuristic.intent,
+      confidence: heuristic.confidence,
+      latency_ms: 0,
+      fallback_used: false
+    };
+  }
+  // --- End heuristic fast-path ---
+
   const prompt =
     'Classify this file write operation. Based on the file path and content snippet, determine: (1) file_type: plan (PLAN.md, ROADMAP.md, planning docs), state (STATE.md, status tracking), code (source code, scripts), test (test files), config (JSON/YAML config, package.json), docs (README, documentation), template (templates, EJS), other. (2) intent: create (new file), update (modify existing), fix (bug fix), refactor (restructure), delete (removing content). Respond with JSON: {"file_type": "<one of 8>", "intent": "<one of 5>", "confidence": 0.0-1.0}\n\nPath: ' +
     filePath + '\nContent snippet:\n' + snippet;
@@ -70,4 +168,4 @@ async function classifyFileIntent(config, planningDir, filePath, contentSnippet,
   }
 }
 
-module.exports = { classifyFileIntent, VALID_FILE_TYPES, VALID_INTENTS };
+module.exports = { classifyFileIntent, classifyFileIntentHeuristic, VALID_FILE_TYPES, VALID_INTENTS };

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

@@ -5,14 +5,33 @@
  *
  * Fires when a Task() sub-agent finishes (distinct from SubagentStop).
  * Logs the completion event and agent type for workflow tracking.
+ * Returns continue:false if a verifier finds critical gaps or an executor
+ * produces no SUMMARY.md — preventing the orchestrator from silently moving on.
  *
  * Non-blocking — exits 0 always.
  */
 
 const fs = require('fs');
+const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
 
+/**
+ * Read current_phase from STATE.md frontmatter.
+ * Lightweight — avoids heavy stateLoad() which parses roadmap/config too.
+ */
+function readCurrentPhase(planningDir) {
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    const content = fs.readFileSync(statePath, 'utf8');
+    const match = content.match(/^current_phase:\s*(\d+)/m);
+    return match ? match[1] : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
 function readStdin() {
   try {
     const input = fs.readFileSync(0, 'utf8').trim();
@@ -23,8 +42,68 @@ function readStdin() {
   return {};
 }
 
+/**
+ * Check whether a halt signal should be emitted after a PBR agent completes.
+ * Returns null (no halt) or { continue: false, stopReason: "..." }.
+ *
+ * @param {object} data - parsed stdin JSON from the TaskCompleted event
+ * @param {string} planningDir - absolute path to the .planning directory
+ * @returns {{ continue: false, stopReason: string }|null}
+ */
+function checkHaltConditions(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  if (!agentType) return null;
+
+  // --- Verifier: halt if VERIFICATION.md reports gaps_found or failed ---
+  if (agentType === 'pbr:verifier') {
+    try {
+      const rawPhase = readCurrentPhase(planningDir);
+      const phaseNum = rawPhase ? String(rawPhase).padStart(2, '0') : null;
+      if (phaseNum) {
+        const phasesDir = path.join(planningDir, 'phases');
+        const candidates = fs.readdirSync(phasesDir).filter(d => d.startsWith(phaseNum + '-'));
+        const target = candidates.length > 0 ? path.join(phasesDir, candidates[0], 'VERIFICATION.md') : null;
+        if (target && fs.existsSync(target)) {
+          const content = fs.readFileSync(target, 'utf8');
+          const statusMatch = content.match(/^status:\s*(.+)$/m);
+          const status = statusMatch ? statusMatch[1].trim() : null;
+          if (status === 'gaps_found' || status === 'failed') {
+            return {
+              continue: false,
+              stopReason: `Verifier found critical gaps in Phase ${phaseNum} (status: ${status}). Run /pbr:review to address gaps before continuing.`
+            };
+          }
+        }
+      }
+    } catch (_e) { /* non-fatal — fall through to normal exit */ }
+  }
+
+  // --- Executor: halt if SUMMARY.md is missing from current phase dir ---
+  if (agentType === 'pbr:executor') {
+    try {
+      const rawPhase = readCurrentPhase(planningDir);
+      const phaseNum = rawPhase ? String(rawPhase).padStart(2, '0') : null;
+      if (phaseNum) {
+        const phasesDir = path.join(planningDir, 'phases');
+        const candidates = fs.readdirSync(phasesDir).filter(d => d.startsWith(phaseNum + '-'));
+        const target = candidates.length > 0 ? path.join(phasesDir, candidates[0], 'SUMMARY.md') : null;
+        if (target && !fs.existsSync(target)) {
+          return {
+            continue: false,
+            stopReason: `Executor completed Phase ${phaseNum} but produced no SUMMARY.md. Review executor output and re-run /pbr:build.`
+          };
+        }
+      }
+    } catch (_e) { /* non-fatal */ }
+  }
+
+  return null;
+}
+
 function main() {
   const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
 
   logHook('task-completed', 'TaskCompleted', 'completed', {
     agent_type: data.agent_type || data.subagent_type || null,
@@ -38,8 +117,17 @@ function main() {
     duration_ms: data.duration_ms || null
   });
 
+  if (fs.existsSync(planningDir)) {
+    const halt = checkHaltConditions(data, planningDir);
+    if (halt) {
+      logHook('task-completed', 'TaskCompleted', 'halting', halt);
+      process.stdout.write(JSON.stringify(halt));
+      process.exit(0);
+    }
+  }
+
   process.exit(0);
 }
 
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { main };
+module.exports = { main, checkHaltConditions, readCurrentPhase };

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

@@ -133,6 +133,7 @@ Use AskUserQuestion:
       description: "Walk through model selection, features, and preferences step by step."
 
 **If user selects "Quick start":**
+- Tell the user: "Tip: Agents set to `inherit` use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See `references/model-profiles.md` for details."
 - Write `.planning/config.json` immediately using the default config below (no further questions):
   ```json
   {
@@ -214,6 +215,8 @@ Use AskUserQuestion:
 After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
 
 **3-model. Model Profile:**
+Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md`.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"

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

@@ -58,6 +58,8 @@ Stop. Do not proceed further.
 
 ## Step 2: Model Selection
 
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
+
 Use AskUserQuestion:
   question: "Which model profile should agents use?"
   header: "Models"