scrumrun 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.4.1 - 2026-07-23
+
+### Added
+
+- `sc plan intake` now renders a **pretty terminal layout** in interactive TTYs: a boxed intake pipeline with streaming stages, aligned Classification / Why / Risk / Deferred-guardrails fields, and a highlighted approval-command box that mirrors the LP replay. Zero-dep — pure ANSI + Unicode. Falls back automatically to the existing Markdown summary when stdout is piped, `NO_COLOR` is set, or `--plain` is passed. `--json` returns the full structured plan for automation.
+- New module `lib/commands/pretty-intake` exposes `canRenderPretty`, `renderIntake`, and `renderIntakePlain` for library consumers.
+
+### Changed
+
+- Manifest declares `--plain` and `--json` on `sc plan intake`.
+- Test suite grew from 177 to 184 passing (added contract tests for TTY detection, `NO_COLOR` / `FORCE_COLOR` overrides, backwards-compatible plain output, and blocked-plan rendering).
+
 ## 2.4.0 - 2026-07-23
 
 ### 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:** `2.4.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.4.1` · **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

@@ -1351,19 +1351,18 @@ function executeRootRoute(route) {
     }
     const request = routeArgs[0] === "--request" ? routeArgs.slice(1).join(" ") : routeArgs.join(" ");
     const plan = planRequest(process.cwd(), request);
