scrumrun 2.7.1 → 2.7.3

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.7.3 - 2026-08-22
+
+### Added
+
+- **Manual Task/Feature/Sprint creation via CLI.** `sc plan task --add`, `sc plan feature --add`, and `sc plan sprint --add` now create canonical artifacts directly (previously these documented actions fell through to the "Agent workflow" hint without writing anything). `--add` parks intent only — a Task lands in `backlog` with no Run, and `sc plan task --start TASK-NNN` remains the explicit approval that creates the first Run. `sc plan task --add` accepts `--type fix|task|docs|discovery` and `--status backlog|proposed`; Feature and Sprint default to their initial statuses. `--list`/`--show` now also cover Feature and Sprint artifacts.
+
+## 2.7.2 - 2026-08-21
+
+### Fixed
+
+- **Duplicate artifact ids across concurrent agents.** All create operations now serialize on a single global `create` lock (`approveRequest`, `retryTask`, `startBacklogTask`, `createMemory`, `recordArtifactReview`) instead of independent per-operation locks (`approval`, `task-…`, `memory-…`, `review-artifact`). Previously two agents could read the same `max` id and both write `TASK-NNN`/`RUN-NNN`; the race is now closed at the source. Conformance's `ID_DUPLICATE` finding remains as a detection backstop for hand-written files.
+
+### Validation
+
+- Added `tests/id-concurrency.test.js` — concurrent backlog starts and memory proposals across child processes allocate unique ids.
+
 ## 2.7.1 - 2026-08-21
 
 ### 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.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.7.3` · **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 { approveRequest, nextBacklogTask, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { addPlanArtifact, approveRequest, nextBacklogTask, 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"));
@@ -1451,6 +1451,18 @@ function executeRootRoute(route) {
     console.log(`Started ${result.task.id} (${result.run.id}) assigned to ${result.task.assignee || "agent"}.`);
     return;
   }
+  if (noun === "plan" && ["task", "feature", "sprint"].includes(subject) && routeArgs[0] === "--add") {
+    const label = removeOptionPairs(routeArgs.slice(1), ["--type", "--status"])
+      .filter((arg) => !arg.startsWith("--"))
+      .join(" ")
+      .trim();
+    const result = addPlanArtifact(process.cwd(), subject, label, {
+      type: optionValue(routeArgs, "--type"),
+      status: optionValue(routeArgs, "--status")
+    });
+    console.log(`Created ${result.record.status} ${result.record.id}: ${path.relative(process.cwd(), result.file)}`);
+    return;
+  }
   if (noun === "plan" && subject === "run" && routeArgs[0] === "--render") {
     const { renderRunFromDisk } = require(path.join(root, "lib", "commands", "run-render"));
     const runId = routeArgs[1];
@@ -1503,7 +1515,7 @@ function executeRootRoute(route) {
     }
     return;
   }
