scrumrun 2.7.7 → 2.7.8

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.7` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.7.8` · **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).
 
@@ -79,7 +79,7 @@ RECEIVED → CONTEXTUALIZING → POLICY → RISK → CLASSIFICATION
 
 The agent may assert the classification (`--type fix|task|feature|docs|discovery`) and attach a short technical preview (`--preview "…"`), rendered with color in the terminal before any Task exists. Nothing canonical is persisted before approval.
 
-Explicit approval atomically creates a Task and a Run. Execution then follows:
+Explicit approval atomically materializes the required plan artifacts and always creates the linked Task and Run. Feature and Sprint artifacts are created automatically when the request calls for them. Execution then follows:
 
 ```text
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED

package/lib/commands/pretty-intake.js

@@ -173,7 +173,12 @@ function pipelineDetail(stage, plan) {
   if (stage === "CLASSIFICATION") {
     return classificationLabel(plan.classification).toLowerCase();
   }
-  if (stage === "AWAITING_APPROVAL") return "";
+  if (stage === "PLANNING") {
+    return plan.proposal && plan.proposal.materialization ? `will materialize ${plan.proposal.materialization.summary}` : "";
+  }
+  if (stage === "AWAITING_APPROVAL") {
+    return plan.proposal && plan.proposal.materialization ? plan.proposal.materialization.summary : "";
+  }
   if (stage === "BLOCKED") return "policy denied — no token issued";
   return "";
 }
@@ -241,7 +246,8 @@ function renderIntake(plan) {
   } else if (plan.approvalToken) {
     const command = "scrumrun sc plan intake --approve";
     const tokenWidth = Math.max(16, width - 8);
-    lines.push(boxLine(width, `  ${paint(FG.gray, "APPROVE · copy the command below to create Task + Run")}`));
+    const materialization = plan.proposal && plan.proposal.materialization ? plan.proposal.materialization.summary : "Task + Run";
+    lines.push(boxLine(width, `  ${paint(FG.gray, `APPROVE · copy the command below to create ${materialization}`)}`));
     lines.push(boxLine(width, `  ${paint(ACID_FG, "$")} ${paint(FG.white, command)}`));
     for (const chunk of hardWrap(plan.approvalToken, tokenWidth)) {
       lines.push(boxLine(width, `    ${paint(DIM_ACID_FG, chunk)}`));
@@ -260,6 +266,7 @@ function renderIntakePlain(plan) {
   lines.push(`State: ${plan.state}`);
   lines.push(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
   if (plan.preview) lines.push(`Preview: ${plan.preview}`);
+  if (plan.proposal && plan.proposal.materialization) lines.push(`Materialization: ${plan.proposal.materialization.summary}`);
   lines.push(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
   lines.push(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
   for (const violation of plan.policy.violations || []) lines.push(`BLOCKED: ${violation}`);

package/lib/runtime/briefing.js

@@ -21,9 +21,12 @@ function generateBriefing(scrumDir, repository) {
   const activeWork = ["feature", "task", "sprint", "run", "review"]
     .flatMap((kind) => (snapshot.records[kind] || [])
       .filter((r) => r.id && !TERMINAL.has(r.status))
-      .map((r) => r.assignee && r.assignee !== "agent"
-        ? `- ${r.id} | ${r.status} | ${r.assignee} | ${r.title || r.id}`
-        : `- ${r.id} | ${r.status} | ${r.title || r.id}`))
+      .map((r) => {
+        const owner = r.assignee && r.assignee !== "agent" ? ` | ${r.assignee}` : "";
+        const links = [r.feature ? `feature:${r.feature}` : null, r.sprint ? `sprint:${r.sprint}` : null].filter(Boolean);
+        const relation = links.length ? ` | ${links.join(" · ")}` : "";
+        return `- ${r.id} | ${r.status}${owner}${relation} | ${r.title || r.id}`;
+      }))
     .slice(0, 5);
 
   const completedRuns = (snapshot.records.run || [])

package/lib/runtime/canonical-snapshot.js

@@ -31,6 +31,7 @@ function artifactSnapshot(scrumDir) {
       }
       return artifact.record ? {
         id: artifact.record.id,
+        kind: artifact.record.kind,
         status: artifact.record.status,
         title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
         task: artifact.record.task || null,

package/lib/runtime/context.js

@@ -58,6 +58,97 @@ function recentTechnicalSummaries(scrumDir, runRecords, limit = 5) {
   return summaries;
 }
 
+function latestRunSummaries(scrumDir) {
+  const repository = new ArtifactRepository(scrumDir);
+  const latestByTask = new Map();
+  for (const artifact of repository.list("run")) {
+    const record = artifact.record;
+    if (!record || record.status !== "completed" || !record.task) continue;
+    const current = latestByTask.get(record.task);
+    const currentAttempt = current ? Number(current.record.attempt) || 0 : -1;
+    const attempt = Number(record.attempt) || 0;
+    if (current && (attempt < currentAttempt || (attempt === currentAttempt && (record.updated || "") <= (current.record.updated || "")))) continue;
+    latestByTask.set(record.task, artifact);
+  }
+  return latestByTask;
+}
+
+function latestRunSummaryForTask(runByTask, taskId) {
+  const artifact = runByTask.get(taskId);
+  if (!artifact) return null;
+  const summary = extractTechnicalSummary(artifact.body);
+  return summary ? { run: artifact.record.id, summary: capped(summary, 500) } : null;
+}
+
+function relatedWork(scrumDir, artifacts, activeWork) {
+  const runByTask = latestRunSummaries(scrumDir);
+  const featureById = new Map((artifacts.records.feature || []).map((record) => [record.id, record]));
+  const sprintById = new Map((artifacts.records.sprint || []).map((record) => [record.id, record]));
+  const tasksByFeature = new Map();
+  const tasksBySprint = new Map();
+  for (const task of artifacts.records.task || []) {
+    if (task.feature) {
+      const list = tasksByFeature.get(task.feature) || [];
+      list.push(task);
+      tasksByFeature.set(task.feature, list);
+    }
+    if (task.sprint) {
+      const list = tasksBySprint.get(task.sprint) || [];
+      list.push(task);
+      tasksBySprint.set(task.sprint, list);
+    }
+  }
+  return activeWork.slice(0, 8).map((item) => {
+    const related = [];
+    if (item.kind === "task") {
+      if (item.feature && featureById.has(item.feature)) related.push({ relation: "belongs_to", id: item.feature });
+      if (item.sprint && sprintById.has(item.sprint)) related.push({ relation: "included_in", id: item.sprint });
+      const latest = latestRunSummaryForTask(runByTask, item.id);
+      return {
+        id: item.id,
+        kind: item.kind,
+        status: item.status,
+        related,
+        latestRun: latest
+      };
+    }
+    if (item.kind === "feature") {
+      const linked = tasksByFeature.get(item.id) || [];
+      for (const task of linked.slice(0, 5)) {
+        related.push({ relation: "contains", id: task.id, status: task.status });
+      }
+      const summaries = linked.map((task) => latestRunSummaryForTask(runByTask, task.id)).filter(Boolean).slice(0, 3);
+      return {
+        id: item.id,
+        kind: item.kind,
+        status: item.status,
+        related,
+        recentSummaries: summaries
+      };
+    }
+    if (item.kind === "sprint") {
+      const linked = tasksBySprint.get(item.id) || [];
+      for (const task of linked.slice(0, 5)) {
+        related.push({ relation: "groups", id: task.id, status: task.status });
+      }
+      const summaries = linked.map((task) => latestRunSummaryForTask(runByTask, task.id)).filter(Boolean).slice(0, 3);
+      return {
+        id: item.id,
+        kind: item.kind,
+        status: item.status,
+        related,
+        recentSummaries: summaries
+      };
+    }
+    return {
+      id: item.id,
+      kind: item.kind,
+      status: item.status,
+      related
+    };
+  });
+}
+
 function contextFingerprint(scrumDir, artifactHashes) {
   return canonicalFingerprint(scrumDir, artifactHashes);
 }
@@ -85,6 +176,7 @@ function buildContextPackage(projectRoot, request) {
   const activeWork = ["feature", "task", "sprint", "run"].flatMap((kind) =>
     (artifacts.records[kind] || []).filter((record) => !["completed", "failed", "cancelled"].includes(record.status))
   ).slice(0, 50);
+  const relatedWorkView = relatedWork(scrumDir, artifacts, activeWork);
   const missing = [];
   for (const relative of ["guardrails.md", "config.md", "project.md"]) {
     if (!fs.existsSync(path.join(scrumDir, relative))) missing.push(relative);
@@ -105,6 +197,7 @@ function buildContextPackage(projectRoot, request) {
     config,
     project: project || "[missing]",
     history: { recentRuns, recentSummaries },
+    relatedWork: relatedWorkView,
     decisions: { open: openDecisions },
     activeWork,
     graph: {

package/lib/runtime/orchestrator.js

@@ -17,7 +17,7 @@ const {
 const { buildContextPackage } = require("./context");
 const { agentIdentity, evaluatePolicy } = require("./policy-engine");
 const { artifactSnapshot, canonicalFingerprint, canonicalWatchSnapshot } = require("./canonical-snapshot");
-const { decodeApproval } = require("./request-engine");
+const { decodeApproval, materializeRequest } = require("./request-engine");
 const { containsSecret } = require("../security/secrets");
 const { currentBranch } = require("./workspace-state");
 const { extractLearningCandidates } = require("../code-intel/learning");
@@ -46,6 +46,20 @@ function titleFor(request) {
   return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
 }
 
+function initiativeBody(title, request, created, taskId) {
+  return `# ${title}\n\n## Purpose\n\n${request}\n\n## Linked Tasks\n\n- ${taskId} — ${title}\n\n## Exit Criteria\n\n- [ ] Define the initiative success condition before completion.\n\n## Source\n\n- ${created}: materialized automatically from approved intake.\n`;
+}
+
+function sprintBody(title, request, created, taskId) {
+  return `# ${title}\n\n## Timebox\n\n${request}\n\n## Tasks\n\n- ${taskId}\n\n## Exit Gate\n\n- [ ] Define the batch completion condition before completion.\n\n## Source\n\n- ${created}: materialized automatically from approved intake. The linked Task represents Sprint planning until the requested work is decomposed into atomic Tasks.\n`;
+}
+
+function buildTaskBody(request, classification, approvalId, fingerprint, risk, previewSection, links = {}) {
+  const featureSection = links.feature ? `\n## Feature\n\n- ${links.feature}\n` : "";
+  const sprintSection = links.sprint ? `\n## Sprint\n\n- ${links.sprint}\n` : "";
+  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n${previewSection}${featureSection}${sprintSection}\n## Classification\n\n- Type: ${classification.type}\n- Reason: ${classification.reason}\n- Risk: ${risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${fingerprint}`;
+}
+
 function stateFingerprint(repository) {
   return canonicalFingerprint(repository.scrumDir, artifactSnapshot(repository.scrumDir).hashes);
 }
