scrumrun 3.1.2 → 4.1.0

package/lib/migrate/run.js

@@ -0,0 +1,108 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { OPS } = require("./ops");
+
+function extractYamlBlocks(markdown) {
+  const blocks = {};
+  const regex = /```yaml\s+([a-z_0-9]+)\r?\n([\s\S]*?)```/g;
+  let match;
+  while ((match = regex.exec(markdown)) !== null) {
+    blocks[match[1]] = match[2];
+  }
+  return blocks;
+}
+
+function parseYamlList(yaml) {
+  if (!yaml || !yaml.trim()) return [];
+  const items = [];
+  let current = null;
+  for (const rawLine of yaml.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, "");
+    if (!line.trim()) continue;
+    const listMatch = /^(\s*)-\s+([a-z_0-9]+):\s*(.*)$/.exec(line);
+    const kvMatch = /^(\s+)([a-z_0-9]+):\s*(.*)$/.exec(line);
+    if (listMatch) {
+      current = {};
+      current[listMatch[2]] = coerce(listMatch[3]);
+      items.push(current);
+    } else if (kvMatch && current) {
+      current[kvMatch[2]] = coerce(kvMatch[3]);
+    }
+  }
+  return items;
+}
+
+function coerce(raw) {
+  const text = raw.trim();
+  if (text === "") return "";
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null") return null;
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (text.startsWith('"') && text.endsWith('"')) return text.slice(1, -1);
+  return text;
+}
+
+function parseMigration(source) {
+  const blocks = extractYamlBlocks(source);
+  const errors = [];
+  const steps = parseYamlList(blocks.steps);
+  const verify = parseYamlList(blocks.verify);
+  const rollback = parseYamlList(blocks.rollback);
+  if (!steps.length) errors.push("missing or empty ```yaml steps``` block");
+  if (!verify.length) errors.push("missing or empty ```yaml verify``` block");
+  for (const step of steps) {
+    if (!step.op || !OPS[step.op]) errors.push(`unknown or missing op in step: ${JSON.stringify(step)}`);
+  }
+  for (const step of verify) {
+    if (!step.op || !OPS[step.op]) errors.push(`unknown or missing verify op: ${JSON.stringify(step)}`);
+  }
+  return { steps, verify, rollback, errors };
+}
+
+function loadMigration(migrationFile) {
+  if (!fs.existsSync(migrationFile)) throw new Error(`Migration file not found: ${migrationFile}`);
+  const source = fs.readFileSync(migrationFile, "utf8");
+  const parsed = parseMigration(source);
+  if (parsed.errors.length) throw new Error(`Malformed migration ${path.basename(migrationFile)}: ${parsed.errors.join("; ")}`);
+  return parsed;
+}
+
+function runMigration(projectRoot, migrationFile, { dryRun = false } = {}) {
+  const migration = loadMigration(migrationFile);
+  if (dryRun) {
+    return {
+      status: "dry-run",
+      planned_steps: migration.steps.length,
+      planned_verify: migration.verify.length,
+      planned_rollback: migration.rollback.length
+    };
+  }
+  const journal = [];
+  const applied = [];
+  try {
+    for (const step of migration.steps) {
+      const result = OPS[step.op](projectRoot, step, journal);
+      applied.push({ op: step.op, result });
+    }
+    for (const step of migration.verify) {
+      OPS[step.op](projectRoot, step, journal);
+    }
+    return { status: "applied", steps: applied, journal };
+  } catch (error) {
+    return { status: "failed", steps: applied, error: error.message, journal };
+  }
+}
+
+function listMigrations(projectRoot) {
+  const dir = path.join(projectRoot, "migrations");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => /\.md$/.test(name))
+    .sort()
+    .map((name) => path.join(dir, name));
+}
+
+module.exports = { parseMigration, loadMigration, runMigration, listMigrations, extractYamlBlocks };

package/lib/runtime/briefing.js

@@ -29,6 +29,31 @@ function generateBriefing(scrumDir, repository) {
       }))
     .slice(0, 5);
 
