scrumrun 3.1.2 → 4.1.0

package/lib/v2/conformance.js

@@ -11,9 +11,14 @@ const { extractEvidence } = require("../memory/markdown");
 const { resolveEvidence } = require("../memory/service");
 const { containsSecret, containsSecretWithAllowlist, loadSecretAllowlist } = require("../security/secrets");
 const { pendingTransactionStatus } = require("./transaction");
-const { configWeakeningAttempts, validateGuardrailDocument } = require("../runtime/policy-engine");
+const { configWeakeningAttempts, declarativeGuardrailConfig, validateGuardrailDocument } = require("../runtime/policy-engine");
 const { auditActiveWorkspace } = require("../runtime/mutation-gateway");
 const { canonicalPaths, PATHS_SCHEMA_VERSION } = require("./paths");
+const { auditPolicyIntegrity } = require("../runtime/policy-integrity");
+const { evaluate } = require("../guardrails/evaluate");
+const { collectChangeSet } = require("../guardrails/changeset");
+const { validateArtifacts: validateTaskSchema } = require("./task-schema");
+const { readGitContext } = require("../git/context");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -64,7 +69,7 @@ function diffPathIndex(expected, actual, prefix = "") {
   return drift;
 }
 
-function auditProject(projectRoot) {
+function auditProject(projectRoot, options = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const findings = [];
   if (!fs.existsSync(scrumDir) || !fs.lstatSync(scrumDir).isDirectory()) {
@@ -79,10 +84,10 @@ function auditProject(projectRoot) {
     if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
     const expectedPaths = canonicalPaths();
     if (!methodMarker.paths || typeof methodMarker.paths !== "object" || Array.isArray(methodMarker.paths)) {
-      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`scrumrun update --migrate\` to backfill.`, marker));
+      findings.push(finding("warning", "METHOD_PATHS_MISSING", `method.json is missing a canonical "paths" block. Non-blocking in Markdown-first daily work; run \`scrumrun update --migrate\` if you want the declared index.`, marker));
     } else {
       const drift = diffPathIndex(expectedPaths, methodMarker.paths);
-      for (const entry of drift) findings.push(finding("high", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Regenerate via \`update --migrate\`.`, marker));
+      for (const entry of drift) findings.push(finding("warning", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Non-blocking; regenerate via \`update --migrate\` when convenient.`, marker));
       if (methodMarker.paths_schema !== PATHS_SCHEMA_VERSION) {
         findings.push(finding("warning", "METHOD_PATHS_SCHEMA", `method.json paths_schema is ${methodMarker.paths_schema || "missing"}; expected ${PATHS_SCHEMA_VERSION}.`, marker));
       }
@@ -94,6 +99,7 @@ function auditProject(projectRoot) {
     const file = path.join(scrumDir, relative);
     if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) findings.push(finding("high", "CANONICAL_MISSING", `${relative} is missing or unsafe.`, file));
   }
+  for (const item of auditPolicyIntegrity(scrumDir)) findings.push(finding(item.severity, item.code, item.message, marker));
   const guardrailsFile = path.join(scrumDir, "guardrails.md");
   const guardrails = fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile() ? fs.readFileSync(guardrailsFile, "utf8") : "";
   const guardrailValidation = validateGuardrailDocument(guardrails);
@@ -111,6 +117,16 @@ function auditProject(projectRoot) {
   const configFile = path.join(scrumDir, "config.md");
   const config = fs.existsSync(configFile) && fs.lstatSync(configFile).isFile() ? fs.readFileSync(configFile, "utf8") : "";
   for (const error of configWeakeningAttempts(config)) findings.push(finding("high", "CONFIG_WEAKENS_POLICY", error, configFile));
+  const declarativeRules = guardrailValidation.records.filter((record) => record.status === "active" && record.enforcement_rule);
+  const guardrailEvaluation = evaluate(declarativeRules, options.changeSet || collectChangeSet(projectRoot, { staged: options.staged === true }), {
+    config: declarativeGuardrailConfig(config)
+  });
+  for (const item of guardrailEvaluation.blocked) {
+    findings.push(finding("high", "DECLARATIVE_GUARDRAIL_BLOCK", `${item.guardrail}: ${item.message} Evidence: ${item.evidence.join(", ")}.`, guardrailsFile));
+  }
+  for (const item of guardrailEvaluation.warnings) {
+    findings.push(finding("warning", "DECLARATIVE_GUARDRAIL_WARN", `${item.guardrail}: ${item.message} Evidence: ${item.evidence.join(", ")}.`, guardrailsFile));
+  }
 
   const repository = new ArtifactRepository(scrumDir);
   const counts = {};
@@ -141,9 +157,9 @@ function auditProject(projectRoot) {
         task = null;
       }
     }
-    if (run.record && !run.record.task) {
-      findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} has no task reference (record.task is null).`, run.file));
-    } else if (run.record && (!task || task.errors.length)) {
+    if (run.record && !run.record.task && !run.record.sprint) {
+      findings.push(finding("high", "RUN_TARGET_MISSING", `${run.record.id} must reference a Task or Sprint.`, run.file));
+    } else if (run.record && run.record.task && (!task || task.errors.length)) {
       findings.push(finding("high", "RUN_TASK_MISSING", `${run.record.id} references missing or invalid ${run.record.task}.`, run.file));
     }
     if (run.record && task && !task.errors.length && (run.record.sprint || null) !== (task.record.sprint || null)) {
@@ -170,6 +186,7 @@ function auditProject(projectRoot) {
     }
   }
   const byId = new Map(Object.values(records).flat().filter((artifact) => artifact.record).map((artifact) => [artifact.record.id, artifact]));
+  const markdownFirst = methodMarker && methodMarker.workflow && methodMarker.workflow.daily === "markdown-first";
   for (const task of records.task || []) {
     for (const [field, prefix] of [["feature", "FEAT"], ["sprint", "SPRINT"]]) {
       const target = task.record && task.record[field];
@@ -182,7 +199,7 @@ function auditProject(projectRoot) {
   }
   const attemptsByTask = new Map();
   for (const run of records.run || []) {
-    if (!run.record || run.errors.length) continue;
+    if (!run.record || run.errors.length || !run.record.task) continue;
     if (!attemptsByTask.has(run.record.task)) attemptsByTask.set(run.record.task, []);
     attemptsByTask.get(run.record.task).push(run.record.attempt);
   }
@@ -199,11 +216,14 @@ function auditProject(projectRoot) {
       .filter((run) => run.record && !run.errors.length && run.record.task === task.record.id)
       .sort((left, right) => right.record.attempt - left.record.attempt);
     if (!attempts.length) {
+      if (markdownFirst) continue;
       if (["running", "validating", "learning", "partial"].includes(task.record.status)) {
         findings.push(finding(
-          "high",
+          markdownFirst ? "warning" : "high",
           "TASK_ORPHANED",
-          `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
+          markdownFirst
+            ? `${task.record.id}.status is ${task.record.status} without a Run. This is valid Markdown-first work; keep the Task handoff current.`
+            : `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
           task.file
         ));
       }
@@ -219,17 +239,13 @@ function auditProject(projectRoot) {
       blocked: "blocked",
       partial: "partial"
     };
-    if (taskStatuses[latest.status] && task.record.status !== taskStatuses[latest.status]) {
+    if (!markdownFirst && taskStatuses[latest.status] && task.record.status !== taskStatuses[latest.status]) {
       findings.push(finding("high", "TASK_RUN_STATUS_MISMATCH", `${task.record.id}.status ${task.record.status} disagrees with latest ${latest.id}.status ${latest.status}.`, task.file));
     }
   }
-  for (const task of records.task || []) {
-    if (!task.record || task.errors.length) continue;
-    if (["backlog", "proposed", "cancelled"].includes(task.record.status)) continue;
-    if (!/^## Acceptance Criteria\b/m.test(task.body || "")) {
-      findings.push(finding("warning", "ACCEPTANCE_CRITERIA_MISSING", `${task.record.id} has no Acceptance Criteria section; define what "done" means before execution.`, task.file));
-    }
-  }
+  // Task bodies are intentionally extensible Markdown. Project Guardrails may
+  // require sections for selected Tasks; the kernel never requires one global
+  // heading or rejects unknown owner-defined structure.
   for (const sprint of records.sprint || []) {
     if (!sprint.record || sprint.errors.length) continue;
     const heading = /^## Tasks[ \t]*$/m.exec(sprint.body);
@@ -286,6 +302,17 @@ function auditProject(projectRoot) {
   } catch (error) {
     findings.push(finding("high", "INDEX_UNSAFE", `semantic index cannot inspect canonical sources safely: ${error.message}`));
   }
+  const allArtifacts = Object.values(records).flat();
+  const gitContext = options.gitContext || readGitContext(projectRoot);
+  const taskSchemaReport = validateTaskSchema(allArtifacts, { gitContext });
+  const schemaErrorSeverity = options.strict ? "high" : "warning";
+  for (const error of taskSchemaReport.errors) {
+    findings.push(finding(schemaErrorSeverity, error.code, error.message, error.file));
+  }
+  for (const warning of taskSchemaReport.warnings) {
+    findings.push(finding("warning", warning.code, warning.message, warning.file));
+  }
+
   const transactions = pendingTransactionStatus(scrumDir);
   if (transactions.error) {
     findings.push(finding("high", "TRANSACTION_JOURNAL_UNSAFE", transactions.error));

package/lib/v2/paths.js

@@ -56,10 +56,11 @@ function flattenPaths(paths = CANONICAL_PATHS, prefix = "") {
   return out;
 }
 
-function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, migratedFrom, migration } = {}) {
+function renderMethodJson({ methodVersion, layout = "v2", schemas = {}, workflow = { daily: "markdown-first" }, migratedFrom, migration } = {}) {
   const payload = {
     method: methodVersion,
     layout,
+    workflow,
     paths_schema: PATHS_SCHEMA_VERSION,
     paths: canonicalPaths(),
     schemas

package/lib/v2/runs-jsonl.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const RUNS_JSONL_SCHEMA = 1;
+const ALLOWED_EVENTS = Object.freeze(["created", "started", "transition", "note", "evidence", "guardrail", "mutation", "completed", "failed", "blocked"]);
+const GENESIS_HASH = "0".repeat(64);
+
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+function jsonlPath(scrumDir, taskId) {
+  return path.join(scrumDir, "runs", `${taskId}.jsonl`);
+}
+
+function assertTaskId(taskId) {
+  if (!/^TASK-\d{3,}$/.test(String(taskId || ""))) throw new Error(`Invalid TASK id for runs.jsonl: ${taskId}`);
+}
+
+function canonicalizePayload(payload) {
+  if (payload === null || payload === undefined) return {};
+  if (typeof payload !== "object" || Array.isArray(payload)) throw new Error("payload must be a plain object");
+  const sorted = {};
+  for (const key of Object.keys(payload).sort()) sorted[key] = payload[key];
+  return sorted;
+}
+
+function computeHash(previousHash, entry) {
+  const material = JSON.stringify({ prev: previousHash, run_id: entry.run_id, ts: entry.ts, event: entry.event, payload: entry.payload });
+  return sha256Hex(material);
+}
+
+function readEntries(scrumDir, taskId) {
+  assertTaskId(taskId);
+  const file = jsonlPath(scrumDir, taskId);
+  if (!fs.existsSync(file)) return [];
+  const contents = fs.readFileSync(file, "utf8");
+  if (!contents) return [];
+  const entries = [];
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    entries.push(JSON.parse(line));
+  }
+  return entries;
+}
+
+function validateEntries(entries) {
+  const errors = [];
+  let previous = GENESIS_HASH;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    if (!entry || typeof entry !== "object") { errors.push(`entry ${index}: not an object`); continue; }
+    for (const field of ["run_id", "ts", "event", "payload", "prev", "hash"]) {
+      if (!(field in entry)) errors.push(`entry ${index}: missing ${field}`);
+    }
+    if (entry.prev !== previous) errors.push(`entry ${index}: prev ${entry.prev} != expected ${previous}`);
+    if (!ALLOWED_EVENTS.includes(entry.event)) errors.push(`entry ${index}: unknown event ${entry.event}`);
+    const expectedHash = computeHash(previous, entry);
+    if (entry.hash !== expectedHash) errors.push(`entry ${index}: hash ${entry.hash} != expected ${expectedHash}`);
+    previous = entry.hash || previous;
+  }
+  return { errors, headHash: previous };
+}
+
+function appendEntry(scrumDir, taskId, { run_id, ts, event, payload }) {
+  assertTaskId(taskId);
+  if (!run_id || !/^RUN-\d{3,}$/.test(String(run_id))) throw new Error(`Invalid run_id: ${run_id}`);
+  if (!ts || Number.isNaN(Date.parse(ts))) throw new Error(`Invalid ts (ISO-8601 required): ${ts}`);
+  if (!ALLOWED_EVENTS.includes(event)) throw new Error(`Unknown event: ${event}`);
+  const canonicalPayload = canonicalizePayload(payload);
+
+  const file = jsonlPath(scrumDir, taskId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  // Concurrency: exclusive-create a lockfile; retry with jittered backoff.
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + 5000;
+  let handle = null;
+  while (Date.now() < deadline) {
+    try {
+      handle = fs.openSync(lock, "wx");
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const delay = 5 + Math.floor(Math.random() * 15);
+      const busyUntil = Date.now() + delay;
+      while (Date.now() < busyUntil) { /* spin briefly */ }
+    }
+  }
+  if (handle === null) throw new Error(`Could not acquire lock on ${lock} within 5s`);
+
+  try {
+    const entries = readEntries(scrumDir, taskId);
+    const previous = entries.length ? entries[entries.length - 1].hash : GENESIS_HASH;
+    const record = { run_id, ts, event, payload: canonicalPayload, prev: previous };
+    record.hash = computeHash(previous, record);
+    const line = `${JSON.stringify(record)}\n`;
+    fs.appendFileSync(file, line);
+    return record;
+  } finally {
+    try { fs.closeSync(handle); } catch { /* ignore */ }
+    try { fs.unlinkSync(lock); } catch { /* ignore */ }
+  }
+}
+
+function listRunIds(scrumDir, taskId) {
+  const entries = readEntries(scrumDir, taskId);
+  return [...new Set(entries.map((entry) => entry.run_id))];
+}
+
+function listAllTaskLedgers(scrumDir) {
+  const dir = path.join(scrumDir, "runs");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => /^TASK-\d{3,}\.jsonl$/.test(name))
+    .map((name) => name.replace(/\.jsonl$/, ""));
+}
+
+module.exports = {
+  RUNS_JSONL_SCHEMA,
+  ALLOWED_EVENTS,
+  GENESIS_HASH,
+  jsonlPath,
+  readEntries,
+  validateEntries,
+  appendEntry,
+  listRunIds,
+  listAllTaskLedgers,
+  computeHash
+};

package/lib/v2/schema.js

@@ -38,8 +38,8 @@ const ARTIFACT_TYPES = deepFreeze({
   task: {
     prefix: "TASK",
     directory: "tasks",
-    initial: ["backlog", "proposed", "running"],
-    statuses: ["backlog", "proposed", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
+    initial: ["backlog", "proposed", "in_progress", "running"],
+    statuses: ["backlog", "proposed", "in_progress", "running", "validating", "learning", "partial", "completed", "failed", "blocked", "cancelled"]
   },
   sprint: {
     prefix: "SPRINT",
@@ -90,7 +90,7 @@ const ARTIFACT_TRANSITIONS = deepFreeze({
     backlog: ["proposed", "active", "cancelled"], proposed: ["active", "cancelled"], active: ["paused", "completed", "cancelled"], paused: ["active", "cancelled"]
   },
   task: {
-    backlog: ["proposed", "running", "cancelled"], proposed: ["running", "cancelled"], running: ["validating", "failed", "blocked", "cancelled"], validating: ["learning", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["running", "cancelled"], failed: ["running", "cancelled"], blocked: ["running", "cancelled"]
+    backlog: ["proposed", "in_progress", "running", "cancelled"], proposed: ["in_progress", "running", "cancelled"], in_progress: ["completed", "failed", "blocked", "cancelled"], running: ["validating", "completed", "failed", "blocked", "cancelled"], validating: ["learning", "completed", "failed", "blocked"], learning: ["completed", "failed", "blocked"], partial: ["in_progress", "running", "cancelled"], failed: ["in_progress", "running", "cancelled"], blocked: ["in_progress", "running", "cancelled"]
   },
   sprint: {
     proposed: ["running", "cancelled"], running: ["partial", "completed", "blocked", "cancelled"], partial: ["running", "completed", "cancelled"], blocked: ["running", "cancelled"]
@@ -108,7 +108,7 @@ const ARTIFACT_TRANSITIONS = deepFreeze({
 const STRUCTURAL_RELATIONS = deepFreeze({
   feature: { targetKind: "feature", cardinality: "0..1", meaning: "long-lived initiative containing the artifact" },
   sprint: { targetKind: "sprint", cardinality: "0..1", meaning: "optional delivery batch containing a Task or Run" },
-  task: { targetKind: "task", cardinality: "1 for Run; otherwise 0..1", requiredFor: ["run"], meaning: "atomic work executed or reviewed by the artifact" }
+  task: { targetKind: "task", cardinality: "0..1", meaning: "atomic work executed or reviewed by the artifact" }
 });
 
 const SCALAR_FIELDS = deepFreeze({
@@ -120,9 +120,9 @@ const SCALAR_FIELDS = deepFreeze({
 
 const TRUTH_OWNERSHIP = deepFreeze({
   feature: { question: "Why does this initiative exist?", truth: "initiative purpose, scope, dependencies, and lifecycle" },
-  task: { question: "What approved atomic outcome is intended?", truth: "scope, acceptance criteria, approval, and intended status" },
-  sprint: { question: "When are related Tasks grouped?", truth: "timebox or delivery-batch membership; never execution history" },
-  run: { question: "How did one execution attempt actually happen?", truth: "append-only execution events, evidence, result, and attempt number" },
+  task: { question: "What concrete outcome is intended?", truth: "scope, owner-defined sections, links, and status" },
+  sprint: { question: "Which Tasks are grouped for this delivery?", truth: "timebox or delivery-batch membership; may be feature, fix, or maintenance" },
+  run: { question: "What happened while executing a Task or Sprint?", truth: "optional human-readable execution record and outcome" },
   review: { question: "What independent validation was performed?", truth: "scoped findings, checks, evidence, and verdict" },
   knowledge: { question: "What verified project fact is reusable?", truth: "approved evidence-backed fact and validity" },
   decision: { question: "What normative choice constrains future work?", truth: "decision, rationale, validity, and lifecycle" },

package/lib/v2/task-schema.js

@@ -0,0 +1,133 @@
+"use strict";
+
+const REQUIRED_SECTIONS = Object.freeze({
+  task: ["## Request", "## Done when"],
+  feature: [],
+  sprint: [],
+  run: []
+});
+
+const COMPLETION_MIN_LENGTH = 24;
+
+function findSectionLine(lines, heading) {
+  const target = heading.trim().toLowerCase();
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index].trim().toLowerCase() === target) return index + 1;
+  }
+  return -1;
+}
+
+function sectionBody(lines, heading) {
+  const start = findSectionLine(lines, heading);
+  if (start === -1) return null;
+  const body = [];
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^## /.test(line) && index !== start - 1) break;
+    if (index !== start - 1) body.push(line);
+  }
+  return body.join("\n").trim();
+}
+
+function bodyLines(bodyOrSource) {
+  const text = String(bodyOrSource || "");
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== "---") return lines;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index] === "---") return lines.slice(index + 1);
+  }
+  return lines;
+}
+
+function completionSatisfied(taskBody, runs = []) {
+  const body = sectionBody(bodyLines(taskBody), "## Completion");
+  if (body && body.replace(/\s+/g, " ").length >= COMPLETION_MIN_LENGTH) return { ok: true, via: "section" };
+  for (const run of runs) {
+    const runBody = String(run.body || "");
+    const summary = sectionBody(bodyLines(runBody), "## Technical Summary");
+    if (summary && summary.replace(/\s+/g, " ").length >= COMPLETION_MIN_LENGTH) {
+      return { ok: true, via: `run:${run.id || "unknown"}` };
+    }
+  }
+  return { ok: false };
+}
+
+function validateTaskArtifact(artifact, options = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!artifact || !artifact.record) return { errors, warnings };
+  const record = artifact.record;
+  const source = artifact.body != null ? artifact.body : (artifact.source || "");
+  const lines = bodyLines(source);
+  const required = REQUIRED_SECTIONS[record.kind] || [];
+  const schemaOptIn = Number(record.task_schema || 0) >= 1;
+  if (schemaOptIn) {
+    for (const heading of required) {
+      if (findSectionLine(lines, heading) === -1) {
+        errors.push({
+          code: "SR-E-452",
+          message: `${record.id}: missing required section "${heading}".`,
+          file: artifact.file || null,
+          line: null
+        });
+      }
+    }
+  }
+  if (schemaOptIn && record.kind === "task" && record.status === "completed") {
+    const runs = options.runsByTask ? options.runsByTask[record.id] || [] : [];
+    const result = completionSatisfied(source, runs);
+    if (!result.ok) {
+      const line = findSectionLine(lines, "## Completion");
+      errors.push({
+        code: "SR-E-453",
+        message: `${record.id} is completed but lacks a non-empty "## Completion" (min ${COMPLETION_MIN_LENGTH} chars) and no associated Run carries a "## Technical Summary".`,
+        file: artifact.file || null,
+        line: line === -1 ? null : line
+      });
+    }
+  }
+  if (schemaOptIn && record.kind === "task" && ["running", "in_progress", "validating", "learning"].includes(record.status)) {
+    const git = options.gitContext;
+    if (git && git.isRepo) {
+      const branch = record.branch || (record.git && record.git.branch);
+      if (!branch) {
+        warnings.push({
+          code: "SR-E-454",
+          message: `${record.id} is ${record.status} inside a git repository but has no git.branch recorded in frontmatter. Reconcile with \`scrumrun repair --apply\` or add \`git: { branch, base_sha }\`.`,
+          file: artifact.file || null
+        });
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+function validateArtifacts(artifacts, options = {}) {
+  const runsByTask = {};
+  for (const artifact of artifacts) {
+    if (!artifact || !artifact.record) continue;
+    if (artifact.record.kind !== "run") continue;
+    const taskId = artifact.record.task;
+    if (!taskId) continue;
+    if (!runsByTask[taskId]) runsByTask[taskId] = [];
+    runsByTask[taskId].push({ id: artifact.record.id, body: (artifact.body != null ? artifact.body : (artifact.source || "")) });
+  }
+  const errors = [];
+  const warnings = [];
+  for (const artifact of artifacts) {
+    const result = validateTaskArtifact(artifact, { ...options, runsByTask });
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return { errors, warnings };
+}
+
+module.exports = {
+  REQUIRED_SECTIONS,
+  COMPLETION_MIN_LENGTH,
+  validateTaskArtifact,
+  validateArtifacts,
+  findSectionLine,
+  sectionBody,
+  bodyLines
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scrumrun",
-  "version": "3.1.2",
-  "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
+  "version": "4.1.0",
+  "description": "Markdown-first Agile memory and guardrails for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",
     "sr-claude": "bin/claude-install.js"

package/scripts/generate-contract-docs.js

@@ -69,7 +69,7 @@ Every artifact also requires \`id\`, \`kind\`, \`status\`, \`created\`, \`update
 |---|---|---|---|
 ${relationRows.join("\n")}
 
-Task is the atomic unit. A Task may have zero or one Sprint. A Task may have many Runs, but every Run belongs to exactly one Task and has a monotonically increasing attempt number within that Task. Sprint membership is authoritative on \`Task.sprint\`; a Sprint's \`## Tasks\` list is a human-readable projection that must agree with it.
+Task is the atomic unit. A Task may have zero or one Sprint. A Run is optional Markdown history and may reference either a Task or a Sprint; it never controls Task status in Markdown-first work. Sprint membership is authoritative on \`Task.sprint\`; a Sprint's \`## Tasks\` list is a human-readable projection that must agree with it. Additional owner-defined relations such as \`depends_on: [TASK-014, DEC-018]\` are preserved as local Markdown graph data.
 
 ## Scalar constraints
 
@@ -85,7 +85,7 @@ Newly authored Runs use \`ledger: ${RUN_LEDGER_VERSION}\`. Their \`## Events\` s
 
 Every event requires \`schema\`, \`id\`, contiguous \`sequence\`, RFC3339 \`occurred_at\`, \`timestamp_precision\`, \`actor\`, \`from\`, \`to\`, \`reason\`, and structured \`evidence\`. Event types are ${RUN_EVENT_TYPES.map((value) => `\`${value}\``).join(", ")}. Evidence kinds are ${RUN_EVIDENCE_KINDS.map((value) => `\`${value}\``).join(", ")}.
 