@@ -112,6 +126,11 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
   const enforceablePolicy = policyState(projectRoot);
   const baseline = publicWorkspace(workspace);
   const branch = currentBranch(projectRoot);
+  const materialization = materializeRequest(payload.classification);
+  const createFeature = materialization.links.feature;
+  const createSprint = materialization.links.sprint;
+  const featureId = createFeature ? nextId(repository, "feature") : null;
+  const sprintId = createSprint ? nextId(repository, "sprint") : null;
   const taskId = nextId(repository, "task");
   const runId = nextId(repository, "run");
   const task = {
@@ -122,8 +141,8 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     created,
     updated: created,
     method: METHOD_VERSION,
-    feature: null,
-    sprint: null,
+    feature: featureId,
+    sprint: sprintId,
     branch,
     assignee: agentIdentity(scrumDir) || "agent",
     approval_id: approvalId,
@@ -138,7 +157,8 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     updated: created,
     method: METHOD_VERSION,
     task: taskId,
-    sprint: null,
+    feature: featureId,
+    sprint: sprintId,
     branch,
     attempt: 1,
     ledger: 1,
@@ -146,20 +166,56 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     workspace: 1,
     approval_id: approvalId
   };
+  const taskLinks = { feature: featureId, sprint: sprintId };
   const previewSection = payload.preview ? `\n\n## Preview\n\n${payload.preview}\n` : "";
