scrumrun 2.7.5 → 2.7.7

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.7.7 - 2026-08-24
+
+### Added
+
+- **Error index.** `sc knowledge errors --show` renders `.scrumrun/errors.md` — a derived index grouping `type: fix` Tasks into Open and Resolved (with branch), so reported bugs have a dedicated project log. `sc plan task --list --type <type>` now filters Tasks by type (e.g. `--type fix`).
+
+## 2.7.6 - 2026-08-24
+
+### Added
+
+- **Branch tracking on artifacts.** Task, Feature, Sprint, and Run artifacts now record the active git branch in a `branch` frontmatter field at creation time (`null` outside a git repo). `sc plan task --list` and the generated `map.md` show the branch, giving a human-readable "which branch did this work originate from" reference index to complement the exact commit SHA already captured in each Run's workspace baseline.
+
 ## 2.7.5 - 2026-08-22
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 ScrumRun gives an agent a small command surface and a precise project memory: what should be done, how each attempt happened, which decisions constrain the code, and why the architecture exists in its current form.
 
-**Package:** `2.7.5` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.7.7` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 **New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 

package/bin/scrumrun.js

@@ -31,7 +31,7 @@ const { ARTIFACT_TYPES, ArtifactRepository } = require(path.join(root, "lib", "v
 const { aliases: COMMAND_ALIASES, resolveAlias, resolveRoute } = require(path.join(root, "lib", "commands", "manifest"));
 const { renderCommandHelp, renderCompatibilityPrompt, renderRootPrompt } = require(path.join(root, "lib", "commands", "render"));
 const { planRequest } = require(path.join(root, "lib", "runtime", "request-engine"));
-const { addPlanArtifact, approveRequest, nextBacklogTask, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { addPlanArtifact, approveRequest, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
 const { authorizeMutation, recordMutation, satisfyGuardrail } = require(path.join(root, "lib", "runtime", "mutation-gateway"));
 const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "review-service"));
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
@@ -1378,6 +1378,11 @@ function runSemanticContext(subject, args) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (subject === "errors") {
+    const report = refreshErrors(path.join(process.cwd(), ".scrumrun"));
+    console.log(report.content);
+    return;
+  }
   if (subject === "map") {
     if (action === "--build") {
       const built = rebuildIndex(process.cwd());
@@ -1537,7 +1542,13 @@ function executeRootRoute(route) {
   if (noun === "plan" && ["task", "run", "feature", "sprint"].includes(subject) && ["--list", "--show"].includes(routeArgs[0])) {
     const repository = new ArtifactRepository(projectFile());
     if (routeArgs[0] === "--list") {
-      const artifacts = repository.list(subject).map((artifact) => `${artifact.record.id} | ${artifact.record.status} | ${((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id}`);
+      const typeFilter = optionValue(routeArgs, "--type");
+      const listed = repository.list(subject).filter((artifact) => !typeFilter || artifact.record.type === typeFilter);
+      const artifacts = listed.map((artifact) => {
+        const title = ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id;
+        const branch = artifact.record.branch ? ` [${artifact.record.branch}]` : "";
+        return `${artifact.record.id} | ${artifact.record.status} | ${title}${branch}`;
+      });
       console.log(artifacts.length ? artifacts.join("\n") : `No ${subject} artifacts.`);
     } else {
       const artifact = repository.read(subject, routeArgs[1]);
@@ -1597,7 +1608,7 @@ function executeRootRoute(route) {
     }
   }
   if (noun === "knowledge" && ["fact", "decision", "insight", "dossier"].includes(subject) && v2Project()) return runV2Memory(subject, routeArgs);
-  if (noun === "knowledge" && ["context", "map", "study"].includes(subject) && v2Project()) return runSemanticContext(subject, routeArgs);
+  if (noun === "knowledge" && ["context", "map", "study", "errors"].includes(subject) && v2Project()) return runSemanticContext(subject, routeArgs);
   if (noun === "knowledge" && subject === "decision") return runDecisions(routeArgs);
   if (noun === "knowledge" && subject === "fact") return runKnow(routeArgs);
   if (noun === "knowledge" && subject === "vault") return runVault(routeArgs);

package/lib/commands/manifest.js

@@ -38,6 +38,7 @@ const nouns = Object.freeze({
       dossier: ["--add [--title] [--content] [--evidence] [--relation] [--subject] [--source] [--source-id] [--valid-from] [--valid-until] [--review-trigger]", "--list [--include-inactive]", "--show", "--refresh [--evidence] [--note]", "--stale [--note]", "--deprecate [--note]", "--archive [--note]"],
       context: ["--build", "--update", "--show", "--clear"],
       map: ["--build", "--show"],
+      errors: ["--show"],
       study: ["<focus>"],
       vault: ["--add", "--list", "--show", "--remove", "--path"]
     }

package/lib/memory/index.js

@@ -12,7 +12,7 @@ const { containsSecret } = require("../security/secrets");
 const { canonicalWatchSnapshot, fileWatchSnapshot } = require("../runtime/canonical-snapshot");
 
 const CACHE_RELATIVE = path.join(".cache", "semantic-index.sqlite");
-const INDEX_SCHEMA_VERSION = 4;
+const INDEX_SCHEMA_VERSION = 5;
 const INACTIVE = new Set(["rejected", "invalidated", "deprecated", "archived"]);
 const SEARCH_BACKENDS = new Set(["auto", "fts5", "like"]);
 const MAX_SEARCH_TOKENS = 32;
@@ -124,6 +124,7 @@ function createSchema(database, { searchBackend = "auto" } = {}) {
       path TEXT NOT NULL UNIQUE,
       hash TEXT NOT NULL,
       content TEXT NOT NULL,
+      branch TEXT,
       valid_from TEXT,
       valid_until TEXT,
       last_verified_commit TEXT,
@@ -380,7 +381,7 @@ function rebuildIndex(projectRoot, { searchBackend = "auto" } = {}) {
   try {
     database = new DatabaseSync(temp);
     selectedSearchBackend = createSchema(database, { searchBackend });
-    const insertArtifact = database.prepare("INSERT INTO artifacts(id, kind, status, title, path, hash, content, valid_from, valid_until, last_verified_commit, review_trigger, search_text, active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+    const insertArtifact = database.prepare("INSERT INTO artifacts(id, kind, status, title, path, hash, content, branch, valid_from, valid_until, last_verified_commit, review_trigger, search_text, active) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
     const insertFts = selectedSearchBackend === "fts5"
       ? database.prepare("INSERT INTO artifacts_fts(id, title, content) VALUES (?, ?, ?)")
       : null;
@@ -400,6 +401,7 @@ function rebuildIndex(projectRoot, { searchBackend = "auto" } = {}) {
           artifact.path,
           sha256(artifact.content),
           artifact.content,
+          artifact.record.branch || null,
           artifact.record.valid_from || null,
           artifact.record.valid_until || null,
           artifact.record.last_verified_commit || null,
@@ -690,7 +692,7 @@ function graphIndex(projectRoot, { rebuild = true } = {}) {
   else if (status.stale) throw new Error("Semantic index is missing or stale; rebuild it first.");
   const database = new DatabaseSync(indexPath(projectRoot), { readOnly: true });
   try {
-    const artifacts = database.prepare("SELECT id, kind, status, title, path, 'artifact' AS node_type FROM artifacts ORDER BY id").all();
+    const artifacts = database.prepare("SELECT id, kind, status, title, path, branch, 'artifact' AS node_type FROM artifacts ORDER BY id").all();
     const code = database.prepare("SELECT id, kind, status, name AS title, path, 'code' AS node_type, fingerprint, remapped_from FROM code_nodes ORDER BY id").all();
     return {
       nodes: [...artifacts, ...code],
@@ -725,7 +727,10 @@ function writeMap(projectRoot, { nodeLimit = 200, edgeLimit = 400 } = {}) {
     "",
     "## Nodes",
     "",
-    ...(nodes.length ? nodes.map((node) => `- ${node.id} | ${node.node_type} | ${node.kind} | ${node.status} | ${node.title} | ${node.path}`) : ["- None."]),
+    ...(nodes.length ? nodes.map((node) => {
+      const branch = node.branch ? ` | branch:${node.branch}` : "";
+      return `- ${node.id} | ${node.node_type} | ${node.kind} | ${node.status} | ${node.title} | ${node.path}${branch}`;
+    }) : ["- None."]),
     ...(graph.nodes.length > nodes.length ? [`- … ${graph.nodes.length - nodes.length} more nodes in the semantic index.`] : []),
     "",
     "## Relations",

package/lib/runtime/briefing.js

@@ -101,4 +101,40 @@ ${backlogTasks.length ? backlogTasks.join("\n") : "- No backlog Tasks."}
   return { content, sourceFingerprint, watchFingerprint: watch.fingerprint, sourceFiles: watch.files };
 }
 
-module.exports = { TERMINAL, generateBriefing };
+function generateErrorsReport(scrumDir, repository) {
+  const repo = repository || new ArtifactRepository(scrumDir);
+  const snapshot = artifactSnapshot(scrumDir);
+  const sourceFingerprint = canonicalFingerprint(scrumDir, snapshot.hashes);
+  const fixes = repo.list("task")
+    .filter((artifact) => artifact.record && !artifact.errors.length && artifact.record.type === "fix")
+    .sort((left, right) => left.record.id.localeCompare(right.record.id));
+  const open = fixes.filter((artifact) => artifact.record.status !== "completed");
+  const resolved = fixes.filter((artifact) => artifact.record.status === "completed");
+  const line = (artifact) => {
+    const record = artifact.record;
+    const title = ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || record.id;
+    return `- ${record.id} | ${record.status} | ${title}${record.branch ? ` [${record.branch}]` : ""}`;
+  };
+  const content = `# ScrumRun Error Index
+
+Projection schema: 1
+Generated: ${new Date().toISOString()}
+Source fingerprint: ${sourceFingerprint}
+Authority: none; rebuild from canonical artifacts.
+
+## Open
+
+${open.length ? open.map(line).join("\n") : "- None."}
+
+## Resolved
+
+${resolved.length ? resolved.map(line).join("\n") : "- None."}
+
+## Summary
+
+- Fix Tasks: ${fixes.length} (${open.length} open, ${resolved.length} resolved)
+`;
+  return { content, sourceFingerprint };
+}
+
+module.exports = { TERMINAL, generateBriefing, generateErrorsReport };

package/lib/runtime/orchestrator.js

@@ -19,9 +19,10 @@ const { agentIdentity, evaluatePolicy } = require("./policy-engine");
 const { artifactSnapshot, canonicalFingerprint, canonicalWatchSnapshot } = require("./canonical-snapshot");
 const { decodeApproval } = require("./request-engine");
 const { containsSecret } = require("../security/secrets");
+const { currentBranch } = require("./workspace-state");
 const { extractLearningCandidates } = require("../code-intel/learning");
 const { appendRunEvent, appendTechnicalSummary, createRunBody, instant } = require("./run-ledger");
-const { generateBriefing } = require("./briefing");
+const { generateBriefing, generateErrorsReport } = require("./briefing");
 const { assertCanonicalWrite, policyState, prepareCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
 const { recoverPendingTransactions, runKernelTransaction } = require("../v2/transaction");
 
@@ -64,6 +65,13 @@ function refreshState(scrumDir) {
   return projection;
 }
 
+function refreshErrors(scrumDir) {
+  const repository = new ArtifactRepository(scrumDir);
+  const report = generateErrorsReport(scrumDir, repository);
+  atomicWrite(path.join(scrumDir, "errors.md"), report.content);
+  return report;
+}
+
 function stateIsStale(scrumDir) {
   const content = fs.existsSync(path.join(scrumDir, "state.md")) ? fs.readFileSync(path.join(scrumDir, "state.md"), "utf8") : "";
   const stored = (content.match(/^Source fingerprint:\s*([a-f0-9]{64})$/m) || [])[1];
@@ -103,6 +111,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
   const created = date();
   const enforceablePolicy = policyState(projectRoot);
   const baseline = publicWorkspace(workspace);
+  const branch = currentBranch(projectRoot);
   const taskId = nextId(repository, "task");
   const runId = nextId(repository, "run");
   const task = {
@@ -115,6 +124,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     method: METHOD_VERSION,
     feature: null,
     sprint: null,
+    branch,
     assignee: agentIdentity(scrumDir) || "agent",
     approval_id: approvalId,
     context_fingerprint: payload.fingerprint,
@@ -129,6 +139,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     method: METHOD_VERSION,
     task: taskId,
     sprint: null,
+    branch,
     attempt: 1,
     ledger: 1,
     guardrails: 1,
@@ -304,6 +315,7 @@ function retryTaskUnlocked(projectRoot, taskId, { note = "Retry explicitly appro
     method: METHOD_VERSION,
     task: taskId,
     sprint: taskArtifact.record.sprint || null,
+    branch: currentBranch(projectRoot),
     attempt: attempts.length ? Math.max(...attempts) + 1 : 1,
     ledger: 1,
     guardrails: 1,
@@ -374,6 +386,7 @@ function startBacklogTaskUnlocked(projectRoot, taskId, { note = "Backlog Task st
     method: METHOD_VERSION,
     task: taskId,
     sprint: taskArtifact.record.sprint || null,
+    branch: currentBranch(projectRoot),
     attempt: 1,
     ledger: 1,
     guardrails: 1,
@@ -504,7 +517,8 @@ function addPlanArtifactUnlocked(projectRoot, kind, label, { type = null, status
     status: chosenStatus,
     created,
     updated: created,
-    method: METHOD_VERSION
+    method: METHOD_VERSION,
+    branch: currentBranch(projectRoot)
   };
   if (kind === "task") {
     record.type = chosenType;
@@ -528,4 +542,4 @@ function addPlanArtifact(projectRoot, kind, label, options = {}) {
   return withArtifactLock(scrumDir, "create", () => addPlanArtifactUnlocked(projectRoot, kind, label, options));
 }
 
-module.exports = { addPlanArtifact, approveRequest, nextBacklogTask, nextId, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };
+module.exports = { addPlanArtifact, approveRequest, nextBacklogTask, nextId, refreshErrors, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };

package/lib/runtime/workspace-state.js

@@ -110,6 +110,16 @@ function workspaceState(projectRoot) {
   return { ...state, fingerprint: sha256(stable(canonical)) };
 }
 
+function currentBranch(projectRoot) {
+  try {
+    const branch = gitOutput(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]).toString("utf8").trim();
+    if (!branch || branch === "HEAD") return null;
+    return branch;
+  } catch {
+    return null;
+  }
+}
+
 function changesBetween(before, after) {
   if (!before || !after || before.mode !== after.mode || before.head !== after.head) throw new Error("Workspace baseline mode or Git HEAD changed during the Run.");
   const left = new Map(before.files.map((item) => [item.path, item]));
@@ -139,6 +149,7 @@ function pathAuthorized(relative, allowed) {
 
 module.exports = {
   changesBetween,
+  currentBranch,
   normalizedRelative,
   pathAuthorized,
   stable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.7.5",
+  "version": "2.7.7",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/types/index.d.ts

@@ -392,6 +392,7 @@ export function retryTask(projectRoot: string, taskId: string, options?: { note?
 export function startBacklogTask(projectRoot: string, taskId: string, options?: { note?: string; failurePoint?: string | null; interruptPoint?: string | null }): { run: ArtifactRecord; task: ArtifactRecord; content: string; recovered?: unknown[] };
 export function nextBacklogTask(repository: ArtifactRepository): ArtifactRecord | null;
 export function refreshState(scrumDir: string): StateProjection;
+export function refreshErrors(scrumDir: string): { content: string; sourceFingerprint: string };
 export function renderState(repository: ArtifactRepository): string;
 export function stateFingerprint(repository: ArtifactRepository): string;
 export function stateIsStale(scrumDir: string): boolean;