scrumrun 4.1.4 → 4.2.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 4.2.0 - 2026-09-22
+
+### Added
+
+- **`scrumrun sync`.** Team-first git wrapper: fetches the remote, rebases the current branch, refreshes `state.md`, and optionally runs `repair --apply` (with `--repair --apply`). Refuses cleanly when the tree is dirty, when git isn't set up, when there's no remote, or when HEAD is detached — so no half-applied merges. Returns structured JSON so wrappers can automate.
+- **`scrumrun lock <acquire|release|status|reap> [ARTIFACT-ID]`.** Cooperative soft locks under `.scrumrun/.locks/<ID>.lock`. Auto-expire after 15 minutes (configurable via `--ttl <minutes>`). Non-owner release is refused unless `--force`. `status` (without id) lists every active lock; `reap` sweeps expired locks. Advisory only — never gates writes, but surfaces "who's touching what" for teams working on the same repo. Owner detected from `SCRUMRUN_AGENT`/`USER`/`USERNAME`.
+- **`scrumrun view` visual polish.** Kanban / Compact / List mode toggle in the toolbar (persisted in `localStorage`). Per-column scroll containers so a huge Completed column doesn't stretch the whole grid. Card hover elevation, larger titles, rounded corners, count pills next to status headers. Cards now render `@assignee` as a highlighted chip and expose `data-assignee` for `?assignee=<name>` filtering. `?readonly=1` disables interactive affordances for stakeholder viewing.
+
 ## 4.1.4 - 2026-09-22
 
 ### 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:** `4.1.4` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `4.2.0` · **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

@@ -65,6 +65,8 @@ Usage:
   scrumrun init [--local|--shared] [--lean] [--no-agent-hint] [--force]
   scrumrun status
   scrumrun view [--port 8080] [--host 127.0.0.1] [--no-open]
+  scrumrun sync [--repair] [--apply]
+  scrumrun lock <acquire|release|status|reap> [ARTIFACT-ID] [--note "..."] [--ttl <minutes>] [--force]
   scrumrun core [--path|--prompt]
   scrumrun commands
   scrumrun migrate --to 2 --dry-run
@@ -2750,6 +2752,53 @@ if (!command || command === "--help" || command === "-h") {
   } else {
     initProject({ force, mode: shared ? "shared" : "local", agentHint: shared || !noAgentHint, lean });
   }