-  const taskBody = `# ${titleFor(payload.request)}\n\n## Request\n\n${payload.request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n${previewSection}\n\n## Classification\n\n- Type: ${payload.classification.type}\n- Reason: ${payload.classification.reason}\n- Risk: ${payload.risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${payload.fingerprint}`;
+  const taskContent = buildTaskBody(payload.request, payload.classification, approvalId, payload.fingerprint, payload.risk, previewSection, taskLinks);
+  const featureRecord = featureId ? {
+    id: featureId,
+    kind: "feature",
+    status: "active",
+    created,
+    updated: created,
+    method: METHOD_VERSION,
+    branch,
+    type: "initiative"
+  } : null;
+  const featureBody = featureId ? initiativeBody(titleFor(payload.request), payload.request, created, taskId) : null;
+  const sprintRecord = sprintId ? {
+    id: sprintId,
+    kind: "sprint",
+    status: "running",
+    created,
+    updated: created,
+    method: METHOD_VERSION,
+    branch,
+    type: null,
+    feature: featureId
+  } : null;
+  const sprintBodyText = sprintId ? sprintBody(titleFor(payload.request), payload.request, created, taskId) : null;
   const runBody = createRunBody(run, {
     approvalId,
     obligations: payload.policy.obligations || [],
     policyFingerprint: enforceablePolicy.fingerprint,
     workspaceBaseline: baseline
   }).body;
