qualia-framework 6.9.0 → 6.14.0

package/CHANGELOG.md

@@ -8,6 +8,94 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [6.14.0] - 2026-06-20 (v7 kernel, step 4 — R3: the cross-artifact analyze gate)
+
+Spec-Kit's most-copied feature, ported. Qualia validated each artifact in isolation — `plan-contract.js` proves the contract is internally well-formed, `harness-eval` scores the built phase — but **nothing diffed scope ↔ plan**. That's exactly where a junior's idea silently loses intent: the scope asks for X, the plan quietly drops it, and no deterministic check notices. This adds that check, between plan and build.
+
+### Added — `bin/analyze-gate.js` (deterministic, zero-LLM, zero-dependency)
+- Diffs the plan contract against **intent**: scope acceptance criteria (`.planning/phase-{N}-context.md` `## Acceptance Criteria`) and the CONTEXT.md glossary. Pure keyword/token coverage — same inputs → same output.
+- **Four checks:** (1) *uncovered scope AC* — a scope requirement whose key terms don't appear in the contract (HIGH; the plan dropped it); (2) *orphan success criterion* — a contract success criterion no task covers (MEDIUM); (3) *glossary violation* — the plan uses a term CONTEXT.md lists under `Avoid:` (MEDIUM; a genuine spec↔plan contradiction); (4) *scope-reduction language* in task actions/ACs (HIGH; reuses `plan-contract.findScopeReductionPhrases`).
+- CLI `analyze-gate.js <phase>` auto-discovers contract + scope + CONTEXT.md; `--json` for machine output. Exit 0 = clean, 1 = findings, 2 = invocation error. Library exports (`analyze`, `coverage`, `parseScopeAcceptanceCriteria`, `parseGlossaryBannedTerms`) for reuse.
+
+### Changed — wired into `qualia-build` as the plan→build gate (§1a), profile-aware
+- Runs `analyze-gate.js {N}` before any build. **strict** profile → a HIGH finding is a stop (route to `/qualia-plan --gaps` or `/qualia-scope`); **standard** → surface + proceed with an explicit ack and a logged waiver. **No scope file = scope-coverage skipped, not a failure** — scope-less phases and `/qualia-feature` trivia still build.
+- Deliberately **not** a `state.js` hard precondition: scope files are optional, so gating the `built` transition there would brick builds for projects that never ran `/qualia-scope`. The gate lives at the skill seam and degrades gracefully.
+- Shipped into installed `bin/` via `runtime-manifest.js`.
+
+### Tests
+- `tests/analyze-gate.test.sh` (new, 21 cases): clean pass, under-covered scope AC, orphan success criterion, glossary violation, no-scope skip, missing-contract error, `coverage()` overlap/disjoint units, AC-parser label-strip + section-boundary. Registered in `run-all.sh` (now 12 suites). `lib.test.sh` trust-score install set carries `analyze-gate.js`.
+
+## [6.13.0] - 2026-06-20 (v7 kernel, step 3 — enforce what you already declare: 3 missing primitives)
+
+The v7 brief's loudest meta-theme is **"enforce, don't just declare"** — every static contract Qualia already computes should have a runtime gate. This batch wires the three primitives the research flagged as genuinely missing (R1, R2 + the slop-gate quick win), turning prose instructions and plan-time checks into deterministic, hook-governed guardrails. No new dependencies; all 11 suites green.
+
+### Added — R1: runtime plan-contract file-scope guard (`hooks/task-write-guard.js`)
+- `plan-contract.js` proves file-disjointness across parallel tasks at **plan** time, but nothing stopped a builder writing outside its declared set at **run** time — the documented #1 cross-wave-conflict + AI-entropy vector. New PreToolUse `Edit|Write` hook closes it.
+- **Scoped:** a no-op unless a build is in flight (≥1 `RUNNING` entry in `.agent-status/` — the R2 signal), so it never interferes with the orchestrator, verifier, or ordinary editing. During a build it **blocks any write to a path not declared by some task** in the active phase contract (`files_modify ∪ files_create`). `.planning/` and `.agent-status/` are always writable. **Fails open** on any error; OWNER escape `QUALIA_ALLOW_OUTSIDE_CONTRACT=1`.
+- **Honest limitation (documented in-file):** Claude Code gives a stateless hook no task identity, so it enforces "declared by SOME task" not "by THIS task" — plan-time disjointness + the builder's `<wave_context>` prompt cover the residual gap. Registered in `install.js` (`QUALIA_HOOK_SET` + the `Edit|Write` block); hook count 14 → 15.
+
+### Added — R2: machine-readable per-task status + wave fan-in barrier (`bin/agent-status.js`)
+- `contract-runner.js` only checked exit codes; wave completion relied on the orchestrator LLM **reading** each builder's "DONE/BLOCKED/PARTIAL" prose. New helper persists each builder's outcome to `.agent-status/<task>.json` (`RUNNING | DONE | BLOCKED | PARTIAL` + commit hash) — the parallel-worktrees convention.
+- CLI: `write` / `read` / `list` / `clear`, plus `barrier <contract.json> [--wave W]` which **exits 0 ⇔ every expected task is DONE** (a pollable barrier, not "did the model notice"). Task ids validated against `^T\d+$` (rejects path traversal). `buildActive()` export is the signal R1 keys off.
+- `qualia-build`: builders now write `RUNNING` at start + `DONE/BLOCKED/PARTIAL` at end; the orchestrator runs the barrier after each wave (a `BLOCKED`/`PARTIAL` task holds the wave) and clears scratch at completion. Shipped into installed `bin/` via `runtime-manifest.js`.
+
+### Added — slop-detect wired into the verify + ship gates (quick win)
+- The anti-slop scanner (`bin/slop-detect.mjs`) already existed and exits non-zero on CRITICAL design tells; this adds the **gate wiring** (same role as `migration-guard`/`branch-guard`). `pre-deploy-gate.js` re-runs it at `vercel --prod` time as the hard, non-bypassable block (CRITICAL → deploy refused). Skipped silently when the scanner isn't installed (brownfield/older installs); OWNER-only `QUALIA_SKIP_SLOP=1` escape mirrors `QUALIA_SKIP_LINT`. Surfaced in `qualia-verify` (CRITICAL = verification FAIL) and `qualia-ship` Quality Gates.
+
+### Tests
+- `tests/agent-status.test.sh` (new, 24 cases): round-trip, validation/traversal rejection, wave + phase barriers, BLOCKED-holds, list/clear, `buildActive`. Registered in `run-all.sh`.
+- `tests/hooks.test.sh`: +10 `task-write-guard` cases (idle no-op, declared allow, undeclared block, `files_create`, framework-path exemptions, escape hatch, absolute paths, quiet-after-DONE, fail-open) and +4 `pre-deploy-gate` anti-slop cases (gradient block, clean pass, OWNER-only skip, graceful skip when absent).
+- Hook-count assertions bumped 14 → 15 (`install-smoke`, `bin`); `runner.js` install test corrected to 15; `lib.test.sh` trust-score install set carries `agent-status.js`.
+
+## [6.12.0] - 2026-06-20 (v7 kernel, step 2 — lifecycle: build → operate, the forced handoff is gone)
+
+The v7.0-defining change the redesign brief called out as #1 (Section 6, "the change you raised"): a project that has **launched** should stop being a milestone-journey dragged to a Handoff, and become an **update stream**. This is the v7 thesis in miniature — a behavior hard-coded in prose ("the final milestone is always Handoff, never negotiable") is now a **branch on explicit state**.
+
+### Added — a `lifecycle: "build" | "operate"` dimension to the state machine
+- **`bin/state.js`:** new projects default to `lifecycle: "build"` (unchanged behavior). New `state.js launch [--deployed-url U] [--source erp|manual]` flips a project to `"operate"`, stamping `launched_at` + `launch_source` (idempotent — relaunching is a no-op). This is the discrete, **ERP-drivable** "is_live" event (the ERP can call it when it detects a project is live), so "launched" is state, not a milestone the team must mislabel as handoff.
+- **The forced-handoff funnel is now lifecycle-gated:** `checkPreconditions` requires `HANDOFF.md` for `handed_off` **only in `build` mode**. An `operate` project can complete without ever producing a handoff. (Build mode is byte-for-byte unchanged — verified by a regression test.)
+- **`nextCommand` is lifecycle-aware:** in `operate`, a final-phase `verified(pass)` routes to `/qualia-update` (not `/qualia-polish → ship → handoff`); a `verified(pass)` on the last phase increments `lifetime.updates_completed` (the operate analogue of closing a milestone). `cmdCheck` now surfaces `lifecycle` + `launched_at`.
+- **`/qualia-update` skill (new):** the operate-mode counterpart to `/qualia-milestone` — a lean plan → build → verify → ship loop with no milestone/handoff machinery. Added to `ACTIVE_SKILLS`.
+- **ERP contract:** `bin/report-payload.js` now sends `lifecycle` (+ `launched_at`/`launch_source` when set) so the ERP counts updates vs milestones and stops expecting a handoff for a live product. `templates/journey.md` rule 3 demoted from "the final milestone is always Handoff, never negotiable" to a **build-mode convention**.
+- **Tests:** 7 new `state.test.sh` cases (build default; launch→operate stamping + routing; idempotent launch; operate verified→`/qualia-update` + `updates_completed` bump; **build mode still requires HANDOFF.md**; operate mode allows `handed_off` without it). All 10 suites green (89 state cases).
+
+> Verification evidence (6.10.0) stays fully in force in operate mode — an update's contract still runs and its evidence must be clean to PASS. Lifecycle relaxes the *handoff* requirement, never the *evidence* requirement.
+
+## [6.11.0] - 2026-06-20 (main-push: accountability instead of a block)
+
+Owner policy change: an employee pushing to `main`/`master` is **no longer blocked** — it is **counted**. The framework records each employee main-push locally (per-employee running total) and reports it to the ERP as a policy-event the OWNER can see, plus a visible on-push notice. OWNER pushes are unaffected and silent.
+
+### Changed — `hooks/branch-guard.js` is now allow-and-record, never block
+- Was: `fail()`/exit 2 (BLOCK) on any non-OWNER push to a protected branch. Now: detects the same protected-branch pushes (current branch **and** `<src>:main` refspec), records an `employee_main_push` event to `~/.claude/.main-push-events.json` (`{counts:{<actor>:{total}}, events:[…]}`, mode 0600), enqueues it to the ERP `/api/v1/policy-events` endpoint via `erp-retry.js` (idempotent, `client_report_id` = `QS-MAINPUSH-<actor>-<count>`), prints a non-blocking NOTICE, and **exits 0**. Mirrors the existing `fawzi-approval-guard` model. The hook no longer blocks on missing/malformed config either — it never blocks.
+- **ERP side:** `docs/erp-contract.md` now documents the `employee_main_push` event type (stored by `(type, actor_code)` for a per-employee tally, `branch` field replaces `sample`).
+- Docs updated to the new reality (`EMPLOYEE-QUICKSTART.md`, `docs/qualia-manual.html`, installer comments + the push hook's status message now reads "Recording branch activity").
+- Tests rewritten (`tests/hooks.test.sh`): employee main-push → exit 0 + recorded + count increments + notice; refspec `:main` → recorded; feature-branch / OWNER / missing-config → allowed, not recorded. All 10 suites green.
+
+> Trade-off (by owner decision): `branch-guard` is no longer a hard gate on `main`; "main is always deployable" now rests on review discipline + the visible per-employee tally rather than a block. `git-guardrails` still blocks genuinely destructive pushes (force-push to main, branch -D).
+
+## [6.10.0] - 2026-06-20 (v7 kernel, step 1 — verification evidence is no longer optional)
+
+Closes the headline finding of the v7 redesign brief: **the verification gate could PASS with zero evidence.** This was real — verified on disk against 6.9.2. The fix is the first incremental step of the v7 "invariants in an enforceable kernel, not prose" thesis, shipped on the 6.x line (main stays deployable).
+
+### Fixed — a phase can no longer reach `verified(pass)` without machine evidence
+- **Root cause:** the enforcement machinery already existed (`contract-runner.js`, `state.js checkMachineEvidence`), but it was *bypassable by omission*. `checkMachineEvidence` only engages when `phase-N-contract.json` exists (`state.js:1024` returned `{ok:true}` when absent), and nothing forced a contract — the `planned` precondition checked the plan file but never the contract. So the common no-contract path fell through to the prose verifier.
+- **Structural fix (`bin/state.js`):** the `planned` precondition now requires a valid `phase-N-contract.json` (exists + parseable + non-empty `tasks[]`), failing `MISSING_CONTRACT`/`INVALID_CONTRACT` otherwise. Because every planned phase now has a contract, `checkMachineEvidence` always engages at the `verified` gate — machine evidence (`evidence/phase-N-contract-run.json` with `ok:true`) becomes mandatory for PASS. "I built it" is no longer sufficient; "the contract ran clean" is required. (Implements the 2026-05-22 harness audit's Finding 3.)
+- **Defense-in-depth (`agents/verifier.md`):** the design-rubric instruction "Default to 3 unless evidence supports otherwise" — which *contradicted* `rules/grounding.md` ("Score without evidence = 0") — is replaced. An unevidenced dimension is now `INSUFFICIENT EVIDENCE` and scores 1 (FAIL). A verifier that runs no checks and writes "3" across the board now produces a FAIL, and `state.js:983` already refuses PASS on that literal.
+- **Tests (`tests/state.test.sh`):** `make_valid_plan` now emits a contract + passing evidence by default so happy-path setups satisfy the new preconditions; the two cases that exercise *absence* (missing-evidence guard, `--require-contract` missing) strip them explicitly. All 10 suites green.
+
+### Removed — dead `qualia-discuss` skill directory
+- The skill was already retired in `bin/command-surface.js` (folded into `/qualia-scope`), but its 222-line `SKILL.md` still shipped in the tarball. Deleted the directory; `RETIRED_SKILLS` continues to clean it from older installs.
+
+## [6.9.2] - 2026-06-20 (docs — visual field manual)
+
+### Added — `docs/qualia-manual.html`
+- A self-contained, single-file introductory **Field Manual** in the Qualia house style (dark + teal `#00FFD1`), shipped in the npm package (`files`). It is the human-friendly visual companion to `docs/EMPLOYEE-QUICKSTART.md`: what the framework is, the plan→build→verify→ship→report loop, employee-mode install, the full command map grouped by purpose, a first-project walkthrough, the five hard rules, the credentials-and-who-issues-them table, and the `/qualia` "when you're lost" escape hatch. Content is grounded in the existing quickstart + skill set — nothing invented. Interactive but dependency-free: sticky scroll-spy nav, click-to-copy command chips, reveal-on-scroll, mobile-responsive, skip-link for a11y. `docs/EMPLOYEE-QUICKSTART.md` now links to it.
+
+## [6.9.1] - 2026-06-16 (fix — stale update banner)
+
+### Fixed — session-start showed a false "update available" banner after catching up
+- `hooks/session-start.js` rendered the cached `.qualia-update-available.json` notice on every session without checking it against the installed version. Because `auto-update.js` only clears that file on its next (throttled) run, the window between an install and that run showed a stale "Current 6.8.1 → Latest 6.9.0" banner even though 6.9.0 was already installed. `maybeRenderUpdateBanner` now validates the notice against `.qualia-config.json` and self-clears (skips render) when the installed version is at or past the advertised `latest`. Regression covered by two new cases in `tests/hooks.test.sh` (stale self-clears; genuine notice preserved).
+
 ## [6.9.0] - 2026-06-13 (employee on-ramps — stack presets, employee-mode install, shared knowledge pull)
 
 Implements Part A of the 2026-06-13 restructure plan: turn the framework from an owner-only tool into something a new employee can take idea→deployed without tribal knowledge. **Additive only** — no skill, agent, hook, or rule was rewritten; these are on-ramps built *around* the existing loop.

package/agents/verifier.md

@@ -176,7 +176,7 @@ If exit code is 1 (critical findings present), the phase FAILS. Quote the findin
 
 ### Step B — Design rubric scoring (9 dimensions)
 
-Apply `qualia-design/design-rubric.md`. Score 1-5 per dimension WITH evidence on the next line. Default to 3 unless evidence supports otherwise.
+Apply `qualia-design/design-rubric.md`. Score 1-5 per dimension WITH cited `file:line` evidence in the Evidence column. **Do NOT default to a passing score.** A dimension you cannot back with evidence is `INSUFFICIENT EVIDENCE` and scores **1 (FAIL)** — per `rules/grounding.md` ("Score without evidence = 0"). A verifier that runs no checks and writes "3" across the board must produce a FAIL, not a PASS. Never write a score you cannot cite.
 
 Scoped by phase scope:
 - Component-only phase → score Typography, Color cohesion, States, Motion intent, Microcopy, Container depth, and Visual system & graphics when the component owns a primary visual (skip Layout originality and Spatial rhythm when those are page-level concerns)

package/bin/agent-status.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// agent-status.js — machine-readable per-task build status + fan-in barrier.
+//
+// The gap this closes: `qualia-build` spawns one subagent per task and the
+// orchestrator LLM has to *read* each builder's "DONE/BLOCKED/PARTIAL" prose to
+// know a wave finished. That's not a barrier — it's the model noticing. This
+// helper persists each builder's outcome to `.agent-status/<task>.json` so wave
+// completion gates on a deterministic, pollable signal (the parallel-worktrees
+// convention) and drives a live wave view.
+//
+// Builder convention (see skills/qualia-build):
+//   1. At task start:  agent-status.js write <task> RUNNING --phase N --wave W
+//   2. At task end:    agent-status.js write <task> DONE --commit <hash>
+//                      (or BLOCKED / PARTIAL with a --note)
+// Orchestrator after spawning a wave:
+//      agent-status.js barrier <contract.json> --wave W   # exit 0 ⇔ all DONE
+//
+// Zero npm dependencies. Library + tiny CLI.
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("./plan-contract.js");
+
+const STATUSES = new Set(["RUNNING", "DONE", "BLOCKED", "PARTIAL"]);
+const STATUS_DIR = ".agent-status";
+
+function statusDir(root) {
+  return path.join(root, STATUS_DIR);
+}
+
+// Task ids match ^T\d+$ (plan-contract schema). Reject anything else so a bad
+// arg can't write outside .agent-status/ via a traversal in the filename.
+function isTaskId(task) {
+  return typeof task === "string" && /^T\d+$/.test(task);
+}
+
+function statusFile(root, task) {
+  return path.join(statusDir(root), `${task}.json`);
+}
+
+function writeStatus(root, entry) {
+  if (!isTaskId(entry.task)) throw new Error(`invalid task id: ${entry.task} (must match ^T\\d+$)`);
+  const status = String(entry.status || "").toUpperCase();
+  if (!STATUSES.has(status)) throw new Error(`invalid status: ${entry.status} (must be ${[...STATUSES].join("|")})`);
+  const dir = statusDir(root);
+  fs.mkdirSync(dir, { recursive: true });
+  const record = {
+    task: entry.task,
+    status,
+    commit: entry.commit || null,
+    note: entry.note || null,
+    phase: entry.phase != null ? Number(entry.phase) : null,
+    wave: entry.wave != null ? Number(entry.wave) : null,
+    updated_at: entry.now || new Date().toISOString(),
+  };
+  fs.writeFileSync(statusFile(root, entry.task), JSON.stringify(record, null, 2) + "\n");
+  return record;
+}
+
+function readStatus(root, task) {
+  try {
+    return JSON.parse(fs.readFileSync(statusFile(root, task), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function listStatuses(root) {
+  const dir = statusDir(root);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      out.push(JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")));
+    } catch {}
+  }
+  out.sort((a, b) => String(a.task).localeCompare(String(b.task), undefined, { numeric: true }));
+  return out;
+}
+
+function clearStatuses(root) {
+  const dir = statusDir(root);
+  if (!fs.existsSync(dir)) return 0;
+  let n = 0;
+  for (const f of fs.readdirSync(dir)) {
+    if (f.endsWith(".json")) { fs.unlinkSync(path.join(dir, f)); n++; }
+  }
+  try { fs.rmdirSync(dir); } catch {}
+  return n;
+}
+
+// True when a build is in flight: at least one task is RUNNING. R1's pre-write
+// guard keys off this so it only enforces file-discipline during a build.
+function buildActive(root) {
+  return listStatuses(root).some((s) => s.status === "RUNNING");
+}
+
+function expectedTaskIds(contract, wave) {
+  const tasks = (contract && contract.tasks) || [];
+  const filtered = wave != null ? tasks.filter((t) => Number(t.wave) === Number(wave)) : tasks;
+  return filtered.map((t) => t.id);
+}
+
+// Fan-in barrier: compare the persisted statuses against the task ids the
+// contract expects (optionally scoped to one wave). ok ⇔ every expected task is
+// DONE. Anything else (missing/running/blocked/partial) holds the barrier.
+function barrier(root, contract, opts = {}) {
+  const expected = expectedTaskIds(contract, opts.wave);
+  const byTask = new Map(listStatuses(root).map((s) => [s.task, s]));
+  const tasks = expected.map((id) => {
+    const s = byTask.get(id);
+    return { task: id, status: s ? s.status : "MISSING", commit: s ? s.commit : null, note: s ? s.note : null };
+  });
+  const count = (st) => tasks.filter((t) => t.status === st).length;
+  const done = count("DONE");
+  return {
+    ok: expected.length > 0 && done === expected.length,
+    wave: opts.wave != null ? Number(opts.wave) : null,
+    expected: expected.length,
+    done,
+    blocked: count("BLOCKED"),
+    partial: count("PARTIAL"),
+    running: count("RUNNING"),
+    missing: count("MISSING"),
+    tasks,
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+function parseFlags(argv, start) {
+  const flags = { _: [] };
+  for (let i = start; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") flags.json = true;
+    else if (a === "--cwd") flags.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) flags.cwd = a.slice(6);
+    else if (a === "--wave") flags.wave = argv[++i];
+    else if (a.startsWith("--wave=")) flags.wave = a.slice(7);
+    else if (a === "--commit") flags.commit = argv[++i];
+    else if (a.startsWith("--commit=")) flags.commit = a.slice(9);
+    else if (a === "--note") flags.note = argv[++i];
+    else if (a.startsWith("--note=")) flags.note = a.slice(7);
+    else if (a === "--phase") flags.phase = argv[++i];
+    else if (a.startsWith("--phase=")) flags.phase = a.slice(8);
+    else flags._.push(a);
+  }
+  return flags;
+}
+
+function usage() {
+  console.error([
+    "Usage:",
+    "  agent-status.js write <task> <status> [--commit H] [--note N] [--phase P] [--wave W] [--cwd DIR]",
+    "  agent-status.js read <task> [--cwd DIR] [--json]",
+    "  agent-status.js list [--cwd DIR] [--json]",
+    "  agent-status.js barrier <contract.json> [--wave W] [--cwd DIR] [--json]",
+    "  agent-status.js clear [--cwd DIR]",
+    "",
+    "status ∈ RUNNING | DONE | BLOCKED | PARTIAL",
+    "barrier exits 0 ⇔ every expected task is DONE.",
+  ].join("\n"));
+}
+
+function main(argv) {
+  const cmd = argv[2];
+  if (!cmd || cmd === "-h" || cmd === "--help") { usage(); return 2; }
+  const flags = parseFlags(argv, 3);
+  const root = path.resolve(flags.cwd || process.cwd());
+
+  if (cmd === "write") {
+    const [task, status] = flags._;
+    if (!task || !status) { usage(); return 2; }
+    try {
+      const rec = writeStatus(root, {
+        task, status, commit: flags.commit, note: flags.note, phase: flags.phase, wave: flags.wave,
+      });
+      if (flags.json) console.log(JSON.stringify(rec));
+      else console.log(`${rec.task} ${rec.status}${rec.commit ? ` @ ${rec.commit}` : ""}`);
+      return 0;
+    } catch (e) {
+      console.error(`ERROR: ${e.message}`);
+      return 2;
+    }
+  }
+
+  if (cmd === "read") {
+    const [task] = flags._;
+    if (!task) { usage(); return 2; }
+    const rec = readStatus(root, task);
+    if (!rec) { console.error(`no status for ${task}`); return 1; }
+    if (flags.json) console.log(JSON.stringify(rec));
+    else console.log(`${rec.task} ${rec.status}${rec.commit ? ` @ ${rec.commit}` : ""}${rec.note ? ` — ${rec.note}` : ""}`);
+    return 0;
+  }
+
+  if (cmd === "list") {
+    const all = listStatuses(root);
+    if (flags.json) { console.log(JSON.stringify(all, null, 2)); return 0; }
+    if (all.length === 0) { console.log("(no agent statuses)"); return 0; }
+    for (const s of all) console.log(`${s.task}  ${s.status.padEnd(8)}${s.commit ? ` @ ${s.commit}` : ""}${s.note ? ` — ${s.note}` : ""}`);
+    return 0;
+  }
+
+  if (cmd === "barrier") {
+    const [contractPath] = flags._;
+    if (!contractPath) { usage(); return 2; }
+    const loaded = pc.readContractFile(contractPath);
+    if (!loaded.ok) {
+      if (flags.json) console.log(JSON.stringify({ ok: false, ...loaded }));
+      else console.error(`${loaded.error}: ${loaded.message}`);
+      return 2;
+    }
+    const result = barrier(root, loaded.contract, { wave: flags.wave });
+    if (flags.json) { console.log(JSON.stringify(result, null, 2)); return result.ok ? 0 : 1; }
+    const scope = result.wave != null ? `wave ${result.wave}` : "phase";
+    if (result.ok) {
+      console.log(`BARRIER PASS (${scope}): ${result.done}/${result.expected} DONE`);
+    } else {
+      console.error(`BARRIER HOLD (${scope}): ${result.done}/${result.expected} DONE` +
+        ` (running=${result.running} blocked=${result.blocked} partial=${result.partial} missing=${result.missing})`);
+      for (const t of result.tasks) if (t.status !== "DONE") console.error(`  - ${t.task}: ${t.status}${t.note ? ` — ${t.note}` : ""}`);
+    }
+    return result.ok ? 0 : 1;
+  }
+
+  if (cmd === "clear") {
+    const n = clearStatuses(root);
+    console.log(`cleared ${n} status file(s)`);
+    return 0;
+  }
+
+  usage();
+  return 2;
+}
+
+module.exports = {
+  STATUSES,
+  STATUS_DIR,
+  writeStatus,
+  readStatus,
+  listStatuses,
+  clearStatuses,
+  buildActive,
+  expectedTaskIds,
+  barrier,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}