-A native ledger begins with \`created → executing\`; an evidenced migration \`snapshot\` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+A native ledger begins with \`created → executing\`; an evidenced migration \`snapshot\` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated when a strict audit Run is used. Run owns optional event history; Task Markdown owns the delivered scope and status in normal work.
 
 ## Truth questions
 
@@ -97,6 +97,10 @@ ${Object.entries(TRUTH_OWNERSHIP).map(([kind, owner]) => `- **${kind}:** ${owner
 |---|---|
 ${lifecycleRows.join("\n")}
 
+## Declarative Guardrail enforcement
+
+Project Guardrails may include an optional fenced \`yaml enforcement\` block. Its restricted, dependency-free YAML schema is defined normatively in \`SPEC.md §6.1\`: \`match.paths[]\`, \`match.diff[]\`, \`match.symbols[]\`, \`on_violation\` (\`block\` or \`warn\`), \`severity\`, and optional \`evidence\`. The pure evaluator consumes only that normalized rule data and a supplied ChangeSet; it has no network or LLM dependency. Prose-only Guardrails remain valid.
+
 ## Projections
 
 \`state.md\`, \`map.md\`, context packages, and \`.cache/\` are disposable. They may summarize or index canonical artifacts, but they cannot introduce status, policy, relations, decisions, or knowledge.

package/templates/project/.scrumrun/config.md

@@ -7,7 +7,16 @@ Interaction Mode: guided
 Execution Approval: always
 Quick Tasks: ask
 Agent Identity: agent
+watcher.enabled: false
+watcher.debounce_ms: 250
+watcher.poll_interval_ms: 1500
+memory.compaction.threshold: 0.6
+memory.compaction.min_members: 3
 
 These are operating preferences. They can never weaken `.scrumrun/guardrails.md`.
 
 `Agent Identity` is the default agent name recorded as the Task `assignee` and Run event `actor`. In shared teams, prefer the per-agent `SCRUMRUN_AGENT` environment variable over this project-wide default.
+
+`watcher.enabled` is opt-in. When enabled, `scrumrun config watch --start` keeps only generated `state.md`, `map.md`, and `.cache/` projections fresh; it never writes canonical Markdown.
+
+`memory.compaction.*` controls an explicitly invoked, deterministic Dossier suggestion. It never calls an LLM, runs automatically, or deletes memory records.

package/templates/project/.scrumrun/method.json

@@ -1,6 +1,9 @@
 {
   "method": "2.0.0",
   "layout": "v2",
+  "workflow": {
+    "daily": "markdown-first"
+  },
   "paths_schema": 1,
   "paths": {
     "guardrails": "guardrails.md",

package/templates/project/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 3.1 — Markdown-first
+## ScrumRun 4.0 — execution-first Markdown
 
 This project uses ScrumRun. The method is mandatory; the direct CLI is `scrumrun <noun> <subject> <action>`. `/sc` is only an optional client shortcut.
 
@@ -15,18 +15,24 @@ Natural-language product requests begin with a read-only understanding pass. Bef
 
 After approval:
 
-- Task is the atomic work item; create or refine its Markdown directly, define its `## Acceptance Criteria`, and retain a short `## Technical Summary` / `## Follow-ups` handoff;
+- execute continuously until the approved Task is delivered: keep working through discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status and must be followed immediately by more execution; it never closes the workflow. Do not stop to send an inventory, a progress report, a decomposition, or a list of work still to do. A missing implementation found during the work remains work to do now, not a follow-up, a “next step”, or a reason to reply. Stop only for an owner decision, external access, an explicit Guardrail, a security/secret risk, destructive work without approval, or an unmet required Acceptance Criterion;
+- Task is the atomic work item; create or refine its Markdown directly, define a short `## Done when` delivery contract, and retain a short `## Completion` / `## Follow-ups` handoff;
+- you may decompose implementation privately or add linked child Tasks when needed, but do not make the owner manage that decomposition and do not stop after planning it;
 - validation is scoped: only a test/review/environment explicitly required by the owner, the Task's Acceptance Criteria, or an active Guardrail can block completion; a missing optional E2E suite is a documented follow-up/risk, never a reason to fail an otherwise accepted Task;
 - Feature and Sprint remain useful organization, but are optional; create them only when they clarify real initiative or timebox context;
 - Sprint is only a real timebox/batch of Tasks;
 - Run is an optional audit/handoff record, never an administrative prerequisite to start, amend, or complete a Task; preserve useful prior attempts but do not let missing/invalid Run metadata stop work;
-- record a `## Technical Summary` at completion so the next agent inherits what was done; record optional missing coverage in `## Follow-ups`;
+- only claim a condition validated when the check actually covers that condition; a narrow checker never proves a broad delivery claim. Record a `## Completion` at completion so the next agent inherits what was done; `## Follow-ups` may contain only work outside the approved `## Done when`, never unfinished acceptance work;
 - work directly in code and Task Markdown after approval; do not call `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution;
 - use the CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, or release checks. It audits/repairs the folder; it does not own the daily workflow;
 - never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` in normal work. A failed legacy Run due to administrative state remains historical; write the corrected delivery outcome directly in the Task instead;
-- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights when the work reveals reusable context;
+- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights after delivery, or only when it materially helps the current implementation; it never interrupts execution;
 - guardrails remain mandatory: stop only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Status vocabulary, missing Runs, unavailable optional tests, and stale generated state are warnings to reconcile, not blockers.
 
+`core.md` and `guardrails.md` are sealed policy. Never edit either during a product Task. A policy change requires an explicit owner request; after review, seal it at the maintenance edge with `scrumrun update --project --seal-policy`.
+
+Artifacts are local Markdown connected by stable IDs and relative links. Preserve any owner-defined frontmatter and sections in a Task. A Guardrail may require sections such as `## Migration Plan`, `## Rollback`, or `## Guardrail Evidence`; add them only to the affected Task.
+
 Never bypass guardrails, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.
 
 Never use `npx scrumrun@latest` in the normal work loop. If the installed CLI is unavailable, stop and report that blocker rather than substituting a network command.

package/templates/project-lean/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 3.1 lean read policy — Markdown-first
+## ScrumRun 4.0 lean read policy — execution-first Markdown
 
 This project stores the complete ScrumRun v2 truth but uses a bounded default read path:
 
@@ -11,12 +11,16 @@ This project stores the complete ScrumRun v2 truth but uses a bounded default re
 
 Do not scan every Task, Run, Sprint, Feature, or Memory file by default. Generated `state.md`, `map.md`, and `.cache/` guide retrieval but never override canonical Markdown.
 
-Natural-language product work begins as a read-only understanding pass. Explicit approval authorizes direct work in source files and `.scrumrun/` Markdown. Define the Task's `## Acceptance Criteria` before execution and record a `## Technical Summary` at completion. A Run is optional handoff/audit context, not a state machine that may prevent starting, amending, or completing work. A Sprint exists only for a real batch/timebox.
+Natural-language product work begins as a read-only understanding pass. Explicit approval authorizes direct work in source files and `.scrumrun/` Markdown. Execute continuously until the approved Task is delivered: keep working through discover → implement → verify → fix → verify. A progress report is allowed only when the owner asks for status and must be followed immediately by more execution; it never closes the workflow. Do not stop to provide an inventory, a partial progress report, or a list of remaining work. A missing implementation found during the work remains work to do now, not a follow-up or “next step”. Define a short `## Done when` delivery contract, record `## Completion` only at the end, and never move unfinished contract work to `## Follow-ups` without explicit owner approval. A Run is optional handoff/audit context, not a state machine that may prevent starting, amending, or completing work. A Sprint exists only for a real batch/timebox.
 
 Guardrails are mandatory, but administrative state is not: block only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Missing Runs, invalid legacy status vocabulary, stale generated views, and optional unrun tests are warnings to reconcile in Markdown. Record meaningful optional coverage gaps under `## Follow-ups`; they do not fail a delivered Task.
 
 `.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
 
+`core.md` and `guardrails.md` are sealed policy. Never edit them during a product Task. A policy change requires an explicit owner request and `scrumrun update --project --seal-policy` after review.
+
+Artifacts are local Markdown connected by stable IDs and relative links. Preserve owner-defined frontmatter and sections in each Task; Guardrails may require a section only on affected Tasks.
+
 Use the installed CLI only for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks. For daily product work, follow `.scrumrun/core.md` and edit the relevant Markdown directly.
 
 Never invoke `plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `plan task --start` during normal work. If an old Run says failed for an administrative reason, leave it as history and record the actual delivered outcome in the Task's Technical Summary and Follow-ups.

package/templates/shared/hooks/pre-commit

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+# Optional local hook. Copy to .git/hooks/pre-commit and chmod +x it.
+# It is intentionally offline: the evaluator reads only the staged Git diff.
+#
+# Cross-platform notes:
+# - macOS / Linux: works out of the box.
+# - Windows: Git for Windows ships an embedded POSIX shell, so this hook
+#   runs as-is when committing from any git client (Git Bash, VS Code,
+#   JetBrains, GitHub Desktop). No `chmod` is needed on NTFS.
+set -eu
+
+if command -v scrumrun >/dev/null 2>&1; then
+  exec scrumrun review artifact --run --staged
+fi
+
+echo "ScrumRun pre-commit hook skipped: scrumrun is not installed." >&2