buildline 0.5.1 → 0.7.0

package/src/ui/index.html

@@ -55,7 +55,7 @@ main { padding: 16px 20px 40px; }
 .col .owner { display: block; font-size: 11px; font-weight: 500; color: var(--ink-3); text-transform: none; letter-spacing: 0; margin-top: 1px; }
 .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 10px 12px; margin-bottom: 8px; box-shadow: var(--shadow); cursor: pointer; display: block; width: 100%; text-align: left; }
 .card:hover { border-color: var(--accent); }
-.card .top { display: flex; gap: 6px; align-items: center; margin-bottom: 4px; }
+.card .top { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; margin-bottom: 4px; }
 .card .id { font: 12px var(--mono); color: var(--ink-3); }
 .card .title { font-weight: 600; line-height: 1.3; }
 .card .next { font-size: 12px; line-height: 1.35; color: var(--ink-2); margin-top: 6px; display: flex; gap: 6px; align-items: baseline; }
@@ -68,6 +68,20 @@ main { padding: 16px 20px 40px; }
 .who-designer { background: var(--blue-soft); color: var(--blue); }
 .who-eng, .who-agent { background: var(--green-soft); color: var(--green); }
 .who-human { background: var(--red-soft); color: var(--red); }
+.live { font-size: 12px; line-height: 1.4; margin-top: 6px; display: flex; gap: 6px; align-items: baseline; color: var(--ink-2); min-width: 0; }
+.live > span { min-width: 0; flex: 1; }
+.live .line { display: block; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.live .wrap { display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; }
+.live b { font-weight: 600; }
+.live.working b { color: var(--ink); }
+.live.waiting b, .live.blocked b { color: var(--red); }
+.live .dot { flex-shrink: 0; width: 8px; height: 8px; border-radius: 50%; background: var(--accent); align-self: center; animation: pulse 1.2s ease-in-out infinite; }
+.live.waiting .dot, .live.blocked .dot { background: var(--red); }
+.live.blocked .dot { animation: none; }
+.live code { font-size: 11px; background: none; padding: 0; }
+.card.is-working { border-color: var(--accent); }
+@keyframes pulse { 50% { opacity: .25; transform: scale(.7); } }
+@media (prefers-reduced-motion: reduce) { .live .dot { animation: none; } }
 .progress { height: 4px; background: var(--line); border-radius: 2px; overflow: hidden; margin-top: 8px; }
 .progress > i { display: block; height: 100%; background: var(--green); }
 .approvals { display: flex; gap: 4px; margin-top: 6px; flex-wrap: wrap; }
@@ -138,6 +152,7 @@ dialog h2 { margin: 0 0 12px; font-size: 17px; }
     <button role="tab" aria-selected="false" data-view="context">Context</button>
   </nav>
   <span class="spacer"></span>
+  <button class="btn" id="soundBtn" aria-pressed="true"></button>
   <button class="btn" id="whoami" title="Name used for approvals"></button>
   <button class="btn primary" id="newBtn">+ New</button>
 </header>
@@ -217,14 +232,33 @@ function md(src) {
 function card(f) {
   const tasks = f.tasks || [], done = tasks.filter((t) => t.passes).length;
   const ap = Object.keys(f.approvals || {});
-  return `<button class="card" data-id="${esc(f.id)}">
-    <div class="top"><span class="id">${esc(f.id)}</span><span class="chip type-${esc(f.type)}">${esc(f.type)}</span>${f.blocked ? '<span class="chip type-fix">blocked</span>' : ''}</div>
+  return `<button class="card${f.live?.working ? ' is-working' : ''}" data-id="${esc(f.id)}">
+    <div class="top"><span class="id">${esc(f.id)}</span><span class="chip type-${esc(f.type)}">${esc(f.type)}</span></div>
     <div class="title">${esc(f.title)}</div>
     ${tasks.length ? `<div class="progress" title="${done}/${tasks.length} tasks passing"><i style="width:${(done / tasks.length) * 100}%"></i></div>` : ''}
-    ${f.next?.text && f.status !== 'done' ? `<div class="next">${f.next.who ? `<span class="who who-${esc(f.next.who)}">${esc(f.next.who)}</span>` : ''}${esc(f.next.text)}</div>` : ''}
+    ${liveLine(f)}
+    ${f.next?.text && f.status !== 'done' && !f.blocked ? `<div class="next">${f.next.who ? `<span class="who who-${esc(f.next.who)}">${esc(f.next.who)}</span>` : ''}${esc(f.next.text)}</div>` : ''}
     ${ap.length ? `<div class="approvals">${ap.map((a) => `<span class="chip" title="by ${esc(f.approvals[a].by)}">✓ ${esc(a)}</span>`).join('')}</div>` : ''}
   </button>`;
 }
+const stationModel = (station) => { const m = S.config.models || {}; const v = m[station] ?? m.default; return v && v !== 'inherit' ? v : ''; };
+const ago = (ms) => (ms < 60e3 ? `${Math.max(1, Math.round(ms / 1000))}s` : ms < 3600e3 ? `${Math.round(ms / 60e3)}m` : `${Math.round(ms / 3600e3)}h`);
+/** What is happening on a feature right now: a blocker, a working session, or one waiting for a reply. */
+function liveLine(f) {
+  if (f.blocked) return `<div class="live blocked"><i class="dot"></i><span class="wrap"><b>Blocked:</b> ${esc(f.blocked)}</span></div>`;
+  const ses = f.live?.sessions || [];
+  const on = ses.filter((x) => x.state === 'working');
+  if (f.live?.working) {
+    const s = on[0];
+    if (!s) return `<div class="live working"><i class="dot"></i><span><b>Working</b> · files changing</span></div>`;
+    const model = String(s.model || stationModel(f.status) || '').replace(/^claude-/, '');
+    const head = [`<b>Working${on.length > 1 ? ` ×${on.length}` : ''}</b>`, ago(s.age), model && esc(model)].filter(Boolean).join(' · ');
+    const doing = s.tool ? `${esc(s.tool)} <code>${esc(s.detail || '')}</code>` : 'thinking';
+    return `<div class="live working" title="${esc([s.tool, s.detail].filter(Boolean).join(': '))}"><i class="dot"></i><span><span class="line">${head}</span><span class="line">${doing}</span></span></div>`;
+  }
+  if (f.live?.waiting) return `<div class="live waiting"><i class="dot"></i><span><b>Waiting for your reply</b> in a Claude session</span></div>`;
+  return '';
+}
 function renderBoard() {
   if (!S.features.length) {
     return `<div class="hero"><h1>No features yet</h1><p>Every change in this project flows through the factory: spec, design, plan, build, verify, review, ship.</p>
@@ -234,7 +268,7 @@ function renderBoard() {
   return `<div class="board">${COLUMNS.map(([key, label, owner]) => {
     const items = S.features.filter((f) => f.status === key);
     const model = (S.config.models || {})[key] ?? S.config.models?.default;
-    const modelTag = model && model !== 'inherit' ? ` · <span class="model" title="Model for this station (buildline models)">${esc(model)}</span>` : '';
+    const modelTag = key !== 'done' && model && model !== 'inherit' ? ` · <span class="model" title="Model for this station (buildline models)">${esc(model)}</span>` : '';
     return `<section class="col" aria-label="${label}"><h2><span>${label} <span class="owner">${owner}${modelTag}</span></span><small>${items.length}</small></h2>${items.map(card).join('') || '<div class="empty">—</div>'}</section>`;
   }).join('')}</div>`;
 }
@@ -254,6 +288,10 @@ async function render() {
   $('#project').textContent = S.config.project;
   $('#autonomy').textContent = S.autonomyLabel || `L${S.config.autonomy}`;
   $('#whoami').textContent = me() ? `👤 ${me()}` : 'Set your name';
+  const on = soundOn();
+  $('#soundBtn').textContent = on ? '♪ Sound on' : '♪ Sound off';
+  $('#soundBtn').setAttribute('aria-pressed', on);
+  $('#soundBtn').title = on ? 'Chimes when a feature needs you or ships. Click to mute.' : 'Click to chime when a feature needs you or ships.';
   document.querySelectorAll('nav.tabs button').forEach((b) => b.setAttribute('aria-selected', b.dataset.view === view));
   if (!(view === 'context' && ctxEditing && $('#ctxEditor'))) $('#main').innerHTML = view === 'board' ? renderBoard() : await renderContext();
   if (openId) await renderDrawer();
@@ -310,6 +348,7 @@ $('#newDialog').addEventListener('close', async () => {
 });
 $('#newBtn').onclick = newFeature;
 $('#whoami').onclick = askName;
+$('#soundBtn').onclick = () => { try { localStorage.setItem('buildline.sound', soundOn() ? 'off' : 'on'); } catch {} render(); if (soundOn()) chime(true); };
 $('#backdrop').onclick = closeDrawer;
 document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && openId && !editing) closeDrawer(); });
 document.addEventListener('click', (e) => {
@@ -319,15 +358,42 @@ document.addEventListener('click', (e) => {
   const x = e.target.closest('[data-ctx]'); if (x) { ctxPath = x.dataset.ctx; ctxEditing = false; render(); }
 });
 
+// ---- sound: one chime when a feature needs a person or ships ----
+let audio = null, needs = null, lastChime = 0;
+const soundOn = () => { let v = null; try { v = localStorage.getItem('buildline.sound'); } catch {} return v ? v === 'on' : S?.config.sound !== false; };
+const attention = (f) => (f.status === 'done' ? 'done' : f.blocked || f.live?.waiting ? 'waiting' : null);
+// Browsers only allow sound after the page has been touched, so the audio starts on the first click or key.
+const unlock = () => { audio ||= new (window.AudioContext || window.webkitAudioContext)(); audio.resume(); };
+['pointerdown', 'keydown'].forEach((e) => document.addEventListener(e, unlock, { once: true }));
+function chime(force = false) {
+  if (!audio || (!force && Date.now() - lastChime < 3000)) return;
+  lastChime = Date.now();
+  const t = audio.currentTime, out = audio.createGain();
+  out.connect(audio.destination);
+  out.gain.setValueAtTime(0.0001, t);
+  out.gain.exponentialRampToValueAtTime(0.25, t + 0.01);
+  out.gain.exponentialRampToValueAtTime(0.0001, t + 1.2);
+  for (const [hz, level] of [[880, 1], [1320, 0.35], [1760, 0.15]]) {
+    const o = audio.createOscillator(), g = audio.createGain();
+    o.frequency.value = hz; g.gain.value = level;
+    o.connect(g).connect(out); o.start(t); o.stop(t + 1.25);
+  }
+}
+function listen() {
+  const now = new Map(S.features.map((f) => [f.id, attention(f)]));
+  if (needs && soundOn() && [...now].some(([id, a]) => a && needs.get(id) !== a)) chime();
+  needs = now;
+}
+
 async function refresh() {
   try {
     const next = await api('/api/state');
     const changed = JSON.stringify(next) !== JSON.stringify(S);
-    S = next; if (changed) await render();
+    S = next; listen(); if (changed) await render();
   } catch (e) { toast('Dashboard lost connection: is `buildline ui` still running?'); }
 }
 refresh();
-setInterval(() => { if (!document.hidden && !editing && !ctxEditing) refresh(); }, 3000);
+setInterval(() => { if (!editing && !ctxEditing) refresh(); }, 2000);
 </script>
 </body>
 </html>

package/templates/AGENTS.block.md

@@ -23,7 +23,7 @@ Each station has a playbook in `.buildline/stations/<station>.md`. Read the play
 
 ### Where things live
 
-- `.buildline/features/<id>-<slug>/feature.json` — state: status, approvals, tasks (each with `passes`), history
+- `.buildline/features/<id>-<slug>/feature.json` — state: status, approvals, tasks (each with `passes`), history. Change it only with `node .buildline/bin/feature.mjs` (run it with no arguments for usage), never by hand.
 - `.buildline/features/<id>-<slug>/spec.md` — the single source of truth for that change
 - `.buildline/features/<id>-<slug>/progress.md` — append-only work log so any session can resume
 - `.buildline/context/` — living product, architecture and design knowledge (update it when you ship)
@@ -45,4 +45,6 @@ A task only gets `"passes": true` after the gates pass **and** its own verificat
 5. **Respect the autonomy level** (`autonomy` in `buildline.json`): pause for human approval where the station playbook says to.
 6. **Small, reversible steps.** Prefer many small commits over one large one. Match the existing code style.
 7. **Ask, don't guess,** when the spec is ambiguous about user-facing behaviour.
-8. **Respect model routing.** `models` in `buildline.json` can send a station to another tool (e.g. `"review": "codex"`). If a station is routed to a different CLI than the one you are, hand it off with `npx buildline step <station> <id> --headless` and summarise the result instead of doing it yourself.
+8. **Record state with the feature script.** `node .buildline/bin/feature.mjs move|task|log|block|approve …` stamps real times, keeps the history the team watches live, and refuses moves that skip a required approval. Never edit `feature.json` by hand.
+9. **Mark it blocked before you ask.** When you need an answer from a person, run `node .buildline/bin/feature.mjs block <id> "<the question>"`, then ask. When they answer, run `node .buildline/bin/feature.mjs unblock <id>` and carry on.
+10. **Respect model routing.** `models` in `buildline.json` can send a station to another tool (e.g. `"review": "codex"`). If a station is routed to a different CLI than the one you are, hand it off with `npx buildline step <station> <id> --headless` and summarise the result instead of doing it yourself.

package/templates/bin/feature.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Feature state for the factory. Managed by buildline. Zero dependencies.
+//
+// Agents record progress through this script instead of editing feature.json by
+// hand: it stamps real times, keeps history, and refuses moves that skip a human
+// approval the autonomy level requires.
+//
+//   node .buildline/bin/feature.mjs new "<title>" [--type fix|feature|epic] [--parent <id>]
+//   node .buildline/bin/feature.mjs show <id>
+//   node .buildline/bin/feature.mjs move <id> <station> [--note "…"]
+//   node .buildline/bin/feature.mjs task <id> add "<title>" [--verify "…"] [--covers R1,A2] [--parallel]
+//   node .buildline/bin/feature.mjs task <id> <T1> pass|fail [--note "what you ran and saw"]
+//   node .buildline/bin/feature.mjs log <id> "<note>"
+//   node .buildline/bin/feature.mjs block <id> "<question or reason>"
+//   node .buildline/bin/feature.mjs unblock <id> [--note "…"]
+//   node .buildline/bin/feature.mjs approve <id> <spec|design|plan> --by "<name>"   (only when that person said yes)
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const STATIONS = ['new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship', 'done'];
+const TYPES = ['fix', 'feature', 'epic'];
+const STAGES = ['spec', 'design', 'plan'];
+const now = () => new Date().toISOString();
+
+/** Approvals a feature needs before it may leave a station, by autonomy level. Fixes need none. */
+export function requiredApproval(station, autonomy, type) {
+  if (type === 'fix') return null;
+  if (station === 'spec' && autonomy <= 3) return 'spec';
+  if (station === 'design' && autonomy <= 1) return 'design';
+  if (station === 'plan' && autonomy <= 2) return 'plan';
+  return null;
+}
+
+/** Why moving `feature` to `to` isn't allowed yet, or null. Moving back is always allowed. */
+export function moveBlocker(feature, to, autonomy) {
+  const from = STATIONS.indexOf(feature.status);
+  const target = STATIONS.indexOf(to);
+  if (target < 0) return `Unknown station "${to}". Use one of: ${STATIONS.join(', ')}.`;
+  for (let i = Math.max(from, 0); i < target; i++) {
+    const stage = requiredApproval(STATIONS[i], autonomy, feature.type);
+    if (stage && !feature.approvals?.[stage]) {
+      return (
+        `${feature.id} needs ${stage} approval before it can leave "${STATIONS[i]}" (autonomy L${autonomy}). ` +
+        `Ask the person: "Approve the ${stage}?". If they say yes in this conversation, record it with ` +
+        `node .buildline/bin/feature.mjs approve ${feature.id} ${stage} --by "<their name>". ` +
+        `They can also approve in npx buildline ui or npx buildline watch. Leave the status where it is until then.`
+      );
+    }
+  }
+  return null;
+}
+
+export function featuresDir(root) {
+  return path.join(root, '.buildline', 'features');
+}
+
+export function findFeatureDir(root, ref) {
+  const dir = featuresDir(root);
+  if (!fs.existsSync(dir)) return null;
+  const r = String(ref ?? '').toLowerCase();
+  const dirs = fs.readdirSync(dir).filter((d) => /^\d{3,}-/.test(d) && fs.existsSync(path.join(dir, d, 'feature.json')));
+  const hit = dirs.find((d) => d.split('-')[0] === r.padStart(3, '0')) || dirs.find((d) => d === r) || dirs.find((d) => d.includes(r));
+  return hit ? path.join(dir, hit) : null;
+}
+
+export function load(root, ref) {
+  const dir = findFeatureDir(root, ref);
+  if (!dir) throw new Error(`No feature "${ref}" in .buildline/features.`);
+  return { dir, data: JSON.parse(fs.readFileSync(path.join(dir, 'feature.json'), 'utf8')) };
+}
+
+export function save({ dir, data }) {
+  data.updated = now();
+  fs.writeFileSync(path.join(dir, 'feature.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
+const autonomyOf = (root) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8')).autonomy ?? 2;
+  } catch {
+    return 2;
+  }
+};
+const record = (data, station, note) => (data.history = [...(data.history || []), { at: now(), station, note }]);
+
+export function move(root, ref, to, { note, force = false } = {}) {
+  const f = load(root, ref);
+  const blocker = force ? null : moveBlocker(f.data, to, autonomyOf(root));
+  if (blocker) throw new Error(blocker);
+  const from = f.data.status;
+  if (['verify', 'review'].includes(from) && to === 'build') f.data.metrics = { ...f.data.metrics, reworks: (f.data.metrics?.reworks || 0) + 1 };
+  if (to === 'done') f.data.metrics = { ...f.data.metrics, shippedAt: now() };
+  f.data.status = to;
+  f.data.blocked = null;
+  record(f.data, to, note || `Moved from ${from} to ${to}`);
+  save(f);
+  return f.data;
+}
+
+export function approve(root, ref, stage, by) {
+  if (!STAGES.includes(stage)) throw new Error(`Approval stage must be one of: ${STAGES.join(', ')}`);
+  if (!by) throw new Error('Say who approved: --by "<name>". Only record an approval the person gave you.');
+  const f = load(root, ref);
+  f.data.approvals = { ...f.data.approvals, [stage]: { by, at: now() } };
+  record(f.data, stage, `${stage} approved by ${by}`);
+  save(f);
+  return f.data;
+}
+
+export function addTask(root, ref, title, { verify, covers, parallel } = {}) {
+  if (!title) throw new Error('A task needs a title.');
+  const f = load(root, ref);
+  const tasks = f.data.tasks || [];
+  const n = tasks.reduce((m, t) => Math.max(m, parseInt(String(t.id).replace(/\D/g, ''), 10) || 0), 0) + 1;
+  const task = { id: `T${n}`, title, ...(covers ? { covers: String(covers).split(',').map((s) => s.trim()).filter(Boolean) } : {}), ...(verify ? { verify } : {}), ...(parallel ? { parallel: true } : {}), passes: false, notes: '' };
+  f.data.tasks = [...tasks, task];
+  save(f);
+  return task;
+}
+
+export function setTask(root, ref, id, passes, note) {
+  const f = load(root, ref);
+  const task = (f.data.tasks || []).find((t) => String(t.id).toLowerCase() === String(id).toLowerCase());
+  if (!task) throw new Error(`${f.data.id} has no task ${id}. Tasks: ${(f.data.tasks || []).map((t) => t.id).join(', ') || 'none yet'}.`);
+  task.passes = passes;
+  if (note) task.notes = note;
+  record(f.data, f.data.status, `${task.id} ${passes ? 'passes' : 'fails'}${note ? `: ${note}` : ''}`);
+  save(f);
+  return task;
+}
+
+export function log(root, ref, note) {
+  if (!note) throw new Error('Nothing to log.');
+  const f = load(root, ref);
+  record(f.data, f.data.status, note);
+  save(f);
+}
+
+export function block(root, ref, reason) {
+  if (!reason) throw new Error('Say what you need: block <id> "<question or reason>".');
+  const f = load(root, ref);
+  f.data.blocked = reason;
+  record(f.data, f.data.status, `Blocked: ${reason}`);
+  save(f);
+}
+
+export function unblock(root, ref, note) {
+  const f = load(root, ref);
+  f.data.blocked = null;
+  record(f.data, f.data.status, note ? `Unblocked: ${note}` : 'Unblocked');
+  save(f);
+}
+
+const slugify = (title) =>
+  title.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).slice(0, 5).join('-') || 'feature';
+
+export function create(root, title, { type = 'feature', parent = null, owner = null, templates } = {}) {
+  if (!title?.trim()) throw new Error('A feature needs a title.');
+  if (!TYPES.includes(type)) throw new Error(`Type must be one of: ${TYPES.join(', ')}`);
+  const base = featuresDir(root);
+  fs.mkdirSync(base, { recursive: true });
+  const next = fs.readdirSync(base).reduce((m, d) => Math.max(m, /^\d{3,}-/.test(d) ? parseInt(d, 10) : 0), 0) + 1;
+  const id = String(next).padStart(3, '0');
+  const slug = slugify(title);
+  const dir = path.join(base, `${id}-${slug}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const at = now();
+  const data = {
+    id, slug, title: title.trim(), type, status: type === 'fix' ? 'build' : 'spec', owner, parent, blocked: null,
+    approvals: {}, tasks: [], metrics: { reworks: 0, createdAt: at, shippedAt: null },
+    history: [{ at, station: 'new', note: `Opened as ${type}` }], created: at, updated: at,
+  };
+  fs.writeFileSync(path.join(dir, 'feature.json'), JSON.stringify(data, null, 2) + '\n');
+  const vars = { id, title: data.title, type, date: at.slice(0, 10) };
+  for (const name of ['spec.md', 'progress.md']) {
+    const local = path.join(root, '.buildline', 'templates', name);
+    const source = fs.existsSync(local) ? local : templates && path.join(templates, name);
+    const text = source && fs.existsSync(source) ? fs.readFileSync(source, 'utf8') : `# ${data.title}\n`;
+    fs.writeFileSync(path.join(dir, name), text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? vars[k] : m)));
+  }
+  return { ...data, dir };
+}
+
+// ---- command line --------------------------------------------------------------
+
+function parse(argv) {
+  const pos = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      opts[key] = val;
+    } else pos.push(a);
+  }
+  return { pos, opts };
+}
+
+function summary(d) {
+  const tasks = d.tasks || [];
+  return `${d.id} ${d.title} · ${d.status}${d.blocked ? ` · BLOCKED: ${d.blocked}` : ''} · ${tasks.filter((t) => t.passes).length}/${tasks.length} tasks`;
+}
+
+function main(argv) {
+  const root = process.env.BUILDLINE_ROOT || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const { pos, opts } = parse(argv);
+  const [cmd, ref, ...rest] = pos;
+  switch (cmd) {
+    case 'new': {
+      const f = create(root, [ref, ...rest].join(' '), { type: opts.type, parent: opts.parent, owner: opts.owner });
+      return console.log(`✔ created ${path.relative(root, f.dir)} · status ${f.status}`);
+    }
+    case 'show':
+      return console.log(JSON.stringify(load(root, ref).data, null, 2));
+    case 'move':
+      return console.log('✔ ' + summary(move(root, ref, rest[0], { note: opts.note, force: !!opts.force })));
+    case 'approve':
+      return console.log('✔ ' + summary(approve(root, ref, rest[0], opts.by)));
+    case 'task': {
+      if (rest[0] === 'add') {
+        const t = addTask(root, ref, rest.slice(1).join(' '), opts);
+        return console.log(`✔ ${t.id} added: ${t.title}`);
+      }
+      const [id, verdict] = rest;
+      if (!['pass', 'fail'].includes(verdict)) throw new Error('Usage: task <id> <T1> pass|fail [--note "…"]');
+      const t = setTask(root, ref, id, verdict === 'pass', opts.note);
+      return console.log(`✔ ${t.id} ${t.passes ? 'passes' : 'fails'} · ${summary(load(root, ref).data)}`);
+    }
+    case 'log':
+      log(root, ref, rest.join(' '));
+      return console.log('✔ logged');
+    case 'block':
+      block(root, ref, rest.join(' '));
+      return console.log(`✔ ${ref} marked blocked. Tell the person what you need; run unblock when they answer.`);
+    case 'unblock':
+      unblock(root, ref, opts.note);
+      return console.log(`✔ ${ref} unblocked`);
+    default:
+      console.log(fs.readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1, 17).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
+      if (cmd) process.exitCode = 1;
+  }
+}
+
+const invoked = () => {
+  try {
+    return import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+};
+if (process.argv[1] && invoked()) {
+  try {
+    main(process.argv.slice(2));
+  } catch (err) {
+    console.error(`✘ ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/templates/bin/hook.mjs

@@ -2,8 +2,14 @@
 // Claude Code hooks for the factory. Managed by buildline.
 //
 //   session-start  prints a short factory briefing into the new session's context
+//   pre            before each tool call: the guards below, plus a session heartbeat
 //   guard          blocks edits to a spec's "## Acceptance" section while the
-//                  feature is in build/verify/review, so agents can't move the goalposts
+//                  feature is in build/verify/review, so agents can't move the goalposts,
+//                  and hand edits to feature.json (agents use .buildline/bin/feature.mjs)
+//   prompt / stop / session-end
+//                  heartbeat: which session works on which feature, so
+//                  `buildline watch` and the dashboard can show live work.
+//                  Written to .buildline/sessions/ (git-ignored).
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 const root = process.env.CLAUDE_PROJECT_DIR || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const featuresDir = path.join(root, '.buildline', 'features');
 const mode = process.argv[2];
+const sessionsDir = path.join(root, '.buildline', 'sessions');
 
 function readJson(file) {
   try {
@@ -48,10 +55,22 @@ const acceptance = (text) => {
   return m ? m[1].trim() : null;
 };
 
+const deny = (msg) => {
+  process.stderr.write(msg + '\n');
+  process.exit(2);
+};
+
 function guard(input) {
   const tool = input.tool_name;
   const ti = input.tool_input || {};
   const file = ti.file_path ? path.resolve(root, ti.file_path) : null;
+  const viaScript = 'Use node .buildline/bin/feature.mjs instead (move, task, log, block, approve); run it with no arguments for usage. It records real times and checks approvals.';
+  if (file && file.startsWith(featuresDir + path.sep) && path.basename(file) === 'feature.json' && fs.existsSync(file)) {
+    deny(`buildline guard: don't edit ${path.relative(root, file)} by hand. ${viaScript}`);
+  }
+  if (tool === 'Bash' && /feature\.json/.test(ti.command || '') && !/feature\.mjs/.test(ti.command || '') && /(>|sed\s+-i|writeFile|json\.dump|\btee\b|perl\s+-[a-z]*i)/.test(ti.command || '')) {
+    deny(`buildline guard: don't write feature.json from the shell. ${viaScript}`);
+  }
   if (!file || !file.startsWith(featuresDir + path.sep) || path.basename(file) !== 'spec.md') return;
 
   const feature = readJson(path.join(path.dirname(file), 'feature.json'));
@@ -63,7 +82,9 @@ function guard(input) {
   else if (tool === 'Edit') after = before.replace(ti.old_string ?? '', ti.new_string ?? '');
   else if (Array.isArray(ti.edits)) for (const e of ti.edits) after = after.replace(e.old_string ?? '', e.new_string ?? '');
 
-  if (acceptance(before) !== acceptance(after)) {
+  // An acceptance section still holding the template's TODO may be filled in (fixes start at build).
+  const unfilled = /\bTODO\b/.test(acceptance(before) ?? 'TODO');
+  if (!unfilled && acceptance(before) !== acceptance(after)) {
     process.stderr.write(
       `buildline guard: "## Acceptance" in ${path.relative(root, file)} is locked while the feature is in "${feature.status}". ` +
         'If a scenario is wrong, stop and ask the spec owner; they can change it at the spec station.\n',
@@ -72,6 +93,66 @@ function guard(input) {
   }
 }
 
+// ---- heartbeat -------------------------------------------------------------------
+
+/** The feature a prompt or tool call is about, e.g. "/buildline-build 3" or a path under features/003-…. */
+function featureRef(text) {
+  const s = String(text || '');
+  const m =
+    /\.buildline\/features\/(\d{3,})-/.exec(s) ||
+    /feature\.mjs\s+(?:move|task|log|block|unblock|approve|show)\s+(\d{1,4})\b/.exec(s) ||
+    /\/buildline(?:-[a-z]+)?\s+(\d{1,4})\b/.exec(s) ||
+    /buildline\s+(?:step\s+[a-z]+|run|approve|move)\s+(\d{1,4})\b/.exec(s);
+  return m ? m[1].padStart(3, '0') : null;
+}
+
+function detail(input) {
+  const ti = input.tool_input || {};
+  if (ti.file_path) return path.basename(ti.file_path);
+  if (ti.command) {
+    // Short and readable: drop heredoc bodies and the long feature folder paths.
+    const cmd = String(ti.command).split(/<<|\n/)[0].replace(/\.buildline\/features\/[^/\s]+\//g, '').replace(/\s+/g, ' ').trim();
+    return cmd.length > 48 ? cmd.slice(0, 47) + '…' : cmd;
+  }
+  if (ti.pattern) return String(ti.pattern).slice(0, 40);
+  if (ti.description) return String(ti.description).slice(0, 60);
+  return '';
+}
+
+function heartbeat(input, event) {
+  const id = String(input.session_id || '').replace(/[^\w-]/g, '');
+  if (!id) return;
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  const ignore = path.join(sessionsDir, '.gitignore');
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n');
+  const file = path.join(sessionsDir, `${id}.json`);
+  if (event === 'end') return fs.rmSync(file, { force: true });
+  const at = new Date().toISOString();
+  const prev = readJson(file) || { id, startedAt: at };
+  const prompt = input.prompt || '';
+  const station = /\/buildline-([a-z]+)/.exec(prompt)?.[1];
+  const ti = input.tool_input || {};
+  // A session stays on the feature it was started for; reading another feature's files doesn't move it.
+  const feature = featureRef(prompt) || prev.feature || featureRef(ti.file_path) || featureRef(ti.command) || featureRef(ti.prompt) || null;
+  const next = {
+    ...prev,
+    feature,
+    station: station || prev.station || null,
+    model: input.model?.id || input.model || prev.model || null,
+    state: event === 'stop' ? 'waiting' : 'working',
+    lastAt: at,
+    ...(event === 'tool' ? { tool: input.tool_name, detail: detail(input) } : {}),
+    ...(event === 'prompt' ? { tool: null, detail: prompt.replace(/\s+/g, ' ').slice(0, 60) } : {}),
+  };
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+  if (event === 'tool' && feature) {
+    // A short live activity feed for the views; trimmed so it never grows large.
+    const feed = path.join(sessionsDir, 'activity.jsonl');
+    fs.appendFileSync(feed, JSON.stringify({ at, session: id.slice(0, 8), feature, tool: input.tool_name, detail: next.detail }) + '\n');
+    if (fs.statSync(feed).size > 200_000) fs.writeFileSync(feed, fs.readFileSync(feed, 'utf8').split('\n').slice(-500).join('\n'));
+  }
+}
+
 let raw = '';
 process.stdin.on('data', (c) => (raw += c));
 process.stdin.on('end', () => {
@@ -80,8 +161,12 @@ process.stdin.on('end', () => {
     input = raw ? JSON.parse(raw) : {};
   } catch {}
   try {
-    if (mode === 'session-start') sessionStart();
+    if (mode === 'session-start') sessionStart(), heartbeat(input, 'start');
     else if (mode === 'guard') guard(input);
+    else if (mode === 'pre') heartbeat(input, 'tool'), guard(input);
+    else if (mode === 'prompt') heartbeat(input, 'prompt');
+    else if (mode === 'stop') heartbeat(input, 'stop');
+    else if (mode === 'session-end') heartbeat(input, 'end');
   } catch (err) {
     // A broken hook must never break the session.
     process.stderr.write(`buildline hook error: ${err.message}\n`);

package/templates/stations/autopilot.md

@@ -33,7 +33,7 @@ Stop and summarise instead of continuing if:
 - the change needs a secret, a paid service, a production system or a destructive action,
 - `metrics.reworks` reaches 5 (the spec or plan probably needs a human).
 
-Write the blocker to `progress.md` and set `feature.json → blocked` to a one-line reason.
+Write the blocker to `progress.md` and run `node .buildline/bin/feature.mjs block <id> "<one-line reason>"` so the board shows it waiting on a person.
 
 ## Running it with `/goal` (Claude Code)
 

package/templates/stations/build.md

@@ -16,7 +16,10 @@ Resolve the feature from `$ARGUMENTS`, or use the most recent feature with statu
 3. Read `spec.md`: Requirements, Acceptance, Design, Plan.
 4. Run `node .buildline/bin/gates.mjs`. If gates fail **before** you change anything, record it in `progress.md` and fix or report it first. Don't stack new work on a red baseline.
 
-For `fix` features with no tasks: create a single task `T1` ("Reproduce with a failing test, then fix") plus `T2` ("Gates pass and A1 verified").
+For `fix` features:
+
+- If `## Brief` or `## Acceptance` in `spec.md` still say TODO, fill them in yourself from the title and the code: a one-line brief and one scenario that reproduces the bug. Fixes don't wait for a PM. Only if you can't tell what correct looks like (for example, which currency to show), block with the question (see "Asking for help").
+- With no tasks yet, add two: `node .buildline/bin/feature.mjs task <id> add "Reproduce with a failing test, then fix"` and `node .buildline/bin/feature.mjs task <id> add "Gates pass and A1 verified"`.
 
 ## 2. Work the next task
 
@@ -26,14 +29,20 @@ Pick the first task with `"passes": false`.
 2. Implement the smallest change that makes it pass. Follow the conventions in `.buildline/context/architecture.md` and reuse existing components and utilities before making new ones.
 3. Run the task's `verify` step **and** the gates. Read the output; don't assume.
 4. For UI work, run the app and look at it (a screenshot via the browser tools if available). Check the states listed in the design.
-5. Only when everything above is green, set `"passes": true` and write in `notes` what you ran and what you observed (one or two lines).
+5. Only when everything above is green, record it: `node .buildline/bin/feature.mjs task <id> T2 pass --note "<what you ran and what you saw>"`.
 6. Commit with a clear message, e.g. `feat(saved-carts): add model and migration [004/T1]`.
 
-If you get stuck on the same task after two genuinely different attempts, stop: write what you tried in `progress.md`, set `notes` on the task, and ask for help. Don't thrash.
+## Asking for help
+
+If you get stuck on the same task after two genuinely different attempts, or you need a decision only a person can make, stop. Don't thrash or guess:
+
+1. Write what you tried in `progress.md`.
+2. `node .buildline/bin/feature.mjs block <id> "<the question, in one line>"` so the board shows the feature waiting on a person.
+3. Ask the question. When it's answered, `node .buildline/bin/feature.mjs unblock <id> --note "<the answer>"` and carry on.
 
 ## 3. Hard rules
 
-- Never edit `## Acceptance` in `spec.md`, never delete or weaken a test to make it pass, never disable a gate. If you believe the spec or a test is wrong, stop and explain.
+- Never change a filled-in `## Acceptance` in `spec.md` (a fix may fill in an empty one), never delete or weaken a test to make it pass, never disable a gate. If you believe the spec or a test is wrong, stop and explain.
 - Never mark a task as passing without running its verification in this session.
 - Stay inside the feature's scope. Note unrelated problems you find in `progress.md` under "Noticed" instead of fixing them.
 - Don't commit secrets, generated artefacts or debugging leftovers.
@@ -49,4 +58,4 @@ Append to `progress.md`:
 - Next: T3 (UI list); watch out for the cart total rounding in utils/money.ts
 ```
 
-When every task passes: set status to `verify`, append a `history` entry, and continue with `/buildline-verify <id>` (or tell the person to).
+When every task passes: `node .buildline/bin/feature.mjs move <id> verify --note "<n>/<n> tasks pass"` and continue with `/buildline-verify <id>` (or tell the person to).

package/templates/stations/design.md

@@ -34,6 +34,6 @@ Follow the conventions in `architecture.md`. If you're breaking one, say so expl
 
 ## Handoff
 
-- Set status to `plan`. Append a `history` entry.
-- **Approval:** at autonomy L1, ask for explicit design approval and record `approvals.design` only when given. At other levels, the designer can approve UX in the dashboard; flag the feature as waiting for design approval if UX changed and nobody has approved it yet.
+- **Approval:** at autonomy L1, ask for explicit design approval and record it only when given: `node .buildline/bin/feature.mjs approve <id> design --by "<their name>"`.
+- Then `node .buildline/bin/feature.mjs move <id> plan --note "<one line>"`. At other levels, the designer can approve UX in the dashboard; flag the feature as waiting for design approval if UX changed and nobody has approved it yet.
 - Next: `/buildline-plan <id>`.