super-backlog 1.3.1 → 1.3.3

package/README.md

@@ -73,7 +73,9 @@ sbl dashboard                   # live Project Dashboard on http://localhost:642
 | `dashboard.html` | generated Project Dashboard | not installed in user projects; generated on demand by `sbl dashboard` |
 | `.git/hooks/pre-commit` | integrity guard hook — only with `--guard` (opt-in) | appended marker block |
 
-Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]`. See `sbl help` for every flag.
+Commands: `sbl init` · `sbl models` · `sbl doctor` · `sbl uninstall [--with-backlog]` · `sbl update` · `sbl dashboard [--port <n>] [--no-open]` (alias: `sbl db`). See `sbl help` for every flag.
+
+`sbl update` first self-updates a globally installed CLI to the latest npm version and re-runs itself (opt out with `--no-self` or `SBL_SKIP_UPDATE_CHECK`), then refreshes injected files.
 
 ## Model router (opt-in)
 
@@ -95,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';
@@ -20,8 +21,9 @@ Commands:
   init        Install the kit into the current project
   uninstall   Remove kit-managed files (project data kept unless --with-backlog)
   update      Refresh kit-managed files and report upstream versions
-  dashboard   Start the project dashboard server (live-reload)
+  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:
@@ -38,14 +40,17 @@ uninstall options:
   --fix-all                       Also remove the global npm package (no prompts)
 
 update options:
-  (none)                          Refreshes injected files, skills, hook; prints upstream versions
+  --no-self                       Skip self-updating the CLI before refreshing
 
 dashboard options:
   --port <n>                      Port for the dashboard server (default: 6428)
   --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
@@ -102,12 +107,17 @@ export async function runCli(argv) {
             });
         }
         case 'update': {
-            const parsed = parseArgs({ args: rest, allowPositionals: true, options: {} });
+            const parsed = parseArgs({
+                args: rest,
+                allowPositionals: true,
+                options: { 'no-self': { type: 'boolean' } },
+            });
             return await runUpdate(process.cwd(), {
                 values: parsed.values,
                 positionals: parsed.positionals,
             });
         }
+        case 'db':
         case 'dashboard': {
             const parsed = parseArgs({
                 args: rest,
@@ -136,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

@@ -11,6 +11,9 @@ import { atomicWrite } from '../lib/atomic.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';
+/** Max time to wait for an outdated hub to exit after killPid, in 100ms polls. */
+const STOP_POLL_MAX_ATTEMPTS = 50;
+const STOP_POLL_INTERVAL_MS = 100;
 async function regenerateInto(outPath, cwd) {
     const data = collectDashboardData(cwd, { kitVersion: KIT_VERSION });
     atomicWrite(outPath, renderDashboard(data));
@@ -151,6 +154,9 @@ export async function runDashboard(cwd, args, deps = {}) {
     const attach = deps.attach ?? defaultAttach;
     const openBrowser = deps.openBrowser ?? defaultOpenBrowser;
     const pid = (deps.nowPid ?? (() => process.pid))();
+    const isAlive = deps.isAlive ?? isPidAlive;
+    const killPid = deps.killPid ?? ((p) => { process.kill(p); });
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     let slugResult;
     try {
         slugResult = projectSlug(cwd);
@@ -165,22 +171,44 @@ export async function runDashboard(cwd, args, deps = {}) {
     }
     const slug = slugResult.slug;
     const state = readHubState(home);
-    if (state !== null && isPidAlive(state.pid)) {
+    if (state !== null && isAlive(state.pid)) {
         try {
             const status = await attach(`http://127.0.0.1:${state.port}/api/hub/status?token=${encodeURIComponent(state.token)}`, undefined);
             if (status.status === 200) {
-                if (values['port'] !== undefined && port !== state.port) {
-                    console.error(`error: a hub is already running on ${state.port}`);
+                const statusJson = typeof status.json === 'object' && status.json !== null
+                    ? status.json
+                    : undefined;
+                const liveVersion = typeof statusJson?.version === 'string' ? statusJson.version : undefined;
+                const effectiveVersion = liveVersion ?? state.version;
+                if (effectiveVersion === KIT_VERSION) {
+                    if (values['port'] !== undefined && port !== state.port) {
+                        console.error(`error: a hub is already running on ${state.port}`);
+                        return 1;
+                    }
+                    return await attachToHub({
+                        cwd,
+                        port: state.port,
+                        token: state.token,
+                        attach,
+                        openBrowser,
+                        noOpen,
+                    });
+                }
+                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++) {
+                    await sleep(STOP_POLL_INTERVAL_MS);
+                    dead = !isAlive(state.pid);
+                }
+                if (dead) {
+                    clearHubState(home, state.pid);
+                    // fall through to the fresh-start path below
+                }
+                else {
+                    console.error(`error: could not stop the outdated hub (pid ${state.pid}) — stop it manually and re-run`);
                     return 1;
                 }
-                return await attachToHub({
-                    cwd,
-                    port: state.port,
-                    token: state.token,
-                    attach,
-                    openBrowser,
-                    noOpen,
-                });
             }
         }
         catch {
@@ -206,7 +234,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 });
+    writeHubState(home, { pid, port: hub.port, token, version: KIT_VERSION });
     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/commands/update.js

