super-backlog 1.3.2 → 1.3.4

package/README.md

@@ -97,6 +97,10 @@ When enabled:
 
 The router is fully owned by super-backlog and removed by `sbl uninstall`. See the [model router design](docs/superpowers/specs/2026-08-26-sbl-model-router-design.md) for details.
 
+## Pipeline phases
+
+Tasks carry their pipeline phase as a label (`phase/spec` → `phase/plan` → `phase/impl` → `phase/verify`), managed by `sbl phase <task-id> [phase|done]` and checked by `sbl doctor`. The dashboard stepper, task table, and task modal render the live phase. Details: [docs/guide/pipeline-phases.md](docs/guide/pipeline-phases.md).
+
 ## Project Dashboard
 
 `sbl dashboard` starts a local hub that serves an HTS-style cockpit (light/dark theme toggle) rendered from your Backlog data in eight sections — Board & Quick Actions, Status (KPI tiles, donut, and an aging strip for open tasks), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Milestones, Drafts (click a card for details), Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Activity (a 26-week calendar heatmap; click a day for its tasks), and Decisions & Docs. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). Typefaces load from Google Fonts with full system fallbacks — the one external resource; everything else is inline, and the dashboard still renders offline. Bookmark `http://127.0.0.1:6428/p/<project_name>/`. The hub watches `backlog/`, regenerates on change, and serves on port `6428`; connected browser tabs reload automatically via Server-Sent Events. A second repo's `sbl dashboard` attaches to the same hub. `Ctrl+C` in the hub terminal stops all projects.

package/dist/cli.js

@@ -8,6 +8,7 @@ import { runDashboard } from './commands/dashboard.js';
 import { runDoctor } from './commands/doctor.js';
 import { runInit } from './commands/init.js';
 import { runModels } from './commands/models.js';
+import { runPhase } from './commands/phase.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runUpdate } from './commands/update.js';
 import { KIT_VERSION } from './lib/version.js';
@@ -22,6 +23,7 @@ Commands:
   update      Refresh kit-managed files and report upstream versions
   dashboard   Start the project dashboard server (live-reload) (alias: db)
   models      Manage the model router (show, enable, disable, discover)
+  phase       Show or advance a task's pipeline phase (spec|plan|impl|verify|done)
   doctor      Check the environment (node, PowerShell policy, backlog CLI)
 
   init options:
@@ -45,7 +47,10 @@ dashboard options:
   --no-open                       Do not open the dashboard browser automatically
 
 doctor options:
-  (none)                          Prints one [ok]/[warn]/[skip] line per check; exit 4 on any warn
+  (none)                          Prints one [ok]/[warn]/[skip]/[fail] line per check; exit 4 on any warn, 1 on any fail
+
+phase options:
+  --json                          Print the query result as JSON (phase + labels)
 
 Global options:
   --version                       Print the super-backlog version and exit
@@ -141,6 +146,19 @@ export async function runCli(argv) {
         }
         case 'doctor':
             return runDoctor(process.cwd());
+        case 'phase': {
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: {
+                    json: { type: 'boolean' },
+                },
+            });
+            return runPhase(process.cwd(), {
+                values: parsed.values,
+                positionals: parsed.positionals,
+            });
+        }
         default:
             console.error(`Unknown command "${command}".\n`);
             console.error(HELP);

package/dist/commands/dashboard.js

@@ -8,6 +8,7 @@ import { startHubServer } from '../dashboard/hub.js';
 import { renderDashboard } from '../dashboard/render.js';
 import { DASHBOARD_PORT } from '../dashboard/server.js';
 import { atomicWrite } from '../lib/atomic.js';
+import { defaultBuildFingerprint } from '../lib/build-fingerprint.js';
 import { clearHubState, isPidAlive, newHubToken, readHubState, writeHubState } from '../lib/hub-state.js';
 import { projectSlug } from '../lib/slug.js';
 import { KIT_VERSION } from '../lib/version.js';