+  const featurePath = featureRecord ? repository.pathFor(featureRecord) : null;
+  const sprintPath = sprintRecord ? repository.pathFor(sprintRecord) : null;
+  const taskPath = repository.pathFor(task);
+  const runPath = repository.pathFor(run);
+  const writes = [];
+  if (featureRecord) writes.push({ file: featurePath, previous: null, next: serializeArtifact(featureRecord, featureBody) });
+  if (sprintRecord) writes.push({ file: sprintPath, previous: null, next: serializeArtifact(sprintRecord, sprintBodyText) });
+  writes.push(
+    { file: taskPath, previous: null, next: serializeArtifact(task, taskContent) },
+    { file: runPath, previous: null, next: serializeArtifact(run, runBody) }
+  );
+  const failureTarget = {
+    "after-task": `after-${writes.findIndex((entry) => entry.file === taskPath) + 1}`,
+    "after-run": `after-${writes.findIndex((entry) => entry.file === runPath) + 1}`
+  };
   try {
-    runKernelTransaction(scrumDir, "approve-task-run", [
-      { file: repository.pathFor(task), previous: null, next: serializeArtifact(task, taskBody) },
-      { file: repository.pathFor(run), previous: null, next: serializeArtifact(run, runBody) }
-    ], {
-      failurePoint: failurePoint === "after-task" ? "after-1" : failurePoint === "after-run" ? "after-2" : null,
+    runKernelTransaction(scrumDir, "approve-task-run", writes, {
+      failurePoint: failureTarget[failurePoint] || failurePoint,
       interruptPoint
     });
   } catch (error) {

package/lib/runtime/request-engine.js

@@ -51,6 +51,28 @@ function classifyRequest(request) {
   return { type: "task", taskType: "task", reason: "request is best represented as one atomic Task" };
 }
 
+function materializeRequest(classification) {
+  const create = [];
+  const links = {
+    feature: false,
+    sprint: false
+  };
+  if (classification.type === "feature") {
+    create.push("Feature");
+    links.feature = true;
+  }
+  if (classification.type === "sprint") {
+    create.push("Sprint");
+    links.sprint = true;
+  }
+  create.push("Task", "Run");
+  return {
+    create,
+    links,
+    summary: create.join(" + ")
+  };
+}
+
 function applyPolicy(context) {
   return evaluatePolicy(context);
 }
@@ -124,6 +146,7 @@ function planRequest(projectRoot, request, { typeOverride = null, preview = null
     if (containsSecret(preview)) throw new Error("Preview contains secret-like content.");
     safePreview = String(preview).trim().slice(0, 2000);
   }
+  const materialization = materializeRequest(classification);
   const plan = {
     state: policy.status === "passed" ? "awaiting_approval" : "blocked",
     pipeline: ["received", "contextualizing", "policy", "risk", "classification", "planning", policy.status === "passed" ? "awaiting_approval" : "blocked"],
@@ -135,7 +158,9 @@ function planRequest(projectRoot, request, { typeOverride = null, preview = null
     classification,
     preview: safePreview,
     proposal: {
-      create: ["Task", "Run"],
+      create: materialization.create,
+      materialization,
+      relationships: materialization.links,
       sprint: classification.type === "sprint" ? "propose only after confirming real batch/timebox membership" : null,
       validation: risk.level === "high" ? "targeted tests plus configured reviewers" : "targeted tests"
     },
@@ -153,5 +178,6 @@ module.exports = {
   decodeApproval,
   encodeApproval,
   planRequest,
+  materializeRequest,
   stableJson
 };

package/lib/v2/conformance.js

@@ -17,7 +17,7 @@ const { canonicalPaths, PATHS_SCHEMA_VERSION } = require("./paths");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
-  { id: "I-02", summary: "approval creates Task and Run atomically", tests: ["explicit approval creates exactly one linked Task and Run", "approval failure injection rolls back"] },
+  { id: "I-02", summary: "approval materializes the requested plan shape atomically", tests: ["explicit approval creates exactly one linked Task and Run", "approval failure injection rolls back"] },
   { id: "I-03", summary: "Task is atomic and Sprint only groups evidenced batches", tests: ["migration apply creates linked v2 artifacts", "artifact repository builds explicit Feature Task Sprint Run graph"] },
   { id: "I-04", summary: "retry preserves prior Runs", tests: ["retry creates a new Run and preserves"] },
   { id: "I-05", summary: "state transitions are declared, evidenced, ordered, and recoverable", tests: ["run state machine follows", "Run ledger uses stable event ids", "paired transition failure restores"] },

package/package.json

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