@sienklogic/plan-build-run 2.56.3 → 2.57.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.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.57.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.56.3",
+  "version": "2.57.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/cursor-pbr/.cursor-plugin/plugin.json

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.56.3",
+  "version": "2.57.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/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 };