+  // Blocked-by-dependency: Tasks with `depends_on: [ID, ...]` in frontmatter
+  // where at least one target artifact is missing or not terminal. This is a
+  // visibility signal, not a hard gate — the agent reads it and decides.
+  const allById = new Map();
+  for (const kind of Object.keys(snapshot.records)) {
+    for (const r of snapshot.records[kind] || []) {
+      if (r.id) allById.set(r.id, r);
+    }
+  }
+  const blockedLines = [];
+  for (const task of snapshot.records.task || []) {
+    if (!task.id || TERMINAL.has(task.status)) continue;
+    const deps = Array.isArray(task.depends_on) ? task.depends_on : [];
+    const blocking = [];
+    for (const depId of deps) {
+      if (typeof depId !== "string") continue;
+      const dep = allById.get(depId);
+      if (!dep) blocking.push(`${depId} (missing)`);
+      else if (!TERMINAL.has(dep.status)) blocking.push(`${depId} (${dep.status})`);
+    }
+    if (blocking.length) {
+      blockedLines.push(`- ${task.id} waits on ${blocking.join(", ")} — ${task.title || task.id}`);
+    }
+  }
+
   const completedRuns = (snapshot.records.run || [])
     .filter((r) => r.status === "completed")
     .slice(-5)
@@ -76,6 +101,10 @@ Progressive disclosure: read this first; go deeper only if the briefing lacks wh
 
 ${activeWork.length ? activeWork.join("\n") : "- No active canonical work."}
 
+## Blocked by dependency
+
+${blockedLines.length ? blockedLines.join("\n") : "- None. All active Tasks have their `depends_on` targets terminal (or none declared)."}
+
 ## Recent
 
 ${recentLines.length ? recentLines.join("\n") : "- No completed Runs."}

package/lib/runtime/context.js

@@ -167,7 +167,9 @@ function buildContextPackage(projectRoot, request) {
     return capped(content, limit);
   };
   const guardrailsContent = safeControl("guardrails.md", 10000);
-  const config = safeControl("config.md", 1000);
+  // Policy fields must never be truncated: a late Read-Only Paths declaration
+  // is still mandatory, regardless of explanatory prose above it.
+  const config = safeControl("config.md", 10000);
   const project = safeControl("project.md", 1400);
   const artifacts = model.source === "canonical-v2" ? artifactSnapshot(scrumDir) : { records: {}, hashes: [], warnings: [] };
   const openDecisions = (artifacts.records.decision || []).filter((record) => record.status === "open").slice(-10);

package/lib/runtime/orchestrator.js