-    console.log(`# ScrumRun Intake`);
-    console.log(`State: ${plan.state}`);
-    console.log(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
-    console.log(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
-    console.log(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
-    for (const violation of plan.policy.violations) console.log(`BLOCKED: ${violation}`);
-    for (const result of plan.policy.evaluations.filter((item) => item.status === "deferred")) {
-      console.log(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
+    if (routeArgs.includes("--json")) {
+      console.log(JSON.stringify(plan, null, 2));
+      return;
     }
-    for (const warning of plan.context.warnings) console.log(`WARNING: ${warning}`);
-    if (plan.approvalToken) {
-      console.log(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
+    const { canRenderPretty, renderIntake, renderIntakePlain } = require(path.join(root, "lib", "commands", "pretty-intake"));
+    const forcePlain = routeArgs.includes("--plain");
+    if (!forcePlain && canRenderPretty()) {
+      console.log(renderIntake(plan));
+    } else {
+      console.log(renderIntakePlain(plan));
     }
+    for (const warning of plan.context.warnings) console.log(`WARNING: ${warning}`);
     return;
   }
   if (noun === "plan" && subject === "task" && routeArgs[0] === "--retry") {

package/docs/QUICKSTART.md

@@ -58,6 +58,12 @@ proposals. Approving is one command:
 npx scrumrun@latest sc plan intake --approve <token>
 ```
 
+In an interactive terminal, the output is rendered as a boxed intake
+pipeline with the exact structure shown on the landing page. Pipe the
+command (`| less`, `> intake.txt`) or set `NO_COLOR=1` to get the plain
+Markdown summary instead; add `--json` for a fully structured payload
+you can feed to CI or a downstream tool.
+
 Only then does a Task and a Run get created.
 
 ## Watching the Run

package/lib/commands/manifest.js

@@ -24,7 +24,7 @@ const nouns = Object.freeze({
         "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
         "--block [--note] [--evidence] [--risk] [--actor] [--at]"
       ],
-      intake: ["<request>", "--request", "--approve"],
+      intake: ["<request>", "--request", "--approve", "--plain", "--json"],
       challenge: ["<question>"]
     }
   },

package/lib/commands/pretty-intake.js

@@ -0,0 +1,272 @@
+"use strict";
+
+// Pretty terminal renderer for `sc plan intake` and related outputs.
+// Zero-dep: pure ANSI escapes plus Unicode box drawing. Automatically
+// falls back to a plain, machine-friendly format when the environment
+// is not an interactive TTY (piped, redirected, NO_COLOR, --json, ...).
+//
+// Contract:
+//   canRenderPretty(stream?) -> boolean
+//   renderIntake(plan)       -> string   (pretty; assumes canRenderPretty)
+//   renderIntakePlain(plan)  -> string   (existing Markdown-style summary)
+
+const RESET = "\x1b[0m";
+
+const STYLES = {
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  underline: "\x1b[4m"
+};
+
+const FG = {
+  black: "\x1b[30m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightRed: "\x1b[91m",
+  brightCyan: "\x1b[96m"
+};
+
+// Signature acid lime (#c9ff5c) via 24-bit truecolor when available.
+const ACID_FG = "\x1b[38;2;201;255;92m";
+const DIM_ACID_FG = "\x1b[38;2;140;180;60m";
+
+function canRenderPretty(stream = process.stdout) {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR === "0") return false;
+  if (process.env.FORCE_COLOR && Number(process.env.FORCE_COLOR) > 0) return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+function paint(color, text) {
+  return `${color}${text}${RESET}`;
+}
+
+function stripAnsi(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function visibleLength(text) {
+  return stripAnsi(text).length;
+}
+
+function padEnd(text, width) {
+  const visible = visibleLength(text);
+  if (visible >= width) return text;
+  return text + " ".repeat(width - visible);
+}
+
+function terminalWidth(min = 60, max = 90) {
+  const columns = (process.stdout && process.stdout.columns) || 80;
+  return Math.max(min, Math.min(max, columns - 2));
+}
+
+function wrap(text, width) {
+  if (!text) return [""];
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (!current) {
+      current = word;
+      continue;
+    }
+    if ((current + " " + word).length <= width) {
+      current += " " + word;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.length ? lines : [""];
+}
+
+function boxTop(width, title) {
+  const label = ` ${title} `;
+  const remaining = width - visibleLength(label) - 4;
+  const left = "╭─";
+  const right = "─".repeat(Math.max(0, remaining)) + "─╮";
+  return paint(FG.gray, `${left}${paint(ACID_FG, label)}${paint(FG.gray, right)}`);
+}
+
+function boxBottom(width) {
+  return paint(FG.gray, `╰${"─".repeat(width - 2)}╯`);
+}
+
+function boxBlank(width) {
+  return paint(FG.gray, `│`) + " ".repeat(width - 2) + paint(FG.gray, `│`);
+}
+
+function boxLine(width, content) {
+  const paddedInterior = padEnd(content, width - 4);
+  return paint(FG.gray, `│ `) + paddedInterior + paint(FG.gray, ` │`);
+}
+
+const RISK_TONE = {
+  low: FG.brightGreen,
+  medium: FG.brightYellow,
+  high: FG.brightRed
+};
+
+const CLASSIFICATION_ALIAS = {
+  task: "Task",
+  fix: "Task (fix)",
+  sprint: "Sprint",
+  feature: "Feature",
+  backlog: "Backlog Task",
+  knowledge: "Knowledge discovery",
+  reject: "Rejected"
+};
+
+function classificationLabel(classification) {
+  const alias = CLASSIFICATION_ALIAS[classification.type];
+  return alias || classification.type;
+}
+
+function classificationLaneLabel(classification) {
+  const alias = CLASSIFICATION_ALIAS[classification.type];
+  if (alias) return alias.toLowerCase() + " lane";
+  return `${classification.type} lane`;
+}
+
+function pipelineDot(stage, blocked) {
+  const color = blocked && stage === "BLOCKED" ? FG.brightRed : ACID_FG;
+  return paint(color, "●");
+}
+
+function fieldLine(label, value, width, valueColor = FG.white, labelColor = FG.gray) {
+  const labelText = paint(labelColor, padEnd(label.padEnd(15).toUpperCase(), 15));
+  const wrapWidth = Math.max(20, width - 4 - 15 - 2);
+  const lines = wrap(value, wrapWidth);
+  const rendered = [];
+  for (let i = 0; i < lines.length; i++) {
+    const prefix = i === 0 ? labelText : padEnd("", 15);
+    rendered.push(boxLine(width, `${prefix}  ${paint(valueColor, lines[i])}`));
+  }
+  return rendered;
+}
+
+function commandBox(interiorWidth, command) {
+  const inside = ` $ ${command} `;
+  const boxWidth = Math.min(interiorWidth, visibleLength(inside) + 4);
+  const top = paint(DIM_ACID_FG, `┌${"─".repeat(boxWidth - 2)}┐`);
+  const bottom = paint(DIM_ACID_FG, `└${"─".repeat(boxWidth - 2)}┘`);
+  const content = padEnd(inside, boxWidth - 2);
+  const middle = `${paint(DIM_ACID_FG, "│")}${paint(ACID_FG, content)}${paint(DIM_ACID_FG, "│")}`;
+  return [top, middle, bottom];
+}
+
+function pipelineDetail(stage, plan) {
+  if (stage === "POLICY") {
+    return `${plan.policy.checked.length} checked · ${plan.policy.deferred.length} deferred`;
+  }
+  if (stage === "RISK") {
+    return `${plan.risk.level} · ${plan.risk.reasons[0] || ""}`.replace(/·\s*$/, "").trim();
+  }
+  if (stage === "CLASSIFICATION") {
+    return classificationLabel(plan.classification).toLowerCase();
+  }
+  if (stage === "AWAITING_APPROVAL") return "";
+  if (stage === "BLOCKED") return "policy denied — no token issued";
+  return "";
+}
+
+function renderIntake(plan) {
+  const width = terminalWidth();
+  const isBlocked = plan.state === "blocked";
+  const title = `intake pipeline · ${classificationLaneLabel(plan.classification)}`;
+  const lines = [];
+
+  lines.push(boxTop(width, title));
+  lines.push(boxBlank(width));
+
+  // Owner prompt
+  const promptLines = wrap(plan.request, width - 6);
+  for (let i = 0; i < promptLines.length; i++) {
+    const marker = i === 0 ? paint(ACID_FG, "❯ ") : "  ";
+    lines.push(boxLine(width, `  ${marker}${paint(FG.white, promptLines[i])}`));
+  }
+  lines.push(boxBlank(width));
+
+  // Pipeline
+  for (const stage of plan.pipeline) {
+    const upper = stage.toUpperCase();
+    const detail = pipelineDetail(upper, plan);
+    const dot = pipelineDot(upper, isBlocked);
+    const label = paint(isBlocked && upper === "BLOCKED" ? FG.brightRed : FG.white, padEnd(upper, 18));
+    const suffix = detail ? paint(FG.gray, detail) : "";
+    lines.push(boxLine(width, `  ${dot} ${label} ${suffix}`));
+  }
+  lines.push(boxBlank(width));
+
+  // Field summary
+  const classificationText = classificationLabel(plan.classification);
+  lines.push(...fieldLine("Classification", classificationText, width, ACID_FG));
+  lines.push(...fieldLine("Why", plan.classification.reason, width, FG.gray));
+  const riskColor = RISK_TONE[plan.risk.level] || FG.white;
+  lines.push(...fieldLine("Risk", `${plan.risk.level} · ${plan.risk.reasons.join("; ")}`, width, riskColor));
+
+  // Deferred guardrails
+  const deferred = plan.policy.evaluations.filter((entry) => entry.status === "deferred");
+  if (deferred.length) {
+    lines.push(boxBlank(width));
+    lines.push(boxLine(width, `  ${paint(FG.gray, "DEFERRED GUARDRAILS")}`));
+    for (const entry of deferred) {
+      const gr = paint(FG.brightYellow, entry.guardrail);
+      const code = paint(FG.gray, entry.code);
+      const short = entry.message.length > width - 30 ? entry.message.slice(0, width - 33) + "…" : entry.message;
+      lines.push(boxLine(width, `  ${gr} ${code}  ${paint(FG.white, short)}`));
+    }
+  }
+
+  // Approval or blocked
+  lines.push(boxBlank(width));
+  if (isBlocked) {
+    lines.push(boxLine(width, `  ${paint(FG.brightRed, "BLOCKED")} ${paint(FG.gray, "no approval token issued")}`));
+    if (plan.policy.violations && plan.policy.violations.length) {
+      for (const violation of plan.policy.violations) {
+        lines.push(boxLine(width, `  ${paint(FG.brightRed, "!")} ${paint(FG.white, violation)}`));
+      }
+    }
+  } else if (plan.approvalToken) {
+    const command = `scrumrun sc plan intake --approve ${plan.approvalToken}`;
+    const truncated = command.length > width - 8 ? `scrumrun sc plan intake --approve ${plan.approvalToken.slice(0, 20)}…` : command;
+    for (const boxRow of commandBox(width - 6, truncated)) {
+      lines.push(boxLine(width, `  ${boxRow}`));
+    }
+    lines.push(boxBlank(width));
+    lines.push(boxLine(width, `  ${paint(FG.gray, "[ awaiting owner approval ]")}`));
+    if (command.length !== truncated.length) {
+      lines.push(boxLine(width, `  ${paint(FG.gray, "(full token above is truncated for display; copy from --json if needed)")}`));
+    }
+  }
+  lines.push(boxBlank(width));
+  lines.push(boxBottom(width));
+  return lines.join("\n");
+}
+
+function renderIntakePlain(plan) {
+  const lines = [];
+  lines.push("# ScrumRun Intake");
+  lines.push(`State: ${plan.state}`);
+  lines.push(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
+  lines.push(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
+  lines.push(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
+  for (const violation of plan.policy.violations || []) lines.push(`BLOCKED: ${violation}`);
+  for (const result of plan.policy.evaluations.filter((entry) => entry.status === "deferred")) {
+    lines.push(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
+  }
+  for (const warning of plan.context.warnings) lines.push(`WARNING: ${warning}`);
+  if (plan.approvalToken) lines.push(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
+  return lines.join("\n");
+}
+
+module.exports = { canRenderPretty, renderIntake, renderIntakePlain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",