-  if (noun === "plan" && ["task", "run"].includes(subject) && ["--list", "--show"].includes(routeArgs[0])) {
+  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}`);

package/lib/memory/service.js

@@ -213,7 +213,7 @@ function createMemory(projectRoot, kind, options = {}) {
   if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
   assertV2Project(projectRoot);
   const scrumDir = path.join(projectRoot, ".scrumrun");
-  return withArtifactLock(scrumDir, `memory-${kind}`, () => createMemoryUnlocked(projectRoot, kind, options));
+  return withArtifactLock(scrumDir, "create", () => createMemoryUnlocked(projectRoot, kind, options));
 }
 
 function setFrontmatter(content, updates) {

package/lib/runtime/orchestrator.js

@@ -18,10 +18,11 @@ const { buildContextPackage } = require("./context");
 const { agentIdentity, evaluatePolicy } = require("./policy-engine");
 const { artifactSnapshot, canonicalFingerprint, canonicalWatchSnapshot } = require("./canonical-snapshot");
 const { decodeApproval } = require("./request-engine");
+const { containsSecret } = require("../security/secrets");
 const { extractLearningCandidates } = require("../code-intel/learning");
 const { appendRunEvent, appendTechnicalSummary, createRunBody, instant } = require("./run-ledger");
 const { generateBriefing } = require("./briefing");
-const { policyState, prepareCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
+const { assertCanonicalWrite, policyState, prepareCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
 const { recoverPendingTransactions, runKernelTransaction } = require("../v2/transaction");
 
 const TERMINAL = new Set(["completed", "failed", "cancelled", "resolved", "rejected", "deprecated", "invalidated", "archived", "passed"]);
@@ -160,7 +161,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
 }
 
 function approveRequest(projectRoot, token, options = {}) {
-  return withArtifactLock(path.join(projectRoot, ".scrumrun"), "approval", () => approveRequestUnlocked(projectRoot, token, options));
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), "create", () => approveRequestUnlocked(projectRoot, token, options));
 }
 
 function transitionedArtifactContent(content, kind, nextStatus, updated, assignee = null) {
@@ -338,7 +339,7 @@ function retryTaskUnlocked(projectRoot, taskId, { note = "Retry explicitly appro
 }
 
 function retryTask(projectRoot, taskId, options = {}) {
-  return withArtifactLock(path.join(projectRoot, ".scrumrun"), `task-${String(taskId).toLowerCase()}`, () => retryTaskUnlocked(projectRoot, taskId, options));
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), "create", () => retryTaskUnlocked(projectRoot, taskId, options));
 }
 
 function nextBacklogTask(repository) {
@@ -408,7 +409,119 @@ function startBacklogTaskUnlocked(projectRoot, taskId, { note = "Backlog Task st
 }
 
 function startBacklogTask(projectRoot, taskId, options = {}) {
-  return withArtifactLock(path.join(projectRoot, ".scrumrun"), `task-${String(taskId).toLowerCase()}`, () => startBacklogTaskUnlocked(projectRoot, taskId, options));
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), "create", () => startBacklogTaskUnlocked(projectRoot, taskId, options));
 }
 
-module.exports = { approveRequest, nextBacklogTask, nextId, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };
+const ADDABLE_PLAN_KINDS = new Set(["task", "feature", "sprint"]);
+const ADD_PLAN_DEFAULTS = Object.freeze({
+  task: { status: "backlog", type: "task" },
+  feature: { status: "backlog", type: "initiative" },
+  sprint: { status: "proposed", type: null }
+});
+const ADD_PLAN_INITIAL_STATUS = Object.freeze({
+  task: ["backlog", "proposed"],
+  feature: ["backlog", "proposed"],
+  sprint: ["proposed"]
+});
+const TASK_TYPES = new Set(["task", "fix", "docs", "discovery"]);
+
+function planArtifactBody(kind, title, created) {
+  const source = `- ${created}: created via CLI (\`sc plan ${kind} --add\`).`;
+  if (kind === "task") {
+    return [
+      `# ${title}`,
+      "",
+      "## Request",
+      "",
+      title,
+      "",
+      "## Acceptance Criteria",
+      "",
+      '- [ ] _Define what "done" means before execution._',
+      "",
+      "## Source",
+      "",
+      source
+    ].join("\n");
+  }
+  if (kind === "feature") {
+    return [
+      `# ${title}`,
+      "",
+      "## Motivation",
+      "",
+      title,
+      "",
+      "## Exit criteria",
+      "",
+      '- [ ] _Define what success looks like._',
+      "",
+      "## Source",
+      "",
+      source
+    ].join("\n");
+  }
+  return [
+    `# ${title}`,
+    "",
+    "## Tasks",
+    "",
+    "_Pending: add Task ids here._",
+    "",
+    "## Exit Gate",
+    "",
+    '- [ ] _Define the batch completion condition._',
+    "",
+    "## Source",
+    "",
+    source
+  ].join("\n");
+}
+
+function addPlanArtifactUnlocked(projectRoot, kind, label, { type = null, status = null } = {}) {
+  if (!ADDABLE_PLAN_KINDS.has(kind)) throw new Error(`Unsupported plan kind: ${kind}`);
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  recoverPendingTransactions(scrumDir);
+  const repository = new ArtifactRepository(scrumDir);
+  const title = String(label || "").trim();
+  if (!title) throw new Error(`A non-empty title is required for ${kind} --add.`);
+  if (/\r|\n/.test(title)) throw new Error(`${kind} title must be one line.`);
+  if (title.length > 200) throw new Error(`${kind} title exceeds the 200 character limit.`);
+  if (containsSecret(title)) throw new Error("Secret-like content is forbidden outside the local vault.");
+  const chosenStatus = status || ADD_PLAN_DEFAULTS[kind].status;
+  if (!ADD_PLAN_INITIAL_STATUS[kind].includes(chosenStatus)) {
+    throw new Error(`Invalid ${kind} status: ${chosenStatus}. Allowed for --add: ${ADD_PLAN_INITIAL_STATUS[kind].join(", ")}.`);
+  }
+  let chosenType = ADD_PLAN_DEFAULTS[kind].type;
+  if (kind === "task" && type) {
+    if (!TASK_TYPES.has(type)) throw new Error(`Invalid task --type: ${type}. Valid: ${[...TASK_TYPES].join(", ")}.`);
+    chosenType = type;
+  }
+  const created = date();
+  const record = {
+    id: nextId(repository, kind),
+    kind,
+    status: chosenStatus,
+    created,
+    updated: created,
+    method: METHOD_VERSION
+  };
+  if (kind === "task") {
+    record.type = chosenType;
+    record.feature = null;
+    record.sprint = null;
+  } else if (kind === "feature") {
+    record.type = chosenType;
+  }
+  const body = planArtifactBody(kind, title, created);
+  assertCanonicalWrite(projectRoot, `add-${kind}`, [title, body]);
+  repository.write(record, body);
+  return repository.read(kind, record.id);
+}
+
+function addPlanArtifact(projectRoot, kind, label, options = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, "create", () => addPlanArtifactUnlocked(projectRoot, kind, label, options));
+}
+
+module.exports = { addPlanArtifact, approveRequest, nextBacklogTask, nextId, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };

package/lib/runtime/review-service.js

@@ -86,7 +86,7 @@ function recordArtifactReviewUnlocked(projectRoot, options) {
 
 function recordArtifactReview(projectRoot, options = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
-  return withArtifactLock(scrumDir, "review-artifact", () => recordArtifactReviewUnlocked(projectRoot, options));
+  return withArtifactLock(scrumDir, "create", () => recordArtifactReviewUnlocked(projectRoot, options));
 }
 
 module.exports = { recordArtifactReview };

package/package.json

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

package/types/index.d.ts

@@ -396,6 +396,7 @@ export function renderState(repository: ArtifactRepository): string;
 export function stateFingerprint(repository: ArtifactRepository): string;
 export function stateIsStale(scrumDir: string): boolean;
 export function nextId(repository: ArtifactRepository, kind: ArtifactKind): string;
+export function addPlanArtifact(projectRoot: string, kind: ArtifactKind, label: string, options?: { type?: string | null; status?: string | null }): ParsedArtifact & { file: string };
 
 // ---------------------------------------------------------------------------
 // lib/runtime/mutation-gateway