@@ -57,7 +57,7 @@ function sprintBody(title, request, created, taskId) {
 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\n## Validation Scope\n\n- Required: validate the stated Acceptance Criteria and active Guardrails proportionately to risk.\n- Non-blocking: tests, reviews, or environments not explicitly required by the owner, Acceptance Criteria, or an active Guardrail. Record a material coverage gap as a follow-up; do not fail the Task solely because that optional check was not run.\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}`;
+  return `# ${titleFor(request)}\n\n## Request\n\n${request}\n\n## Done when\n\n- [ ] _State the smallest observable delivery contract before execution._\n\n## Validation Scope\n\n- Required: validate the stated Done when contract and active Guardrails proportionately to risk.\n- Non-blocking: tests, reviews, or environments not explicitly required by the owner, Done when contract, or an active Guardrail. Record a material coverage gap as a follow-up only when it is outside the approved contract; do not fail the Task solely because that optional check was not run.\n\n## Completion\n\n- _Fill this once, after the delivery contract is satisfied._\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) {
@@ -595,9 +595,9 @@ function planArtifactBody(kind, title, created) {
       "",
       title,
       "",
-      "## Acceptance Criteria",
+      "## Done when",
       "",
-      '- [ ] _Define what "done" means before execution._',
+      "- [ ] _State the smallest observable delivery contract before execution._",
       "",
       "## Source",
       "",
@@ -792,7 +792,7 @@ function amendPlanArtifact(projectRoot, kind, id, options = {}) {
     let body = artifact.body;
     if (options.title !== undefined) body = replaceTitle(body, options.title);
     if (options.request !== undefined) body = replaceSection(body, "Request", options.request);
-    if (options.acceptance !== undefined) body = replaceSection(body, "Acceptance Criteria", options.acceptance.map((item) => `- [ ] ${normalizeAmendText(item, "Acceptance criterion")}`).join("\n"));
+    if (options.acceptance !== undefined) body = replaceFirstKnownSection(body, ["Done when", "Acceptance Criteria"], options.acceptance.map((item) => `- [ ] ${normalizeAmendText(item, "Delivery criterion")}`).join("\n"));
     if (options.purpose !== undefined) body = replaceFirstKnownSection(body, ["Purpose", "Motivation"], options.purpose);
     if (options.exitCriteria !== undefined) body = replaceFirstKnownSection(body, ["Exit Criteria", "Exit criteria"], options.exitCriteria.map((item) => `- [ ] ${normalizeAmendText(item, "Exit criterion")}`).join("\n"));
     if (options.timebox !== undefined) body = replaceSection(body, "Timebox", options.timebox);

package/lib/runtime/policy-engine.js

@@ -3,6 +3,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { containsSecret } = require("../security/secrets");
+const { enforcementBlock } = require("../guardrails/evaluate");
 
 const GUARDRAIL_STATUSES = new Set(["active", "retired", "superseded"]);
 const ENFORCEMENTS = new Set([
@@ -72,6 +73,7 @@ function parseGuardrails(content) {
     const status = normalized(fields.status || "active").replace(/[._-]+$/, "");
     const enforcement = normalized(fields.enforcement || inferEnforcement(title, rule));
     const scope = (fields.scope || "all").split(/\s*,\s*/).map((value) => normalized(value)).filter(Boolean);
+    const declarative = enforcementBlock(block, heading[1]);
     return {
       id: heading[1],
       title,
@@ -80,6 +82,8 @@ function parseGuardrails(content) {
       enforcement,
       scope,
       source: fields.source || null,
+      enforcement_rule: declarative.value,
+      enforcement_errors: declarative.errors,
       explicit: {
         status: Object.prototype.hasOwnProperty.call(fields, "status"),
         enforcement: Object.prototype.hasOwnProperty.call(fields, "enforcement"),
@@ -94,6 +98,11 @@ function configFields(content) {
   return fieldMap(String(content || ""));
 }
 
+function declarativeGuardrailConfig(content) {
+  // A project preference can promote warnings to blocks, never demote blocks.
+  return { on_violation: normalized(configFields(content).guardrail_on_violation || "warn") === "block" ? "block" : "warn" };
+}
+
 function agentIdentity(scrumDir) {
   if (process.env.SCRUMRUN_AGENT) {
     const env = String(process.env.SCRUMRUN_AGENT).trim();
@@ -249,6 +258,7 @@ function validateGuardrailDocument(content) {
     if (!ENFORCEMENTS.has(record.enforcement)) errors.push(`${record.id} has unknown enforcement: ${record.enforcement}`);
     if (!record.scope.length) errors.push(`${record.id} has no scope`);
     for (const scope of record.scope) if (!SCOPES.has(scope)) errors.push(`${record.id} has unknown scope: ${scope}`);
+    for (const error of record.enforcement_errors || []) errors.push(error);
   }
   return { records, errors };
 }
@@ -278,6 +288,7 @@ function normalizeGuardrailDocument(content) {
 module.exports = {
   agentIdentity,
   configWeakeningAttempts,
+  declarativeGuardrailConfig,
   evaluatePolicy,
   inferEnforcement,
   normalizeGuardrailDocument,

package/lib/runtime/policy-integrity.js

@@ -0,0 +1,83 @@
+"use strict";
+
+// Daily work is intentionally Markdown-first.  This module keeps the
+// enforcement at the boundary: project policy is pinned when ScrumRun is
+// initialized/updated and `doctor --strict` / release audits detect drift.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function readRegular(file) {
+  if (!fs.existsSync(file) || !fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink()) return null;
+  return fs.readFileSync(file, "utf8");
+}
+
+function expectedCoreFingerprint(packageRoot = path.resolve(__dirname, "../..")) {
+  const core = readRegular(path.join(packageRoot, "CORE.md"));
+  return core === null ? null : sha256(core);
+}
+
+function readPolicyIntegrity(scrumDir) {
+  const marker = path.join(scrumDir, "method.json");
+  const raw = readRegular(marker);
+  if (raw === null) return { marker: null, integrity: null, error: "method.json is missing or unsafe" };
+  try {
+    const parsed = JSON.parse(raw);
+    return { marker: parsed, integrity: parsed.integrity || null, error: null };
+  } catch (error) {
+    return { marker: null, integrity: null, error: error.message };
+  }
+}
+
+function sealPolicyIntegrity(scrumDir, { includeGuardrails = false, coreFingerprint = expectedCoreFingerprint() } = {}) {
+  const state = readPolicyIntegrity(scrumDir);
+  if (state.error) throw new Error(`Cannot seal ScrumRun policy: ${state.error}`);
+  const core = readRegular(path.join(scrumDir, "core.md"));
+  if (core === null) throw new Error("Cannot seal ScrumRun policy: core.md is missing or unsafe.");
+  const guardrails = readRegular(path.join(scrumDir, "guardrails.md"));
+  if (guardrails === null) throw new Error("Cannot seal ScrumRun policy: guardrails.md is missing or unsafe.");
+  const next = {
+    ...state.marker,
+    workflow: { ...(state.marker.workflow || {}), daily: "markdown-first" },
+    integrity: {
+      ...(state.integrity || {}),
+      schema: 1,
+      core_sha256: sha256(core),
+      core_package_sha256: coreFingerprint || sha256(core),
+      ...(includeGuardrails || !state.integrity || !state.integrity.guardrails_sha256
+        ? { guardrails_sha256: sha256(guardrails) }
+        : {})
+    }
+  };
+  return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+function auditPolicyIntegrity(scrumDir, { coreFingerprint = expectedCoreFingerprint() } = {}) {
+  const state = readPolicyIntegrity(scrumDir);
+  if (state.error) return [{ severity: "critical", code: "POLICY_MARKER", message: state.error }];
+  const integrity = state.integrity;
+  if (!integrity || integrity.schema !== 1) {
+    return [{ severity: "warning", code: "POLICY_INTEGRITY_UNSEALED", message: "Policy fingerprints are not sealed. Run `scrumrun update --project --seal-policy` after owner review." }];
+  }
+  const findings = [];
+  const core = readRegular(path.join(scrumDir, "core.md"));
+  const guardrails = readRegular(path.join(scrumDir, "guardrails.md"));
+  if (core === null) findings.push({ severity: "critical", code: "CORE_UNSAFE", message: "core.md is missing or unsafe." });
+  else {
+    const actual = sha256(core);
+    if (actual !== integrity.core_sha256) findings.push({ severity: "high", code: "CORE_TAMPERED", message: "core.md differs from the owner-sealed policy. Restore it with `scrumrun update --project`." });
+    if (coreFingerprint && actual !== coreFingerprint) findings.push({ severity: "high", code: "CORE_PACKAGE_DRIFT", message: "core.md differs from the installed ScrumRun Core. Review then run `scrumrun update --project`." });
+  }
+  if (guardrails === null) findings.push({ severity: "critical", code: "GUARDRAILS_UNSAFE", message: "guardrails.md is missing or unsafe." });
+  else if (sha256(guardrails) !== integrity.guardrails_sha256) {
+    findings.push({ severity: "high", code: "GUARDRAILS_TAMPERED", message: "guardrails.md changed after owner sealing. Review it, then explicitly run `scrumrun update --project --seal-policy`." });
+  }
+  return findings;
+}
+
+module.exports = { auditPolicyIntegrity, expectedCoreFingerprint, sealPolicyIntegrity, sha256 };

package/lib/runtime/watcher.js

@@ -0,0 +1,185 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const { refreshState } = require("./orchestrator");
+const { incrementalArtifact, rebuildIndex, writeMap } = require("../memory/index");
+const { sourceWatchSnapshot } = require("../memory/index");
+
+const PID_FILE = path.join(".scrumrun", ".cache", "watcher.pid");
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_POLL_MS = 1500;
+const GENERATED_OUTPUTS = Object.freeze([".scrumrun/state.md", ".scrumrun/map.md", ".scrumrun/.cache/"]);
+const EXECUTABLE_MARKDOWN = Object.freeze(["CORE.md", "SPEC.md", "DECISIONS.md"]);
+
+function number(value, fallback, minimum, maximum) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+}
+
+function watcherConfig(projectRoot) {
+  const file = path.join(projectRoot, ".scrumrun", "config.md");
+  const content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const field = (name) => {
+    const matches = [...content.matchAll(new RegExp(`^${name.replace(/\./g, "\\.")}:\\s*(.+)$`, "gmi"))];
+    return matches.length ? matches[matches.length - 1][1] : "";
+  };
+  return {
+    enabled: /^(true|yes|on|1)$/i.test(field("watcher.enabled").trim()),
+    debounceMs: number(field("watcher.debounce_ms"), DEFAULT_DEBOUNCE_MS, 25, 60_000),
+    pollMs: number(field("watcher.poll_interval_ms"), DEFAULT_POLL_MS, 250, 300_000)
+  };
+}
+
+function pidFile(projectRoot) { return path.join(projectRoot, PID_FILE); }
+
+function readStatus(projectRoot) {
+  const file = pidFile(projectRoot);
+  try {
+    const pid = Number(fs.readFileSync(file, "utf8").trim());
+    if (!Number.isInteger(pid) || pid < 1) throw new Error("invalid pid");
+    try { process.kill(pid, 0); return { running: true, pid, file }; }
+    catch { return { running: false, pid, file }; }
+  } catch { return { running: false, pid: null, file }; }
+}
+
+function writeStatus(projectRoot, value) {
+  const file = pidFile(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${value.pid}\n`);
+}
+
+function isRelevant(relative) {
+  const item = String(relative || "").split(path.sep).join("/").replace(/^\.\//, "");
+  if (!item || item === ".") return true;
+  if (item === ".scrumrun/vault.local.md" || item.startsWith(".scrumrun/.cache/contexts/") || item.startsWith(".scrumrun/.cache/") || item === ".scrumrun/state.md" || item === ".scrumrun/map.md") return false;
+  if (item.startsWith(".git/") || item.startsWith("node_modules/") || item.startsWith("dist/") || item.startsWith("build/") || item.startsWith("coverage/")) return false;
+  return item.startsWith(".scrumrun/") || /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i.test(item);
+}
+
+function generatedOutputOnly(relative) {
+  const item = String(relative || "").split(path.sep).join("/").replace(/^\.\//, "");
+  return GENERATED_OUTPUTS.some((output) => output.endsWith("/") ? item.startsWith(output) : item === output);
+}
+
+function assertGeneratedOutput(relative) {
+  if (!generatedOutputOnly(relative)) throw new Error(`Watcher output is restricted to generated projections, not ${relative}.`);
+}
+
+function refreshDerived(projectRoot, changed = []) {
+  // state.md is a bounded incremental projection; the SQLite graph falls back
+  // to its complete deterministic rebuild whenever a changed file could alter
+  // graph-wide lexical relations. This favours correctness over a partial edge
+  // update and keeps the incremental seam explicit for future adapters.
+  assertGeneratedOutput(".scrumrun/state.md");
+  assertGeneratedOutput(".scrumrun/.cache/semantic-index.sqlite");
+  assertGeneratedOutput(".scrumrun/map.md");
+  const state = refreshState(path.join(projectRoot, ".scrumrun"));
+  const incremental = incrementalArtifact(projectRoot, changed);
+  const index = incremental || rebuildIndex(projectRoot, { changedPaths: changed });
+  const map = writeMap(projectRoot);
+  return { mode: incremental ? "incremental-artifact" : changed.length === 1 ? "incremental-state+full-index-fallback" : "coalesced-full-index", changed, state, index, map };
+}
+
+function createWatcher(projectRoot, options = {}) {
+  const config = { ...watcherConfig(projectRoot), ...options };
+  let closed = false;
+  let pending = new Set();
+  let timer = null;
+  let poll = null;
+  let native = null;
+  let mode = "polling";
+  let snapshot = sourceWatchSnapshot(projectRoot).fingerprint;
+  let rebuilds = 0;
+  let lastResult = null;
+
+  const flush = () => {
+    timer = null;
+    if (closed || !pending.size) return;
+    const changed = [...pending].sort();
+    pending.clear();
+    lastResult = refreshDerived(projectRoot, changed);
+    snapshot = sourceWatchSnapshot(projectRoot).fingerprint;
+    rebuilds++;
+  };
+  const schedule = (relative) => {
+    if (!isRelevant(relative)) return;
+    pending.add(relative || ".");
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(flush, config.debounceMs);
+  };
+
+  const watch = options.watchImpl || fs.watch;
+  const startPolling = () => {
+    if (poll) return;
+    mode = "polling";
+    poll = setInterval(() => {
+      if (closed) return;
+      const next = sourceWatchSnapshot(projectRoot).fingerprint;
+      if (next !== snapshot) schedule(".");
+    }, config.pollMs);
+  };
+  try {
+    native = watch(projectRoot, { recursive: true }, (_event, filename) => schedule(filename ? String(filename) : "."));
+    mode = "fs.watch";
+    native.once("error", () => {
+      if (native) native.close();
+      native = null;
+      startPolling();
+    });
+  } catch {
+    // Linux and some Windows volumes do not support recursive fs.watch.
+    startPolling();
+  }
+  return {
+    get mode() { return mode; },
+    get rebuilds() { return rebuilds; },
+    get lastResult() { return lastResult; },
+    schedule,
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      if (poll) clearInterval(poll);
+      if (native) native.close();
+    }
+  };
+}
+
+function runDaemon(projectRoot) {
+  const config = watcherConfig(projectRoot);
+  if (!config.enabled) throw new Error("Watcher is disabled. Set watcher.enabled: true in .scrumrun/config.md before starting it.");
+  refreshDerived(projectRoot, ["startup"]);
+  const watcher = createWatcher(projectRoot, config);
+  writeStatus(projectRoot, { pid: process.pid });
+  const stop = () => {
+    watcher.close();
+    try { fs.rmSync(pidFile(projectRoot), { force: true }); } catch { /* best effort generated state cleanup */ }
+    process.exit(0);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+}
+
+function startWatcher(projectRoot) {
+  const config = watcherConfig(projectRoot);
+  if (!config.enabled) return { status: "disabled", config };
+  const status = readStatus(projectRoot);
+  if (status.running) return { status: "already-running", ...status };
+  const child = spawn(process.execPath, [__filename, "--daemon", projectRoot], { detached: true, stdio: "ignore" });
+  child.unref();
+  return { status: "started", pid: child.pid, config };
+}
+
+function stopWatcher(projectRoot) {
+  const status = readStatus(projectRoot);
+  if (status.running) {
+    try { process.kill(status.pid, "SIGTERM"); } catch { /* status is reconciled below */ }
+  }
+  try { fs.rmSync(pidFile(projectRoot), { force: true }); } catch { /* generated state cleanup */ }
+  return { status: status.running ? "stopped" : "not-running", pid: status.pid };
+}
+
+if (require.main === module && process.argv[2] === "--daemon") runDaemon(path.resolve(process.argv[3] || process.cwd()));
+
+module.exports = { EXECUTABLE_MARKDOWN, GENERATED_OUTPUTS, assertGeneratedOutput, createWatcher, generatedOutputOnly, isRelevant, refreshDerived, readStatus, startWatcher, stopWatcher, watcherConfig };

package/lib/v2/artifacts.js

@@ -17,6 +17,7 @@ function sha256(content) {
 
 function scalar(value) {
   if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return `[${value.map((item) => scalar(item)).join(", ")}]`;
   if (typeof value === "boolean" || typeof value === "number") return String(value);
   const text = String(value);
   if (/^[A-Za-z0-9._/-]+$/.test(text)) return text;
@@ -36,6 +37,11 @@ function parseScalar(value) {
       return text;
     }
   }
+  if (text.startsWith("[") && text.endsWith("]")) {
+    const inner = text.slice(1, -1).trim();
+    if (!inner) return [];
+    return inner.split(",").map((item) => parseScalar(item));
+  }
   return text;
 }
 
@@ -102,6 +108,9 @@ function validateArtifact(record, expectedKind = null) {
       errors.push(`${record.kind}.${field} must reference ${target.prefix}-NNN`);
     }
   }
+  if (record.kind === "run" && (record.task === undefined || record.task === null) && (record.sprint === undefined || record.sprint === null)) {
+    errors.push("run must reference TASK-NNN or SPRINT-NNN");
+  }
   for (const [field, constraint] of Object.entries(SCALAR_FIELDS)) {
     if (!constraint.kinds.includes(record.kind)) continue;
     if (constraint.required && (record[field] === undefined || record[field] === null)) {