@@ -157,6 +158,8 @@ export async function runDashboard(cwd, args, deps = {}) {
     const isAlive = deps.isAlive ?? isPidAlive;
     const killPid = deps.killPid ?? ((p) => { process.kill(p); });
     const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const buildFingerprint = deps.buildFingerprint ?? defaultBuildFingerprint;
+    const myFingerprint = buildFingerprint();
     let slugResult;
     try {
         slugResult = projectSlug(cwd);
@@ -180,7 +183,14 @@ export async function runDashboard(cwd, args, deps = {}) {
                     : undefined;
                 const liveVersion = typeof statusJson?.version === 'string' ? statusJson.version : undefined;
                 const effectiveVersion = liveVersion ?? state.version;
-                if (effectiveVersion === KIT_VERSION) {
+                const liveFingerprint = typeof statusJson?.fingerprint === 'string' ? statusJson.fingerprint : undefined;
+                // Same version AND (proven identical build OR build cannot be
+                // assessed locally) -> attach. A missing live fingerprint from a
+                // same-version hub means it was started by an older CLI and cannot
+                // see the current build, so it is restarted exactly once.
+                const buildMatches = myFingerprint !== null && liveFingerprint === myFingerprint;
+                const buildUnassessable = myFingerprint === null;
+                if (effectiveVersion === KIT_VERSION && (buildMatches || buildUnassessable)) {
                     if (values['port'] !== undefined && port !== state.port) {
                         console.error(`error: a hub is already running on ${state.port}`);
                         return 1;
@@ -194,7 +204,12 @@ export async function runDashboard(cwd, args, deps = {}) {
                         noOpen,
                     });
                 }
-                console.error(`hub v${effectiveVersion ?? 'unknown'} does not match this CLI (v${KIT_VERSION}) — restarting it`);
+                if (effectiveVersion === KIT_VERSION) {
+                    console.error(`hub build changed (fingerprint mismatch, same version v${KIT_VERSION}) — restarting it`);
+                }
+                else {
+                    console.error(`hub v${effectiveVersion ?? 'unknown'} does not match this CLI (v${KIT_VERSION}) — restarting it`);
+                }
                 killPid(state.pid);
                 let dead = !isAlive(state.pid);
                 for (let attempt = 0; !dead && attempt < STOP_POLL_MAX_ATTEMPTS; attempt++) {
@@ -234,7 +249,7 @@ export async function runDashboard(cwd, args, deps = {}) {
         console.error(`error: dashboard serve failed (${err instanceof Error ? err.message : String(err)})`);
         return 1;
     }
-    writeHubState(home, { pid, port: hub.port, token, version: KIT_VERSION });
+    writeHubState(home, { pid, port: hub.port, token, version: KIT_VERSION, fingerprint: myFingerprint ?? undefined });
     const result = hub.register({ cwd, file: outPath, regenerate });
     if (!result.ok) {
         await hub.close();

package/dist/commands/doctor.js

@@ -1,21 +1,63 @@
 // src/commands/doctor.ts
 import process from 'node:process';
+import { extractPhaseLabels, PHASES } from '../lib/phase.js';
 import { getEffectiveExecutionPolicy, isBlockingExecutionPolicy, } from '../lib/powershell.js';
-import { resolveBacklogBin } from '../lib/run.js';
-const MARK = { ok: '[ok]  ', warn: '[warn]', skip: '[skip]' };
+import { resolveBacklogBin, runCapture } from '../lib/run.js';
+const MARK = {
+    ok: '[ok]  ',
+    warn: '[warn]',
+    skip: '[skip]',
+    fail: '[fail]',
+};
+function defaultReadTaskLabels(cwd, resolveBacklog) {
+    const bin = resolveBacklog(cwd);
+    if (!bin)
+        return null;
+    const res = runCapture(bin, ['task', 'list', '--json'], cwd);
+    if (res.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(res.stdout);
+        if (!Array.isArray(parsed.tasks))
+            return null;
+        const rows = [];
+        for (const t of parsed.tasks) {
+            if (typeof t !== 'object' || t === null)
+                continue;
+            const id = t.id;
+            const status = t.status;
+            const labels = t.labels;
+            if (typeof id !== 'string' || typeof status !== 'string')
+                continue;
+            rows.push({
+                id,
+                status,
+                labels: Array.isArray(labels) ? labels.filter((l) => typeof l === 'string') : [],
+            });
+        }
+        return rows;
+    }
+    catch {
+        return null;
+    }
+}
 export function runDoctor(cwd, deps = {}) {
     const platform = deps.platform ?? process.platform;
     const nodeVersion = deps.nodeVersion ?? process.versions.node;
     const resolveBacklog = deps.resolveBacklog ?? resolveBacklogBin;
+    const readTaskLabels = deps.readTaskLabels ?? ((c) => defaultReadTaskLabels(c, resolveBacklog));
     const log = deps.log ?? ((line) => console.log(line));
     let okCount = 0;
     let warnCount = 0;
     let skipCount = 0;
+    let failCount = 0;
     const emit = (status, line, extra = []) => {
         if (status === 'ok')
             okCount += 1;
         else if (status === 'warn')
             warnCount += 1;
+        else if (status === 'fail')
+            failCount += 1;
         else
             skipCount += 1;
         log(`${MARK[status]} ${line}`);
@@ -60,6 +102,43 @@ export function runDoctor(cwd, deps = {}) {
             'fix: npx.cmd super-backlog init',
         ]);
     }
-    log(`doctor summary: ${okCount} ok, ${warnCount} warn, ${skipCount} skip`);
+    // check 4: phase label hygiene
+    const taskRows = readTaskLabels(cwd);
+    if (taskRows === null) {
+        emit('skip', 'phase label hygiene (task labels unreadable - backlog CLI unavailable)');
+    }
+    else {
+        const known = new Set(PHASES.map((p) => `phase/${p}`));
+        let problems = 0;
+        let legacy = 0;
+        for (const row of taskRows) {
+            const phaseLabels = extractPhaseLabels(row.labels);
+            const unknown = phaseLabels.filter((l) => !known.has(l));
+            if (phaseLabels.length > 1) {
+                problems += 1;
+                emit('fail', `${row.id}: multiple phase labels (${phaseLabels.join(', ')})`, [
+                    `fix: sbl phase ${row.id} <phase> after removing the stale label`,
+                ]);
+            }
+            for (const l of unknown) {
+                problems += 1;
+                emit('fail', `${row.id}: unknown phase label ${l}`, [
+                    `fix: backlog task edit ${row.id} --remove-label ${l}`,
+                ]);
+            }
+            if (unknown.length === 0 && phaseLabels.length === 0 && row.status === 'In Progress') {
+                legacy += 1;
+                emit('warn', `${row.id}: In Progress without phase label (legacy inventory)`, [
+                    `fix: sbl phase ${row.id} spec`,
+                ]);
+            }
+        }
+        if (problems === 0 && legacy === 0) {
+            emit('ok', `phase label hygiene clean (${taskRows.length} tasks)`);
+        }
+    }
+    log(`doctor summary: ${okCount} ok, ${warnCount} warn, ${skipCount} skip, ${failCount} fail`);
+    if (failCount > 0)
+        return 1;
     return warnCount > 0 ? 4 : 0;
 }

package/dist/commands/phase.js

@@ -0,0 +1,86 @@
+// src/commands/phase.ts
+import { derivePhase, extractPhaseLabels, isPhaseTarget, planTransition } from '../lib/phase.js';
+import { resolveBacklogBin, runCapture } from '../lib/run.js';
+function readLabels(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const labels = parsed?.task?.labels;
+        if (!Array.isArray(labels))
+            return null;
+        return labels.filter((l) => typeof l === 'string');
+    }
+    catch {
+        return null;
+    }
+}
+export function runPhase(cwd, args, deps = {}) {
+    const resolveBacklog = deps.resolveBacklog ?? resolveBacklogBin;
+    const run = deps.run ?? runCapture;
+    const log = deps.log ?? ((line) => console.log(line));
+    const id = args.positionals[0];
+    const target = args.positionals[1];
+    const json = args.values['json'] === true;
+    if (!id || (target !== undefined && !isPhaseTarget(target))) {
+        log(`usage: sbl phase <task-id> [${['spec', 'plan', 'impl', 'verify', 'done'].join('|')}] [--json]`);
+        return 1;
+    }
+    const bin = resolveBacklog(cwd);
+    if (!bin) {
+        log('error: backlog CLI not found - run sbl init or npm install first');
+        return 1;
+    }
+    const view = run(bin, ['task', 'view', id, '--json'], cwd);
+    if (view.status !== 0) {
+        log(`error: backlog task view ${id} failed (exit ${view.status})`);
+        if (view.stderr.trim())
+            log(view.stderr.trim());
+        return 1;
+    }
+    const labels = readLabels(view.stdout);
+    if (labels === null) {
+        log(`error: unreadable task view JSON for ${id}`);
+        return 1;
+    }
+    const phase = derivePhase(labels);
+    if (target === undefined) {
+        if (json) {
+            log(JSON.stringify({ id, phase, labels: extractPhaseLabels(labels) }));
+        }
+        else {
+            log(phase ? `${id}: phase/${phase}` : `${id}: none`);
+        }
+        return 0;
+    }
+    const result = planTransition(labels, target);
+    if (!result.ok) {
+        if (result.reason === 'multiple-phases') {
+            log(`error: ${id} carries multiple phase labels (${extractPhaseLabels(labels).join(', ')}) - run sbl doctor`);
+        }
+        else if (result.reason === 'no-phase') {
+            log(`error: ${id} has no phase label - start with: sbl phase ${id} spec`);
+        }
+        else {
+            log(`error: unknown phase "${String(target)}"`);
+        }
+        return 1;
+    }
+    const { remove, add } = result.plan;
+    if (remove === null && add === null) {
+        log(`${id}: no phase label present, nothing to do`);
+        return 0;
+    }
+    const editArgs = ['task', 'edit', id];
+    if (remove)
+        editArgs.push('--remove-label', remove);
+    if (add)
+        editArgs.push('--add-label', add);
+    const edit = run(bin, editArgs, cwd);
+    if (edit.status !== 0) {
+        log(`error: backlog task edit failed (exit ${edit.status})`);
+        if (edit.stderr.trim())
+            log(edit.stderr.trim());
+        return 3;
+    }
+    log(add ? `${id}: ${add}` : `${id}: phase label removed (done)`);
+    return 0;
+}

package/dist/dashboard/data.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
+import { derivePhase } from '../lib/phase.js';
 import { isNewerVersion } from '../lib/version-check.js';
 import { readSimpleKeys } from '../lib/yamlmini.js';
 import { computeKpis } from './metrics.js';
@@ -16,6 +17,9 @@ function asString(v) {
         return String(v);
     return undefined;
 }
+function asStrings(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+}
 /**
  * Parse the stdout of `backlog task list --json` defensively.
  * Accepts `{tasks:[...]}` and bare-array shapes; anything else throws
@@ -70,6 +74,8 @@ export function normalizeTasks(rawTasks) {
         title: asString(t['title']) ?? '(untitled)',
         status: asString(t['status']) ?? 'Unknown',
         priority: asString(t['priority']),
+        labels: asStrings(t['labels']),
+        phase: derivePhase(asStrings(t['labels'])),
         assignee: firstAssignee(t),
         created: asString(t['createdAt']) ?? asString(t['created_at']) ?? asString(t['created']),
         updated: asString(t['updatedAt']) ?? asString(t['updated_at']) ?? asString(t['updated']),

package/dist/dashboard/hub.js

@@ -9,6 +9,7 @@ import { collectDashboardData } from './data.js';
 import { renderDashboard } from './render.js';
 import { createDebouncedReloader, createReloadBroker, DASHBOARD_PORT, recursiveWatchSupported, } from './server.js';
 import { atomicWrite } from '../lib/atomic.js';
+import { defaultBuildFingerprint } from '../lib/build-fingerprint.js';
 import { projectSlug, realpathKey } from '../lib/slug.js';
 import { KIT_VERSION } from '../lib/version.js';
 import { createModelApiHandler } from '../models/dashboard-api.js';
@@ -63,6 +64,7 @@ function generateDashboard(cwd, file) {
 export async function startHubServer(opts) {
     const projects = new Map();
     const token = opts.token;
+    const fingerprint = defaultBuildFingerprint();
     let port = 0;
     let watchWarned = false;
     function watchBacklog(cwd, reloader) {
@@ -166,7 +168,7 @@ export async function startHubServer(opts) {
                 sendText(res, 401, 'unauthorized');
                 return;
             }
-            sendJson(res, 200, { pid: process.pid, port, version: KIT_VERSION });
+            sendJson(res, 200, { pid: process.pid, port, version: KIT_VERSION, fingerprint: fingerprint ?? undefined });
             return;
         }
         if (pathname === '/api/hub/register' && method === 'POST') {

package/dist/lib/build-fingerprint.js

@@ -0,0 +1,50 @@
+// src/lib/build-fingerprint.ts
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const require = createRequire(import.meta.url);
+function distRoot() {
+    // Resolves from src/lib (dev/tests) and dist/lib (runtime) alike: both sit
+    // two levels below the package root that owns dist/.
+    const pkgPath = require.resolve('../../package.json');
+    return join(dirname(pkgPath), 'dist');
+}
+function walk(dir, out) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(full, out);
+        else
+            out.push(full);
+    }
+}
+/**
+ * Stable content hash over the built CLI. Two builds of the same source
+ * produce the same fingerprint; any changed or added file changes it.
+ * Returns null when the build directory is missing.
+ */
+export function computeBuildFingerprint(root = distRoot()) {
+    if (!existsSync(root))
+        return null;
+    const files = [];
+    walk(root, files);
+    if (files.length === 0)
+        return null;
+    files.sort();
+    const hash = createHash('sha256');
+    for (const file of files) {
+        hash.update(file.slice(root.length + 1).replaceAll('\\', '/'));
+        hash.update('\0');
+        hash.update(readFileSync(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 16);
+}
+let cachedDefault;
+/** Process-lifetime cached fingerprint of the running build. */
+export function defaultBuildFingerprint() {
+    if (cachedDefault === undefined)
+        cachedDefault = computeBuildFingerprint();
+    return cachedDefault;
+}

package/dist/lib/hub-state.js

@@ -16,8 +16,14 @@ export function readHubState(home) {
             typeof parsed.token !== 'string') {
             return null;
         }
-        const { pid, port, token, version } = parsed;
-        return typeof version === 'string' ? { pid, port, token, version } : { pid, port, token };
+        const { pid, port, token, version, fingerprint } = parsed;
+        return {
+            pid,
+            port,
+            token,
+            ...(typeof version === 'string' ? { version } : {}),
+            ...(typeof fingerprint === 'string' ? { fingerprint } : {}),
+        };
     }
     catch {
         return null;

package/dist/lib/phase.js

@@ -0,0 +1,30 @@
+// src/lib/phase.ts
+export const PHASES = ['spec', 'plan', 'impl', 'verify'];
+export const PHASE_LABEL_PREFIX = 'phase/';
+const PHASE_LABELS = PHASES.map((p) => PHASE_LABEL_PREFIX + p);
+export function phaseLabel(p) {
+    return PHASE_LABEL_PREFIX + p;
+}
+export function isPhaseTarget(v) {
+    return v === 'done' || PHASES.includes(v);
+}
+export function extractPhaseLabels(labels) {
+    return labels.filter((l) => l.startsWith(PHASE_LABEL_PREFIX));
+}
+export function derivePhase(labels) {
+    const found = labels.find((l) => PHASE_LABELS.includes(l));
+    return found ? found.slice(PHASE_LABEL_PREFIX.length) : null;
+}
+export function planTransition(labels, target) {
+    if (!isPhaseTarget(target))
+        return { ok: false, reason: 'unknown-phase' };
+    const phaseLabels = extractPhaseLabels(labels);
+    if (phaseLabels.length > 1)
+        return { ok: false, reason: 'multiple-phases' };
+    const current = phaseLabels[0] ?? null;
+    if (current === null && target !== 'spec')
+        return { ok: false, reason: 'no-phase' };
+    const remove = current;
+    const add = target === 'done' ? null : phaseLabel(target);
+    return { ok: true, plan: { remove, add } };
+}

package/dist/templates/dashboard.html

@@ -395,6 +395,12 @@
     overflow-wrap: break-word;
   }
   .step.gate .step-label { color: var(--warn); }
+  .step .step-count { position: relative; z-index: 1; display: inline-block; margin-top: 6px;
+    padding: 0 .45rem; border-radius: 999px; font: 600 .68rem/1.5 var(--mono);
+    background: color-mix(in oklab, var(--accent) 18%, transparent); color: var(--accent); }
+
+  /* ---------- Phase chip in task rows ---------- */
+  .cell-id .status-chip { margin-left: .45rem; }
 
   /* ---------- Phase detail panel ---------- */
   #phase-detail {
@@ -766,6 +772,13 @@
           var chip = el('span', 'status-chip', field(task, k));
           chip.setAttribute('data-tone', toneOf(task.status));
           td.appendChild(chip);
+        } else if (k === 'id') {
+          td.textContent = field(task, k);
+          if (task.phase) {
+            var pc = el('span', 'status-chip', 'phase/' + task.phase);
+            pc.setAttribute('data-tone', 'accent');
+            td.appendChild(pc);
+          }
         } else if (k === 'updated') {
           td.textContent = formatRelative(field(task, k));
           var exact = formatExact(field(task, k));
@@ -1342,6 +1355,10 @@
       step.setAttribute('aria-controls', 'phase-detail');
       step.appendChild(el('div', 'step-num', String(p.n)));
       step.appendChild(el('span', 'step-label', p.name));
+      var phaseKey = PHASE_STEP[p.n];
+      if (phaseKey && phaseCounts[phaseKey] > 0) {
+        step.appendChild(el('span', 'step-count', String(phaseCounts[phaseKey])));
+      }
       step.addEventListener('click', function () {
         if (!panel) return;
         var wasOpen = current === step;
@@ -1368,6 +1385,15 @@
   } catch (e) {
     phases = [];
   }
+
+  /* ---------- Pipeline phase state (labels on tasks) ---------- */
+  var PHASE_STEP = { 5: 'spec', 6: 'plan', 7: 'impl', 8: 'verify' };
+  var NEXT_PHASE = { spec: 'plan', plan: 'impl', impl: 'verify', verify: 'done' };
+  var phaseCounts = { spec: 0, plan: 0, impl: 0, verify: 0 };
+  data.tasks.forEach(function (t) {
+    if (t.phase && phaseCounts[t.phase] !== undefined) phaseCounts[t.phase] += 1;
+  });
+
   if ($('#donut')) renderDonut($('#donut'), data.statuses);
   if ($('#kpis')) renderKpis($('#kpis'), data.kpis);
   if ($('#aging')) renderAging($('#aging'), data.tasks);
@@ -1505,6 +1531,7 @@
     }
     grid.appendChild(cell('Milestone', task.milestone));
     grid.appendChild(cell('Priority', task.priority, priorityTone(task.priority)));
+    grid.appendChild(cell('Phase', task.phase ? 'phase/' + task.phase : ''));
     grid.appendChild(cell('Assignee', task.assignee));
     grid.appendChild(cell('Updated', task.updated));
     return grid;
@@ -1570,6 +1597,15 @@
     cmd.appendChild(el('span', 'cmd-title', 'copy'));
     cmd.addEventListener('click', function () { copyCommand(cmd, cmdLine); });
     content.appendChild(cmd);
+    if (t.phase && NEXT_PHASE[t.phase]) {
+      var advanceCmd = 'sbl phase ' + t.id.replace(/^task-/i, '') + ' ' + NEXT_PHASE[t.phase];
+      var adv = el('button', 'phase-cmd detail-cmd');
+      adv.type = 'button';
+      adv.appendChild(el('span', 'cmd-line', advanceCmd));
+      adv.appendChild(el('span', 'cmd-title', 'copy: advance'));
+      adv.addEventListener('click', function () { copyCommand(adv, advanceCmd); });
+      content.appendChild(adv);
+    }
     dialog.textContent = '';
     dialog.appendChild(content);
     dialog.showModal();

package/dist/templates/skill-spec-to-backlog.md

@@ -18,15 +18,17 @@ Bridge between Superpowers (brainstorming, writing-plans) and Backlog.md.
 1. Read `backlog instructions overview` and `backlog instructions task-creation` first.
 2. Decompose: every plan unit becomes ONE task, small enough for one session/PR.
 3. Create per task:
-   backlog task create "Title" -d "<goal/context>" --ac "<criterion 1>" --ac "<criterion 2>" --type feature --label feature --ref "<path/to/plan-doc>"
+   backlog task create "Title" -d "<goal/context>" --ac "<criterion 1>" --ac "<criterion 2>" --type feature --labels feature,phase/spec --ref "<path/to/plan-doc>"
    - Dependencies: --dep TASK-y (order follows the plan).
    - Larger efforts: backlog milestone add `"<Name>"`, attach via -m.
    - Reference the plan doc via --ref; NEVER copy it into the task.
 4. Never set --plan or --notes at create time — those belong to the "task started" checkpoint after codebase research.
-5. STOP at the review gate: the human reviews specs and acceptance criteria (backlog board / backlog browser / dashboard.html) before any code exists.
+5. Every created task starts at `phase/spec`. Later phase changes happen only via `sbl phase <id> <phase>` at gate passages — never by editing labels manually.
+6. STOP at the review gate: the human reviews specs and acceptance criteria (backlog board / backlog browser / project dashboard) before any code exists.
 
 ## Boundaries
 
 - Never hand-edit task markdown; use the backlog CLI exclusively.
 - No code, no worktrees, no status changes inside this skill.
+- Phase labels are set with creation and advanced only via `sbl phase`.
 - Project-specific human-gate topics get their own tasks with an explicit review gate.

package/dist/templates/skill-task-review-gate.md

@@ -1,30 +1,44 @@
 ---
 name: task-review-gate
-description: Enforce the human review checkpoint before implementation starts. Use after tasks were created from a plan, or when the user asks to implement a specific task, to present the task and its acceptance criteria and wait for explicit approval before any code.
+description: Enforce the human review checkpoint before implementation starts. Use at session start on an existing task, right after spec-to-backlog created tasks, or when the user asks to implement a specific task: present the task, its pipeline phase and acceptance criteria, and wait for explicit approval before any code.
 ---
 
-# Task Review Gate: no code before an explicit yes
+# Task Review Gate: session entry, review gate, resume
 
-Human checkpoint between reviewed specs and the first line of code.
+Human checkpoint between reviewed specs and the first line of code — and the
+re-entry point for every session that continues a running task.
 
 ## When this skill runs
 
-1. Right after spec-to-backlog created tasks (review specs + acceptance criteria).
-2. When the user asks to implement a specific task (restate scope before starting).
+1. At the start of a session that works on an existing task (resume).
+2. Right after spec-to-backlog created tasks (review specs + acceptance criteria).
+3. When the user asks to implement a specific task (restate scope before starting).
 
 ## Procedure
 
 1. Load the task: `backlog task view <ID> --plain`.
-2. Present compactly: goal, every acceptance criterion, dependencies, and the
-   recorded plan if one exists.
-3. STOP and wait for the user's explicit approval. Silence or a topic change
+2. Load the phase: `sbl phase <ID>` (prints `phase/spec|plan|impl|verify` or `none`).
+3. Present compactly: goal, every acceptance criterion, dependencies, the
+   recorded plan if one exists, and the current phase.
+4. STOP and wait for the user's explicit approval. Silence or a topic change
    is NOT approval.
-4. Only after approval: set the task In Progress via the backlog CLI and start
-   with a plan-before-code pass if no plan is recorded yet.
+5. After approval, resume per phase:
+   - `phase/spec` — review gate passed: advance with `sbl phase <ID> plan`,
+     then start the plan-before-code pass.
+   - `phase/plan` — plan recorded: advance with `sbl phase <ID> impl` once the
+     human approves the plan, then TDD.
+   - `phase/impl` — refresh context from the recorded plan and implementation
+     notes, then continue TDD where it stopped.
+   - `phase/verify` — collect verification evidence (tests/lint/typecheck),
+     write the final summary, then `sbl phase <ID> done` at archival.
+   - `none` — a task without a phase label is either legacy (offer
+     `sbl phase <ID> spec`) or not yet started (walk the review gate first).
+6. Set the task In Progress via the backlog CLI when work starts.
 
 ## Boundaries
 
 - Never approve the gate yourself; vague consent is not approval.
+- Phase changes only via `sbl phase` — never edit labels by hand.
 - Trivial edits stay exempt only on explicit user instruction.
 - If acceptance criteria look wrong or incomplete, send the user back to task
   editing instead of starting.

package/dist/templates/workflow-block.md

@@ -8,17 +8,17 @@ methodology skills that decide how the work is done.
 
 ### Pipeline (follow in order)
 
-| # | Phase | Gate to pass |
-|---|-------|--------------|
-| 1 | Idea | User states a need; capture it before doing anything else |
-| 2 | Brainstorming | Explore intent, requirements and design before any creative work |
-| 3 | Design gate | Human approves the design document |
-| 4 | Spec-to-backlog | Decompose the approved design into reviewed tasks with acceptance criteria |
-| 5 | Review gate | Human reviews specs and acceptance criteria before any code exists |
-| 6 | Plan-before-code | A written implementation plan is approved by the human |
-| 7 | TDD implementation | Failing test first, then code; one task per session/PR |
-| 8 | Verification & final summary | Run tests/lint/typecheck; verification evidence before success claims |
-| 9 | Merge & archive | Merge the branch, then close/archive the task via the backlog CLI |
+| # | Phase | Phase label | Gate to pass |
+|---|-------|-------------|--------------|
+| 1 | Idea | — | User states a need; capture it before doing anything else |
+| 2 | Brainstorming | — | Explore intent, requirements and design before any creative work |
+| 3 | Design gate | — | Human approves the design document |
+| 4 | Spec-to-backlog | `phase/spec` set at creation | Decompose the approved design into reviewed tasks with acceptance criteria |
+| 5 | Review gate | `phase/spec` | Human reviews specs and acceptance criteria before any code exists |
+| 6 | Plan-before-code | `phase/plan` | A written implementation plan is approved by the human |
+| 7 | TDD implementation | `phase/impl` | Failing test first, then code; one task per session/PR |
+| 8 | Verification & final summary | `phase/verify` | Run tests/lint/typecheck; verification evidence before success claims |
+| 9 | Merge & archive | label removed (`done`) | Merge the branch, then close/archive the task via the backlog CLI |
 
 ### Binding rules
 
@@ -26,6 +26,7 @@ methodology skills that decide how the work is done.
 2. Plan before code — implementation starts only after an approved written plan.
 3. Task status changes always go through the CLI backed by verification evidence, never from memory.
 4. Skills take precedence over habit whenever a matching skill exists.
+5. Phase transitions only via `sbl phase <id> <phase>`, always at a gate passage — never edit phase labels by hand.
 
 Project-specific human gates are intentionally out of scope for this block.
 Add project-specific human gates below the block.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-backlog",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "One command to equip any project with Backlog.md + Superpowers, plus a Project Dashboard.",
   "license": "MIT",
   "repository": {