scrumrun 3.1.2 → 4.1.0

package/templates/shared/skills/scrumrun/SKILL.md

@@ -3,7 +3,9 @@ name: scrumrun
 description: Use when initializing or migrating ScrumRun, handling product requests, planning or executing Tasks/Sprints/Features/Runs, managing guardrails or semantic memory, checking status, and running reviews.
 ---
 
-# ScrumRun 2.0
+# ScrumRun 4.0 — execution-first Markdown
+
+Package 4.0 implements the stable ScrumRun method contract 2.0.0.
 
 ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical shell command is:
 
@@ -36,9 +38,11 @@ Normal hot path:
 5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `scrumrun knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-**Markdown is the daily runtime.** After approval, work directly in source files and the relevant `.scrumrun/` Markdown. Create/refine the Task, its acceptance criteria, technical summary, follow-ups, and optional Run handoff without waiting for a CLI transition. Do not invoke `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution. The CLI is optional maintenance for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks.
+**Markdown is the daily runtime.** After approval, work directly in source files and the relevant `.scrumrun/` Markdown until the approved Task is delivered. Continue the full loop — discover → implement → verify → fix → verify — before responding. A progress report is allowed only when the owner asks for status and must be followed immediately by further execution; it never ends the Task. Do not stop to issue a progress report, inventory, decomposition, or list of remaining work; those are internal implementation steps. A missing implementation discovered in scope remains required work now, never a follow-up or a “next step”. Stop only for an owner decision, external access, an explicit Guardrail, security/secret risk, destructive work without approval, or an unmet required delivery criterion. Do not invoke `npx scrumrun@latest` or normal `scrumrun plan/run` commands during execution. The CLI is optional maintenance for `init`, `update --project`, `migrate`, `repair`, `doctor`, reports, and release checks.
+
+**Do not block on administrative state.** A missing/invalid Run, legacy status vocabulary, stale generated view, or optional unrun test is a warning to reconcile in Markdown, not a reason to refuse productive work. Define a concise `## Done when` delivery contract. `## Follow-ups` is only for work outside that contract: never relabel an unfinished requirement as a follow-up without explicit owner approval. Optional E2E/integration/review coverage belongs there or in a risk note, never in a fabricated failed Run.
 
-**Do not block on administrative state.** A missing/invalid Run, legacy status vocabulary, stale generated view, or optional unrun test is a warning to reconcile in Markdown, not a reason to refuse productive work. Block only for an explicit Guardrail, security/secret risk, destructive action without approval, or an unmet required Acceptance Criterion. Optional E2E/integration/review coverage belongs in `## Follow-ups` or a risk note, never in a fabricated failed Run.
+**A check must prove its claim.** A passing narrow checker does not prove a broader Task condition. If the task says no visible hardcoded literals, scan the relevant source, replace every in-scope match, and re-run that scan plus the build. Apply the same coverage rule to all completion claims.
 
 **Normal-operation command ban.** Do not invoke `scrumrun plan run --fail`, `--block`, `--retry`, `--finalize`, `--complete`, `--validate`, or `scrumrun plan task --start` during ordinary work. Those are optional strict-audit tools and cannot be used to decide whether a Task is delivered. If an old Run is already failed for an administrative reason, leave it as historical evidence, continue the Task directly, and write the corrected outcome in the Task's Technical Summary and Follow-ups.
 
@@ -104,11 +108,11 @@ During execution:
 
 1. keep the change inside the approved Task scope;
 2. preserve existing owner work and unrelated dirty files;
-3. define or confirm the Task's `## Acceptance Criteria` before execution and check them off as evidence;
-4. work normally: edit code and update the Task's `## Technical Summary`, `## Follow-ups`, and any Guardrail evidence required by an active rule;
+3. define or confirm the Task's short `## Done when` contract before execution and use it as the only delivery boundary;
+4. work normally and continuously. Privately decompose work or create linked child Tasks when useful, but do not return after planning; edit code until the contract is satisfied;
 5. validate in proportion to risk and against the acceptance criteria. Tests, reviews, and environments are required only when the owner, Acceptance Criteria, or an active Guardrail says so. Do not fail or block an otherwise accepted Task merely because an optional E2E/integration suite does not exist or was not run;
 6. run a configured reviewer only when a Guardrail requires it;
-7. complete the Task directly in Markdown after the required work is satisfied; use CLI release/doctor/repair commands only when their audit or recovery value is wanted;
+7. complete the Task directly in Markdown after the required work is satisfied, adding a concise `## Completion`; use CLI release/doctor/repair commands only when their audit or recovery value is wanted;
 8. use path-scoped Mutation Gateway commands only when the owner explicitly requests strict execution.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
@@ -117,7 +121,7 @@ When work remains queued, the briefing may name the next backlog Task. The owner
 
 Every explicit Guardrail remains mandatory. In strict mode, the CLI final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
 
-Task Markdown is the daily operational handoff authority. A structured Run is optional strict audit history only. Early v2 prose Runs may be repaired/migrated explicitly, but their state never overrides the Task's direct handoff or blocks approved work.
+Task Markdown is the daily operational handoff authority. A structured Run is optional strict audit history only. `core.md` and `guardrails.md` are sealed policy: never edit either during product work. A policy change requires an explicit owner request and the owner seals reviewed changes with `scrumrun update --project --seal-policy`. Early v2 prose Runs may be repaired/migrated explicitly, but their state never overrides the Task's direct handoff or blocks approved work.
 
 Linked canonical writes use the ignored durable transaction journal. An interrupted prepared mutation rolls back before the next approved mutation; a committed journal is verified and finalized. Audit remains read-only and reports pending recovery. Use `doctor --recover` only when explicitly requested, and never overwrite bytes changed after interruption.
 

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>

package/types/index.d.ts

@@ -21,7 +21,7 @@ export type ArtifactKind =
 
 export type ArtifactStatus =
   | "backlog" | "proposed" | "active" | "completed" | "paused" | "cancelled"
-  | "running" | "validating" | "learning" | "partial" | "failed" | "blocked"
+  | "running" | "in_progress" | "validating" | "learning" | "partial" | "failed" | "blocked"
   | "candidate" | "approved" | "rejected" | "deprecated" | "invalidated"
   | "open" | "resolved" | "confirmed" | "stale" | "archived" | "executing" | "passed";