scrumrun 4.0.0 → 4.1.1

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,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Markdown-first Agile memory and guardrails for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/scripts/generate-contract-docs.js

@@ -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/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

package/templates/shared/view.html

@@ -0,0 +1,281 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>ScrumRun View</title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #0f1115;
+    --panel: #171a21;
+    --border: #262a34;
+    --muted: #8b93a1;
+    --fg: #e6e9ef;
+    --accent: #5aa1ff;
+    --ok: #4ac68a;
+    --warn: #e9b949;
+    --err: #ef6f6f;
+    --mono: ui-monospace, "SF Mono", "Menlo", "Consolas", monospace;
+  }
+  @media (prefers-color-scheme: light) {
+    :root { --bg:#f7f8fa; --panel:#fff; --border:#e2e5ec; --muted:#5f6773; --fg:#0f1115; --accent:#1e6feb; }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  header { padding: 16px 24px; border-bottom: 1px solid var(--border); display: flex; align-items: baseline; gap: 16px; }
+  h1 { font-size: 18px; margin: 0; font-weight: 600; }
+  .sub { color: var(--muted); font-size: 12px; }
+  main { padding: 16px 24px; display: grid; gap: 16px; }
+  section { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 12px 16px; }
+  section h2 { margin: 0 0 8px; font-size: 13px; text-transform: uppercase; color: var(--muted); letter-spacing: .04em; font-weight: 600; }
+  .kanban { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }
+  .col h3 { margin: 0 0 8px; font-size: 12px; text-transform: uppercase; color: var(--muted); letter-spacing: .04em; }
+  .card { background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 8px 10px; margin-bottom: 8px; cursor: pointer; transition: border-color .15s; }
+  .card:hover { border-color: var(--accent); }
+  .card .id { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+  .card .title { font-size: 13px; margin-top: 2px; }
+  .card .meta { font-size: 11px; color: var(--muted); margin-top: 4px; display: flex; gap: 8px; flex-wrap: wrap; }
+  .badge { display: inline-block; padding: 1px 6px; border-radius: 3px; background: var(--border); font-size: 10px; font-family: var(--mono); }
+  .badge.type-fix { color: var(--err); }
+  .badge.type-feature { color: var(--accent); }
+  .badge.type-docs { color: var(--muted); }
+  .search { padding: 6px 10px; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); color: var(--fg); font: inherit; width: 240px; }
+  .empty { color: var(--muted); font-style: italic; padding: 8px 0; }
+  .err { color: var(--err); font-family: var(--mono); font-size: 12px; }
+  #detail { position: fixed; top: 0; right: 0; height: 100vh; width: min(560px, 60vw); background: var(--panel); border-left: 1px solid var(--border); padding: 16px 20px; overflow: auto; box-shadow: -6px 0 24px rgba(0,0,0,.15); transform: translateX(100%); transition: transform .18s; z-index: 10; }
+  #detail.open { transform: translateX(0); }
+  #detail pre { white-space: pre-wrap; word-break: break-word; font-family: var(--mono); font-size: 12px; background: var(--bg); padding: 10px; border-radius: 6px; border: 1px solid var(--border); }
+  #detail .close { float: right; background: none; border: 0; color: var(--muted); font-size: 20px; cursor: pointer; }
+  .list-item { padding: 6px 0; border-bottom: 1px dotted var(--border); cursor: pointer; }
+  .list-item:last-child { border-bottom: 0; }
+  .list-item:hover { color: var(--accent); }
+  .row { display: flex; justify-content: space-between; gap: 12px; font-size: 12px; }
+  .row .muted { color: var(--muted); }
+  .header-right { margin-left: auto; display: flex; gap: 12px; align-items: center; }
+</style>
+</head>
+<body>
+<header>
+  <h1>ScrumRun</h1>
+  <span class="sub" id="project-label">loading…</span>
+  <div class="header-right">
+    <input type="search" class="search" id="search" placeholder="filter by id or title" />
+  </div>
+</header>
+<main>
+  <section id="err-panel" style="display:none"><h2>Load error</h2><div class="err" id="err-msg"></div></section>
+  <section>
+    <h2>Tasks</h2>
+    <div class="kanban" id="kanban"></div>
+  </section>
+  <section>
+    <h2>Guardrails</h2>
+    <div id="guardrails"><div class="empty">loading…</div></div>
+  </section>
+  <section>
+    <h2>Recent Runs</h2>
+    <div id="runs"><div class="empty">loading…</div></div>
+  </section>
+  <section>
+    <h2>Decisions</h2>
+    <div id="decisions"><div class="empty">loading…</div></div>
+  </section>
+</main>
+<aside id="detail" aria-hidden="true">
+  <button class="close" id="detail-close" aria-label="close">×</button>
+  <div id="detail-body"></div>
+</aside>
+<script>
+(() => {
+  "use strict";
+  const STATUS_ORDER = ["backlog", "running", "in_progress", "validating", "learning", "blocked", "failed", "completed"];
+  const STATUS_LABELS = {
+    backlog: "Backlog",
+    running: "Running",
+    in_progress: "In progress",
+    validating: "Validating",
+    learning: "Learning",
+    blocked: "Blocked",
+    failed: "Failed",
+    completed: "Completed"
+  };
+
+  function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/.exec(text);
+    if (!match) return { record: {}, body: text };
+    const record = {};
+    for (const raw of match[1].split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const colon = line.indexOf(":");
+      if (colon === -1) continue;
+      const key = line.slice(0, colon).trim();
+      const value = line.slice(colon + 1).trim();
+      record[key] = value.replace(/^"(.*)"$/, "$1");
+    }
+    return { record, body: match[2].trimStart() };
+  }
+
+  async function tryFetch(url) {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) return null;
+      return await res.text();
+    } catch {
+      return null;
+    }
+  }
+
+  async function fetchArtifactsByPrefix(dir, prefix, cap = 999) {
+    const found = [];
+    // Try increasing IDs; stop after 3 consecutive misses beyond the last hit.
+    let consecutiveMisses = 0;
+    for (let i = 1; i <= cap && consecutiveMisses < 5; i += 1) {
+      const id = `${prefix}-${String(i).padStart(3, "0")}`;
+      const text = await tryFetch(`${dir}/${id}.md`);
+      if (text === null) {
+        consecutiveMisses += 1;
+        continue;
+      }
+      consecutiveMisses = 0;
+      const parsed = parseFrontmatter(text);
+      parsed.record.id = parsed.record.id || id;
+      parsed.file = `${dir}/${id}.md`;
+      found.push(parsed);
+    }
+    return found;
+  }
+
+  function extractHeading(body) {
+    const line = body.split(/\r?\n/).find((l) => l.trim().startsWith("# "));
+    return line ? line.replace(/^# /, "").trim() : "(untitled)";
+  }
+
+  function renderKanban(tasks) {
+    const bucket = {};
+    for (const task of tasks) {
+      const status = task.record.status || "backlog";
+      if (!bucket[status]) bucket[status] = [];
+      bucket[status].push(task);
+    }
+    const ordered = STATUS_ORDER.filter((s) => bucket[s] && bucket[s].length);
+    const container = document.getElementById("kanban");
+    container.innerHTML = "";
+    if (!ordered.length) { container.innerHTML = '<div class="empty">no tasks found</div>'; return; }
+    for (const status of ordered) {
+      const col = document.createElement("div");
+      col.className = "col";
+      col.innerHTML = `<h3>${STATUS_LABELS[status] || status} (${bucket[status].length})</h3>`;
+      for (const task of bucket[status]) {
+        const title = extractHeading(task.body);
+        const type = task.record.type || "task";
+        const branch = task.record.branch;
+        const card = document.createElement("div");
+        card.className = "card";
+        card.dataset.id = task.record.id;
+        card.innerHTML = `
+          <div class="id">${task.record.id}</div>
+          <div class="title"></div>
+          <div class="meta">
+            <span class="badge type-${type}">${type}</span>
+            ${branch ? `<span class="badge">${branch}</span>` : ""}
+            ${task.record.sprint ? `<span class="badge">${task.record.sprint}</span>` : ""}
+          </div>`;
+        card.querySelector(".title").textContent = title;
+        card.addEventListener("click", () => openDetail(task));
+        col.appendChild(card);
+      }
+      container.appendChild(col);
+    }
+  }
+
+  function renderList(id, items, format) {
+    const el = document.getElementById(id);
+    el.innerHTML = "";
+    if (!items.length) { el.innerHTML = '<div class="empty">none</div>'; return; }
+    for (const item of items) {
+      const row = document.createElement("div");
+      row.className = "list-item";
+      row.innerHTML = format(item);
+      row.addEventListener("click", () => openDetail(item));
+      el.appendChild(row);
+    }
+  }
+
+  function renderGuardrailsFromText(text) {
+    const el = document.getElementById("guardrails");
+    if (!text) { el.innerHTML = '<div class="empty">guardrails.md not found</div>'; return; }
+    const rules = [];
+    for (const match of text.matchAll(/^##\s+(GR-\d+)\s+-\s+(.+)$/gm)) {
+      rules.push({ id: match[1], title: match[2] });
+    }
+    el.innerHTML = rules.length
+      ? rules.map((r) => `<div class="row"><span>${r.id}</span><span class="muted">${r.title}</span></div>`).join("")
+      : '<div class="empty">no guardrails declared</div>';
+  }
+
+  function openDetail(artifact) {
+    const body = document.getElementById("detail-body");
+    const record = artifact.record || {};
+    const meta = Object.entries(record).map(([k, v]) => `${k}: ${v}`).join("\n");
+    body.innerHTML = `
+      <h2 style="margin-top:0;font-size:14px">${record.id || "(unknown)"}</h2>
+      <div class="sub" style="margin-bottom:10px">${extractHeading(artifact.body || "")}</div>
+      <pre>${escape(meta)}</pre>
+      <pre>${escape(artifact.body || "")}</pre>
+      <div class="sub"><a href="${artifact.file || "#"}" target="_blank" rel="noopener">open raw file</a></div>`;
+    document.getElementById("detail").classList.add("open");
+    document.getElementById("detail").setAttribute("aria-hidden", "false");
+  }
+
+  function escape(s) { return String(s).replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c])); }
+
+  document.getElementById("detail-close").addEventListener("click", () => {
+    document.getElementById("detail").classList.remove("open");
+    document.getElementById("detail").setAttribute("aria-hidden", "true");
+  });
+
+  document.getElementById("search").addEventListener("input", (event) => {
+    const q = event.target.value.trim().toLowerCase();
+    for (const card of document.querySelectorAll(".card")) {
+      const text = card.textContent.toLowerCase();
+      card.style.display = !q || text.includes(q) ? "" : "none";
+    }
+  });
+
+  async function boot() {
+    const label = document.getElementById("project-label");
+    const [tasks, runs, decisions, guardrailsText, methodText, stateText] = await Promise.all([
+      fetchArtifactsByPrefix("tasks", "TASK", 999),
+      fetchArtifactsByPrefix("runs", "RUN", 999),
+      fetchArtifactsByPrefix("memory/decisions", "DEC", 999),
+      tryFetch("guardrails.md"),
+      tryFetch("method.json"),
+      tryFetch("state.md")
+    ]);
+    if (methodText) {
+      try { const m = JSON.parse(methodText); label.textContent = `method ${m.method || "?"} · ${tasks.length} tasks · ${runs.length} runs`; }
+      catch { label.textContent = `${tasks.length} tasks · ${runs.length} runs`; }
+    } else {
+      label.textContent = `${tasks.length} tasks · ${runs.length} runs`;
+    }
+    if (!tasks.length && !runs.length && !guardrailsText && !stateText) {
+      document.getElementById("err-panel").style.display = "";
+      document.getElementById("err-msg").textContent = "No .scrumrun/ artifacts loaded. If you are viewing via file:// and your browser blocks local fetch, serve the folder: cd .scrumrun && python3 -m http.server 8080, then open http://localhost:8080/view.html";
+      return;
+    }
+    renderKanban(tasks);
+    renderList("runs", runs.slice().reverse().slice(0, 20), (r) => `<div class="row"><span>${r.record.id}</span><span class="muted">${extractHeading(r.body)}</span></div>`);
+    renderList("decisions", decisions, (d) => `<div class="row"><span>${d.record.id}</span><span class="muted">${extractHeading(d.body)}</span></div>`);
+    renderGuardrailsFromText(guardrailsText);
+  }
+
+  boot().catch((error) => {
+    document.getElementById("err-panel").style.display = "";
+    document.getElementById("err-msg").textContent = String(error && error.message || error);
+  });
+})();
+</script>
+</body>
+</html>