+} else if (command === "sync") {
+  try {
+    const { sync } = require(path.join(root, "lib", "team", "sync"));
+    const result = sync(process.cwd(), {
+      autoRepair: args.includes("--repair"),
+      apply: args.includes("--apply")
+    });
+    console.log(JSON.stringify(result, null, 2));
+    if (["dirty", "fetch-failed", "rebase-conflict", "no-project", "no-git", "no-remote", "detached"].includes(result.status)) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(`sync failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+} else if (command === "lock") {
+  try {
+    const locks = require(path.join(root, "lib", "team", "locks"));
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    if (!fs.existsSync(scrumDir)) throw new Error("ScrumRun project not initialized.");
+    const action = args[1];
+    const id = args[2];
+    if (action === "--status" || action === "status") {
+      console.log(JSON.stringify(locks.status(scrumDir, id), null, 2));
+    } else if (action === "--acquire" || action === "acquire") {
+      if (!id) throw new Error("Usage: scrumrun lock acquire <ARTIFACT-ID> [--note \"...\"] [--ttl <minutes>]");
+      const noteIdx = args.indexOf("--note");
+      const ttlIdx = args.indexOf("--ttl");
+      const note = noteIdx !== -1 ? args[noteIdx + 1] : null;
+      const ttlMs = ttlIdx !== -1 ? Number(args[ttlIdx + 1]) * 60 * 1000 : undefined;
+      const result = locks.acquire(scrumDir, id, { note, ttlMs });
+      console.log(JSON.stringify(result, null, 2));
+      if (result.status === "conflict") process.exitCode = 1;
+    } else if (action === "--release" || action === "release") {
+      if (!id) throw new Error("Usage: scrumrun lock release <ARTIFACT-ID> [--force]");
+      const result = locks.release(scrumDir, id, { force: args.includes("--force") });
+      console.log(JSON.stringify(result, null, 2));
+      if (result.status === "denied") process.exitCode = 1;
+    } else if (action === "--reap" || action === "reap") {
+      console.log(JSON.stringify(locks.reapExpired(scrumDir), null, 2));
+    } else {
+      console.log("Usage: scrumrun lock <acquire|release|status|reap> [ARTIFACT-ID] [--note \"...\"] [--ttl <minutes>] [--force]");
+    }
+  } catch (error) {
+    console.error(`lock failed: ${error.message}`);
+    process.exitCode = 1;
+  }
 } else if (command === "view") {
   (async () => {
     try {

package/lib/team/locks.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const DEFAULT_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+function locksDir(scrumDir) {
+  return path.join(scrumDir, ".locks");
+}
+
+function lockFile(scrumDir, artifactId) {
+  if (!/^[A-Z]+-[a-z0-9]+$/i.test(String(artifactId || ""))) {
+    throw new Error(`Invalid artifact id for lock: ${artifactId}`);
+  }
+  return path.join(locksDir(scrumDir), `${artifactId}.lock`);
+}
+
+function currentOwner() {
+  return process.env.SCRUMRUN_AGENT
+    || process.env.USER
+    || process.env.USERNAME
+    || os.userInfo().username
+    || "unknown";
+}
+
+function readLock(scrumDir, artifactId) {
+  const file = lockFile(scrumDir, artifactId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    return { ...parsed, file, id: artifactId };
+  } catch { return null; }
+}
+
+function isExpired(lock, now = Date.now()) {
+  if (!lock || !lock.expires_at) return true;
+  return Date.parse(lock.expires_at) <= now;
+}
+
+function acquire(scrumDir, artifactId, { owner = null, ttlMs = DEFAULT_TTL_MS, note = null } = {}) {
+  fs.mkdirSync(locksDir(scrumDir), { recursive: true });
+  const existing = readLock(scrumDir, artifactId);
+  const now = Date.now();
+  const nextOwner = owner || currentOwner();
+  if (existing && !isExpired(existing, now) && existing.owner !== nextOwner) {
+    return {
+      status: "conflict",
+      lock: existing,
+      message: `${artifactId} is locked by ${existing.owner} until ${existing.expires_at}.`
+    };
+  }
+  const payload = {
+    id: artifactId,
+    owner: nextOwner,
+    acquired_at: new Date(now).toISOString(),
+    expires_at: new Date(now + ttlMs).toISOString(),
+    note: note || null
+  };
+  fs.writeFileSync(lockFile(scrumDir, artifactId), JSON.stringify(payload, null, 2) + "\n");
+  return { status: "acquired", lock: payload };
+}
+
+function release(scrumDir, artifactId, { owner = null, force = false } = {}) {
+  const existing = readLock(scrumDir, artifactId);
+  if (!existing) return { status: "not-locked" };
+  const requester = owner || currentOwner();
+  if (!force && existing.owner !== requester && !isExpired(existing)) {
+    return {
+      status: "denied",
+      lock: existing,
+      message: `${artifactId} is locked by ${existing.owner}. Use --force to override.`
+    };
+  }
+  try { fs.unlinkSync(existing.file); } catch { /* already gone */ }
+  return { status: "released", lock: existing };
+}
+
+function status(scrumDir, artifactId) {
+  if (artifactId) {
+    const lock = readLock(scrumDir, artifactId);
+    if (!lock) return { status: "not-locked", id: artifactId };
+    return { status: isExpired(lock) ? "expired" : "locked", lock };
+  }
+  const dir = locksDir(scrumDir);
+  if (!fs.existsSync(dir)) return { status: "empty", locks: [] };
+  const now = Date.now();
+  const locks = fs.readdirSync(dir)
+    .filter((name) => name.endsWith(".lock"))
+    .map((name) => {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+        return { ...parsed, expired: isExpired(parsed, now) };
+      } catch { return null; }
+    })
+    .filter(Boolean);
+  return { status: "listed", locks };
+}
+
+function reapExpired(scrumDir) {
+  const dir = locksDir(scrumDir);
+  if (!fs.existsSync(dir)) return { removed: 0 };
+  let removed = 0;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".lock")) continue;
+    const file = path.join(dir, name);
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (isExpired(parsed)) { fs.unlinkSync(file); removed += 1; }
+    } catch { /* skip malformed */ }
+  }
+  return { removed };
+}
+
+module.exports = { acquire, release, status, readLock, isExpired, reapExpired, currentOwner, DEFAULT_TTL_MS };

package/lib/team/sync.js

@@ -0,0 +1,115 @@
+"use strict";
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch (error) {
+    return { error: String(error && error.message || error), stderr: (error && error.stderr && error.stderr.toString()) || "" };
+  }
+}
+
+function isRepo(cwd) {
+  const inside = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  return typeof inside === "string" && inside === "true";
+}
+
+function detectRemote(cwd) {
+  const remotes = git(cwd, ["remote"]);
+  if (typeof remotes !== "string" || !remotes) return null;
+  const list = remotes.split(/\r?\n/).filter(Boolean);
+  if (list.includes("origin")) return "origin";
+  return list[0] || null;
+}
+
+function currentBranch(cwd) {
+  const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  return typeof branch === "string" ? branch : null;
+}
+
+function hasUncommittedChanges(cwd) {
+  const status = git(cwd, ["status", "--porcelain"]);
+  return typeof status === "string" && status.length > 0;
+}
+
+function sync(projectRoot, { autoRepair = false, apply = false, logger = console } = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir)) {
+    return { status: "no-project", message: "No .scrumrun/ directory. Run `scrumrun init` first." };
+  }
+  if (!isRepo(projectRoot)) {
+    return { status: "no-git", message: "Not a git repository. Sync requires git for team collaboration." };
+  }
+  const remote = detectRemote(projectRoot);
+  if (!remote) {
+    return { status: "no-remote", message: "No git remote configured. `git remote add origin <url>` first." };
+  }
+  const branch = currentBranch(projectRoot);
+  if (!branch || branch === "HEAD") {
+    return { status: "detached", message: "Detached HEAD state. Check out a branch first." };
+  }
+  if (hasUncommittedChanges(projectRoot)) {
+    return {
+      status: "dirty",
+      message: "Working tree has uncommitted changes. Commit or stash before sync.",
+      hint: "git status  #  see what's dirty"
+    };
+  }
+
+  logger.log(`sync: fetching ${remote}...`);
+  const fetch = git(projectRoot, ["fetch", remote, branch]);
+  if (typeof fetch !== "string") {
+    return { status: "fetch-failed", message: fetch.error, stderr: fetch.stderr };
+  }
+
+  const behind = git(projectRoot, ["rev-list", "--count", `HEAD..${remote}/${branch}`]);
+  const ahead = git(projectRoot, ["rev-list", "--count", `${remote}/${branch}..HEAD`]);
+  const behindCount = typeof behind === "string" ? Number(behind) : 0;
+  const aheadCount = typeof ahead === "string" ? Number(ahead) : 0;
+
+  if (behindCount === 0) {
+    logger.log(`sync: already up to date with ${remote}/${branch} (ahead ${aheadCount}).`);
+    return { status: "up-to-date", behind: 0, ahead: aheadCount };
+  }
+
+  logger.log(`sync: rebasing onto ${remote}/${branch} (behind ${behindCount})...`);
+  const rebase = git(projectRoot, ["pull", "--rebase", remote, branch]);
+  if (typeof rebase !== "string") {
+    return {
+      status: "rebase-conflict",
+      message: "Rebase failed — likely a conflict in .scrumrun/. Resolve with git tools, then re-run.",
+      stderr: rebase.stderr
+    };
+  }
+
+  const result = { status: "synced", behind: behindCount, ahead: aheadCount };
+
+  if (autoRepair) {
+    logger.log("sync: running repair...");
+    try {
+      const { repair } = require("../commands/repair");
+      const rep = repair(scrumDir, { apply, recoverOrphanTasks: false });
+      result.repair = {
+        entries: (rep.plan && rep.plan.entries && rep.plan.entries.length) || 0,
+        applied: apply
+      };
+    } catch (error) {
+      result.repair_error = error.message;
+    }
+  }
+
+  try {
+    const { refreshState } = require("../runtime/orchestrator");
+    refreshState(scrumDir);
+    result.state_refreshed = true;
+  } catch (error) {
+    result.state_refresh_error = error.message;
+  }
+
+  return result;
+}
+
+module.exports = { sync, isRepo, detectRemote, currentBranch, hasUncommittedChanges };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "4.1.4",
+  "version": "4.2.0",
   "description": "Markdown-first Agile memory and guardrails for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/templates/shared/view.html

@@ -29,17 +29,41 @@
   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; }
+  .toolbar { display: flex; gap: 8px; align-items: center; margin-bottom: 12px; }
+  .toolbar .group { display: inline-flex; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; }
+  .toolbar button { background: transparent; border: 0; color: var(--muted); padding: 5px 10px; font: inherit; font-size: 12px; cursor: pointer; }
+  .toolbar button.active { background: var(--border); color: var(--fg); }
+  .toolbar button:hover { color: var(--fg); }
+  .kanban { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 14px; align-items: start; }
+  .kanban.compact { grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 10px; }
+  .col { min-width: 0; }
+  .col h3 { margin: 0 0 10px; font-size: 11px; text-transform: uppercase; color: var(--muted); letter-spacing: .06em; display: flex; align-items: center; gap: 6px; }
+  .col h3 .count { background: var(--border); color: var(--fg); padding: 1px 6px; border-radius: 10px; font-family: var(--mono); font-size: 10px; }
+  .col-body { max-height: 70vh; overflow-y: auto; padding-right: 4px; }
+  .col-body::-webkit-scrollbar { width: 6px; }
+  .col-body::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+  .card { background: var(--bg); border: 1px solid var(--border); border-radius: 8px; padding: 10px 12px; margin-bottom: 8px; cursor: pointer; transition: border-color .15s, transform .1s, box-shadow .15s; }
+  .card:hover { border-color: var(--accent); transform: translateY(-1px); box-shadow: 0 4px 12px rgba(0,0,0,.08); }
+  .card .id { font-family: var(--mono); font-size: 10px; color: var(--muted); letter-spacing: .04em; }
+  .card .title { font-size: 13.5px; font-weight: 500; margin-top: 3px; line-height: 1.35; color: var(--fg); }
+  .card .meta { font-size: 11px; color: var(--muted); margin-top: 8px; display: flex; gap: 5px; flex-wrap: wrap; }
+  .kanban.compact .card { padding: 7px 9px; }
+  .kanban.compact .card .title { font-size: 12.5px; }
+  .kanban.compact .card .meta { display: none; }
+  body.list-mode .kanban { display: block; }
+  body.list-mode .col { margin-bottom: 20px; }
+  body.list-mode .col-body { max-height: none; }
+  body.list-mode .card { display: grid; grid-template-columns: 100px 1fr auto; gap: 12px; align-items: center; padding: 8px 14px; }
+  body.list-mode .card .id { margin: 0; }
+  body.list-mode .card .title { margin: 0; }
+  body.list-mode .card .meta { margin: 0; justify-content: flex-end; }
+  body.readonly .card { cursor: default; }
+  body.readonly .card:hover { transform: none; }
   .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); }
+  .badge.assignee { color: var(--accent); background: color-mix(in oklab, var(--accent) 15%, transparent); }
   .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; }
@@ -67,6 +91,13 @@
   <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="toolbar">
+      <div class="group" role="tablist" aria-label="View mode">
+        <button data-mode="kanban" class="active">Kanban</button>
+        <button data-mode="compact">Compact</button>
+        <button data-mode="list">List</button>
+      </div>
+    </div>
     <div class="kanban" id="kanban"></div>
   </section>
   <section>
@@ -166,7 +197,10 @@
     for (const status of ordered) {
       const col = document.createElement("div");
       col.className = "col";
-      col.innerHTML = `<h3>${STATUS_LABELS[status] || status} (${bucket[status].length})</h3>`;
+      col.innerHTML = `<h3>${STATUS_LABELS[status] || status} <span class="count">${bucket[status].length}</span></h3>`;
+      const body = document.createElement("div");
+      body.className = "col-body";
+      col.appendChild(body);
       for (const task of bucket[status]) {
         const title = extractHeading(task.body);
         const type = task.record.type || "task";
@@ -174,17 +208,20 @@
         const card = document.createElement("div");
         card.className = "card";
         card.dataset.id = task.record.id;
+        const assignee = task.record.assignee;
+        card.dataset.assignee = assignee || "";
         card.innerHTML = `
           <div class="id">${task.record.id}</div>
           <div class="title"></div>
           <div class="meta">
             <span class="badge type-${type}">${type}</span>
+            ${assignee ? `<span class="badge assignee">@${assignee}</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);
+        body.appendChild(card);
       }
       container.appendChild(col);
     }
@@ -236,13 +273,42 @@
     document.getElementById("detail").setAttribute("aria-hidden", "true");
   });
 
-  document.getElementById("search").addEventListener("input", (event) => {
-    const q = event.target.value.trim().toLowerCase();
+  const params = new URLSearchParams(window.location.search);
+  const assigneeFilter = (params.get("assignee") || "").trim().toLowerCase();
+  const readonly = params.get("readonly") === "1";
+
+  function applyFilters() {
+    const q = (document.getElementById("search").value || "").trim().toLowerCase();
     for (const card of document.querySelectorAll(".card")) {
       const text = card.textContent.toLowerCase();
-      card.style.display = !q || text.includes(q) ? "" : "none";
+      const cardAssignee = (card.dataset.assignee || "").toLowerCase();
+      const matchesSearch = !q || text.includes(q);
+      const matchesAssignee = !assigneeFilter || cardAssignee === assigneeFilter;
+      card.style.display = matchesSearch && matchesAssignee ? "" : "none";
     }
-  });
+  }
+
+  document.getElementById("search").addEventListener("input", applyFilters);
+
+  const kanbanEl = document.getElementById("kanban");
+  const savedMode = localStorage.getItem("scrumrun.view.mode") || "kanban";
+  function setMode(mode) {
+    kanbanEl.classList.toggle("compact", mode === "compact");
+    document.body.classList.toggle("list-mode", mode === "list");
+    for (const button of document.querySelectorAll(".toolbar button")) {
+      button.classList.toggle("active", button.dataset.mode === mode);
+    }
+    localStorage.setItem("scrumrun.view.mode", mode);
+  }
+  for (const button of document.querySelectorAll(".toolbar button")) {
+    button.addEventListener("click", () => setMode(button.dataset.mode));
+  }
+  setMode(savedMode);
+  if (readonly) document.body.classList.add("readonly");
+  if (assigneeFilter) {
+    const label = document.getElementById("project-label");
+    label.textContent = label.textContent + ` · filter: @${assigneeFilter}`;
+  }
 
   async function boot() {
     const label = document.getElementById("project-label");
@@ -266,6 +332,7 @@
       return;
     }
     renderKanban(tasks);
+    applyFilters();
     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);