@@ -1,13 +1,86 @@
 // src/commands/update.ts
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import process from 'node:process';
+import spawn from 'cross-spawn';
 import { executeActions, findGitDir, InvalidJsonError, validateJsonFile, RefusalError, UpstreamError } from '../init/execute.js';
 import { planInit } from '../init/planner.js';
 import { GUARD_RE } from '../lib/hooks.js';
 import { detectPackageManager } from '../lib/pm.js';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
+import { detectInstallKind, runSelfUpdate } from '../lib/self-update.js';
 import { KIT_VERSION } from '../lib/version.js';
+import { fetchLatestVersion } from '../lib/version-check.js';
+/** Longer than the startup version-hint fetch: this one blocks `sbl update` directly. */
+const SELF_UPDATE_FETCH_TIMEOUT_MS = 10000;
+function resolveGlobalRoot(cwd) {
+    const r = runCapture('npm', ['root', '-g'], cwd);
+    if (r.status !== 0)
+        return null;
+    const line = firstLine(r.stdout);
+    return line === '' ? null : line;
+}
+function resolveBinRealPath() {
+    const argvBin = process.argv[1];
+    if (!argvBin)
+        return null;
+    try {
+        return realpathSync(argvBin);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runs the self-update check/install and, when a new version was installed,
+ * re-execs the new binary once (env-guarded via SBL_SELF_UPDATED) and
+ * returns its exit code. Returns null when the caller should fall through
+ * to the normal refresh (no update available, offline, install failed, or
+ * the update was skipped entirely).
+ */
+async function maybeSelfUpdate(cwd, args, override) {
+    const skip = args.values['no-self'] === true ||
+        Boolean(process.env.SBL_SELF_UPDATED) ||
+        Boolean(process.env.SBL_SKIP_UPDATE_CHECK) ||
+        Boolean(process.env.SBL_FORCE_OFFLINE);
+    if (skip)
+        return null;
+    const binRealPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    const globalRoot = override.globalRoot !== undefined ? override.globalRoot : resolveGlobalRoot(cwd);
+    const installKind = binRealPath === null ? 'unknown' : detectInstallKind(binRealPath, cwd, globalRoot);
+    const fetchLatest = override.fetchLatest ?? (() => fetchLatestVersion(SELF_UPDATE_FETCH_TIMEOUT_MS));
+    const npmInstallGlobal = override.npmInstallGlobal ?? ((spec) => runCapture('npm', ['i', '-g', spec], cwd));
+    const result = await runSelfUpdate({
+        installed: KIT_VERSION,
+        fetchLatest,
+        installKind,
+        npmInstallGlobal,
+        log: (line) => console.log(line),
+        warn: (line) => console.warn(`warning: ${line}`),
+    });
+    if (result.kind !== 'updated')
+        return null;
+    // npm rewrites the global package's files in place, so process.argv[1]
+    // still points at a valid path after the install -- re-resolve anyway in
+    // case the realpath target moved (e.g. a version-pinned symlink).
+    const updatedBinPath = override.binRealPath !== undefined ? override.binRealPath : resolveBinRealPath();
+    if (updatedBinPath === null)
+        return null; // can't re-exec without a bin path; fall through on the old version
+    const spawnSelf = override.spawnSelf ??
+        ((binPath, rArgs, execCwd, env) => {
+            const r = spawn.sync(process.execPath, [binPath, 'update', ...rArgs], {
+                cwd: execCwd,
+                stdio: 'inherit',
+                env,
+            });
+            return { status: r.status ?? 1 };
+        });
+    const res = spawnSelf(updatedBinPath, args.positionals, cwd, {
+        ...process.env,
+        SBL_SELF_UPDATED: '1',
+    });
+    return res.status ?? 1;
+}
 const REFRESH_KINDS = new Set([
     'inject-agents-block',
     'write-claude-pointer',
@@ -29,7 +102,10 @@ function guardHookInstalled(cwd) {
         return false;
     return GUARD_RE.test(readFileSync(hookPath, 'utf8'));
 }
-export async function runUpdate(cwd, _args) {
+export async function runUpdate(cwd, args, selfUpdateOverride = {}) {
+    const selfUpdateExitCode = await maybeSelfUpdate(cwd, args, selfUpdateOverride);
+    if (selfUpdateExitCode !== null)
+        return selfUpdateExitCode;
     // Up-front detection-failure check (mirrors uninstall): refuse before mutating anything.
     for (const f of ['package.json', 'opencode.json']) {
         const p = join(cwd, f);
@@ -100,14 +176,17 @@ export async function runUpdate(cwd, _args) {
             warnings.push(`\`${bin} --version\` failed with exit code ${local.status}`);
         }
     }
+    const probePublished = selfUpdateOverride.probePublished ??
+        (() => {
+            // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
+            if (process.env.SBL_FORCE_OFFLINE)
+                throw new Error('forced offline');
+            const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
+            return view.status === 0 ? firstLine(view.stdout) : null;
+        });
     let published = null;
     try {
-        // test seam: SBL_FORCE_OFFLINE makes e2e runs take the offline path deterministically
-        if (process.env.SBL_FORCE_OFFLINE)
-            throw new Error('forced offline');
-        const view = runCapture('npm', ['view', 'backlog.md', 'version'], cwd);
-        if (view.status === 0)
-            published = firstLine(view.stdout);
+        published = probePublished();
     }
     catch {
         published = null;

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

@@ -166,7 +166,7 @@ export async function startHubServer(opts) {
                 sendText(res, 401, 'unauthorized');
                 return;
             }
-            sendJson(res, 200, { pid: process.pid, port });
+            sendJson(res, 200, { pid: process.pid, port, version: KIT_VERSION });
             return;
         }
         if (pathname === '/api/hub/register' && method === 'POST') {

package/dist/lib/hub-state.js

@@ -16,8 +16,8 @@ export function readHubState(home) {
             typeof parsed.token !== 'string') {
             return null;
         }
-        const { pid, port, token } = parsed;
-        return { pid, port, token };
+        const { pid, port, token, version } = parsed;
+        return typeof version === 'string' ? { pid, port, token, version } : { pid, port, token };
     }
     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/lib/self-update.js

@@ -0,0 +1,57 @@
+// src/lib/self-update.ts
+import { join } from 'node:path';
+import process from 'node:process';
+import { isNewerVersion } from './version-check.js';
+/**
+ * Normalizes separators for prefix comparison and, on win32, case as well:
+ * `npm root -g` and `realpathSync` can disagree on drive-letter/path casing
+ * (`C:\` vs `c:\`) even for the same install, and Windows paths are
+ * case-insensitive anyway, so comparing case-sensitively there would
+ * misclassify a real global install as `unknown`. Takes an optional
+ * `caseInsensitive` override (default: `process.platform === 'win32'`) so
+ * the function stays pure and testable for both platforms' behavior.
+ */
+function normalizeForCompare(p, caseInsensitive) {
+    const withForwardSlashes = p.replace(/\\/g, '/');
+    return caseInsensitive ? withForwardSlashes.toLowerCase() : withForwardSlashes;
+}
+function isUnder(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+/**
+ * Classifies the running binary's real path as a local (project
+ * node_modules) install, a global npm install, or unknown (treated the
+ * same as local: never mutated, hint only). Pure function -- callers
+ * gather binRealPath (from `process.argv[1]` + `realpathSync`) and
+ * globalRoot (from `npm root -g`, captured once, null on failure).
+ */
+export function detectInstallKind(binRealPath, cwd, globalRoot, caseInsensitive = process.platform === 'win32') {
+    const bin = normalizeForCompare(binRealPath, caseInsensitive);
+    const localRoot = normalizeForCompare(join(cwd, 'node_modules'), caseInsensitive);
+    if (isUnder(bin, localRoot))
+        return 'local';
+    if (globalRoot !== null && isUnder(bin, normalizeForCompare(globalRoot, caseInsensitive)))
+        return 'global';
+    return 'unknown';
+}
+export async function runSelfUpdate(deps) {
+    const latest = await deps.fetchLatest();
+    if (latest === null) {
+        deps.warn('could not check for a newer super-backlog (offline?)');
+        return { kind: 'unavailable' };
+    }
+    if (!isNewerVersion(latest, deps.installed)) {
+        return { kind: 'current' };
+    }
+    if (deps.installKind !== 'global') {
+        deps.log(`a newer super-backlog (${latest}) is available; update the dependency yourself, e.g. npm i -D super-backlog@${latest}`);
+        return { kind: 'skipped-local', latest };
+    }
+    const result = deps.npmInstallGlobal(`super-backlog@${latest}`);
+    if (result.status === 0) {
+        deps.log(`self-updated to ${latest}, re-running update...`);
+        return { kind: 'updated', latest };
+    }
+    deps.warn(`self-update to ${latest} failed (npm install exited ${String(result.status)}); continuing with ${deps.installed}`);
+    return { kind: 'failed', latest };
+}

package/dist/lib/version-check.js

@@ -57,7 +57,8 @@ function isStale(checkedAt, now) {
 function unrefStream(stream) {
     stream?.unref?.();
 }
-export async function defaultFetchLatest() {
+/** Queries the npm registry for the latest published version, racing a timeout. */
+export async function fetchLatestVersion(timeoutMs = FETCH_TIMEOUT_MS) {
     const work = new Promise((resolvePromise) => {
         let child;
         try {
@@ -89,7 +90,7 @@ export async function defaultFetchLatest() {
     });
     let timer;
     const timeout = new Promise((resolveTimeout) => {
-        timer = setTimeout(() => resolveTimeout(null), FETCH_TIMEOUT_MS);
+        timer = setTimeout(() => resolveTimeout(null), timeoutMs);
         timer.unref();
     });
     try {
@@ -103,12 +104,15 @@ export async function defaultFetchLatest() {
             clearTimeout(timer);
     }
 }
+export async function defaultFetchLatest() {
+    return fetchLatestVersion(FETCH_TIMEOUT_MS);
+}
 export async function applyVersionHint(installed, deps) {
     if (deps.env.SBL_SKIP_UPDATE_CHECK)
         return;
     const cache = readCache(deps.home);
     if (cache && isNewerVersion(cache.latest, installed)) {
-        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: npm i -g super-backlog`);
+        deps.log(`super-backlog ${cache.latest} is available (installed ${installed}). Update: sbl update (or npm i -g super-backlog)`);
     }
     if (!cache || isStale(cache.checkedAt, deps.now())) {
         void deps

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 {
@@ -659,7 +665,7 @@
     var upd = el('button', 'update-badge');
     upd.type = 'button';
     upd.appendChild(el('span', 'cmd-title', 'v' + data.latestVersion + ' available'));
-    upd.setAttribute('data-tip', 'Update: npm i -g super-backlog (click to copy)');
+    upd.setAttribute('data-tip', 'Update: run sbl update (click copies npm i -g super-backlog)');
     upd.addEventListener('click', function () { copyCommand(upd, 'npm i -g super-backlog'); });
     sideVersion.appendChild(upd);
   }
@@ -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.1",
+  "version": "1.3.3",
   "description": "One command to equip any project with Backlog.md + Superpowers, plus a Project Dashboard.",
   "license": "MIT",
   "repository": {