qualia-framework 6.9.2 → 6.22.0

package/AGENTS.md

@@ -1,3 +1,5 @@
+<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->
+
 # Qualia Framework
 
 Company: Qualia Solutions — Nicosia, Cyprus
@@ -8,17 +10,18 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 
 ## Hard rules (non-negotiable)
 - **Read before Write/Edit** — *every edit is informed by the current state of the file.*
-- **Feature branches only** — *changes ship through review; main is always deployable.*
-- **MVP first** — *build the minimum that demonstrates the goal.*
+- **Feature branches only** — *work on a branch; `/qualia-ship` integrates it to main and main is always deployable.*
+- **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
 - **Root cause on failures** — *understand the why before patching the symptom.*
 - **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*
 
 ## Discoverable substrate (load on demand, not always)
-- `/qualia-road`, `FLAGS.md`, `guide.md` — every active command + flag (canonical surface)
+- `rules/constitution.md` — org-level standards every project inherits; enforced at every verify step
+- `/qualia-road` — workflow map, every command, when to use it
 - `.planning/CONTEXT.md` — project domain glossary (loaded by road agents)
 - `.planning/decisions/` — ADRs for hard-to-reverse decisions
-- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — on relevant tasks only
-- `qualia-design/frontend.md` `qualia-design/design-laws.md` — on design/frontend tasks only
+- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — read on relevant tasks only
+- `qualia-design/frontend.md` `qualia-design/design-laws.md` — read on design/frontend tasks only
 
 ## Lost?
 `/qualia` — state router tells you the next command.

package/CHANGELOG.md

@@ -8,6 +8,214 @@ 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.22.0] - 2026-06-21 (session continuity + ERP project-sync — built by two parallel worktree agents)
+
+Two independent continuity features, built concurrently in isolated git worktrees and integrated together.
+
+### Added — B1: `/qualia` surfaces the latest session report at session start (`bin/last-report.js`)
+- Finds the newest `.planning/reports/report-*.md` (filename date desc, mtime tiebreak) and extracts a tight digest: `{ found, file, date, summary, next, age_days }` — summary from the report's `## What Was Done`, next-step from `## Next Steps`, markdown-flattened and capped. `--json`, `--cwd`, `--now ISO` (deterministic age); exit 0 found / 1 none / 2 bad input.
+- Wired into the `/qualia` router "Get State" step: when a project is loaded, the router prints the last-session digest at the TOP of its output, so the operator — or a teammate picking the project up — instantly sees where work was left off. `tests/last-report.test.sh` (28 assertions).
+
+### Added — B2: full project-sync reconciliation payload for the ERP (`bin/project-sync.js`)
+- A single deterministic snapshot the ERP can reconcile a whole project from: identity + lifecycle/launched_at, `milestones[]` (closed/current/future + per-milestone REQ-ID completion + phases/tasks/deployed_url), current position, `task_rollup`, `accountability` (offroad), `integration` (the trunk-merge model), and a `schema_version`. **Composes** `project-snapshot.js` (reuses its builders) rather than duplicating or bloating that stable endpoint. `--json`/`--write`/`--pretty`; read-only; graceful on missing JOURNEY/REQUIREMENTS. `tests/project-sync.test.sh` (38 assertions).
+- `docs/erp-contract.md`: new "Project Sync Payload" section — every field, the server-side reconciliation steps, and the PR/merge model (branch → main at ship → deploy; main-push accountability). Explicit **Framework-emits vs ERP-backend-ingests** split.
+- **Backend remains (out of this repo):** a `POST /api/v1/project-sync` endpoint + server reconciliation (upsert milestones by num, completion from REQ counts, roll up phases/tasks, store offroad, encode the merge model). The framework emits + documents; it does not POST yet (the ERP team mirrors `project-snapshot.js`'s upload plumbing once the endpoint exists).
+
+run-all now 19 suites; both bins in the manifest + install-set; all suites green.
+
+## [6.21.0] - 2026-06-21 (work-unit goals on both runtimes — Codex /goal + the Claude Code equivalent)
+
+Every defined unit of work should declare one objective + one budget, so it stays anchored and the operator sees burn-vs-budget. The framework had this for Codex (`/goal`) but `rules/codex-goal.md` explicitly told Claude Code to "skip — no equivalent surface." Claude Code DOES have an equivalent (the session task-list + turn budget); this wires it up and broadens goal-setting to every work-unit skill.
+
+### Changed — `rules/codex-goal.md` is now a both-runtimes "work-unit goal" rule
+- One shared helper (`codex-goal.js {scope}`, via the host-adapter-rendered `${QUALIA_BIN}`) produces the objective + token budget from STATE.md/ROADMAP.md.
+- **Codex** path unchanged: native `/goal` / `update_goal`.
+- **Claude Code** path (new): set the goal via the harness **task-list** (a tracked task titled with the objective, in_progress→completed) + state the budget in the banner. Same discipline — one named objective + budget per unit — native surface on each runtime.
+
+### Changed — goal-setting wired into every work-unit skill
+- Existing blocks in `/qualia-plan`, `/qualia-build`, `/qualia-feature` relabeled from "Codex goal (Codex runtime only)" to runtime-neutral **"Set the work-unit goal."**
+- Added to `/qualia-fix` (scope `quick`/`feature`) and `/qualia-update` (scope `feature` — it runs its own lean loop without `/qualia-plan`, so it needs its own goal). `/qualia-milestone` deliberately omitted — it routes into `/qualia-plan`, which sets the goal (no double-set).
+
+No bin or schema change; all 17 suites pass.
+
+## [6.20.0] - 2026-06-21 (scope integrity — the roadmap finishes the project, and the team can't drift off it)
+
+The deepest fix this cycle. Teams were drifting off-plan — inventing milestones, building features with no link to the roadmap — and the root cause was upstream: **`/qualia-new` under-scoped the project** (a v1 slice capped at 5 milestones, overflow dumped into an unplanned "v2"), so the agreed work literally wasn't in the arc and the team was *forced* to improvise. Two layers: make genesis cover the whole project, then bind the team to it. (Layer 1 shipped in the prior commit; this entry covers the full feature.)
+
+### Layer 1 — genesis covers the whole project (commit `feat(genesis)`)
+- **Interview reworked** (`templates/project-discovery.md`): added §9 **capability inventory** (every capability needed for DONE — the whole thing) + §10 **whole-project definition-of-done**; dropped the old §9 "stop at 3–5 chapters" self-cap. Full path 14 → 15 questions, refocused from brand-vibe to functional completeness.
+- **Milestone cap removed** (`agents/roadmapper.md`, `templates/journey.md`, `templates/requirements.md`): the arc spans until the §9 inventory reaches the §10 done-state — as many milestones as needed. `Post-Handoff`/`Out of Scope` holds ONLY explicit client deferrals (§8), never overflow. Handoff optional for internal/ongoing products.
+- **Coverage gate** (`/qualia-new` Step 14): genesis refuses to present a journey that leaves any §9 capability unmapped (0 unmapped before the approval ladder).
+
+### Layer 2 — bind the team to the arc (this commit)
+- **Milestone close gates on requirements** (`bin/state.js`): new `MILESTONE_REQS_INCOMPLETE` — close refuses (strict) / warns (standard) when a REQ-ID mapped to the milestone in REQUIREMENTS.md isn't `Complete`. Stops "finishing a milestone with scope still open". New `state.js reqs-check [--milestone N]` exposes the same check (exit 0/1) for `/qualia-milestone` to show coverage before closing.
+- **Off-road work is recorded, not silent** (`bin/state.js` note path): `transition --to note` gains `--scope in|off --ref {REQ/why}`. Off-road work increments `lifetime.offroad_count` and appends to an `offroad[]` ledger (OWNER + ERP visible), mirroring branch-guard's accountability model.
+- **`/qualia-feature` + `/qualia-fix` scope gate**: before building, both check the active milestone. In-scope → proceed, tagged `--scope in`. Off-road → **strict blocks** (route to `/qualia-scope`/`/qualia-milestone` to fold it into the arc) / **standard records** (`--scope off`, counted). The drift vector the user named is now governed at the source.
+
+### Tests
+- `tests/state.test.sh`: +5 cases — `reqs-check` (complete/incomplete/milestone-filter/untracked), `--scope off` tally + ledger, `--scope in` no-op, `--force` bypass. 96 state assertions green; all 17 suites pass. (Genesis is prose/templates — validated by the skills + refs suites.)
+
+## [6.19.0] - 2026-06-21 (trunk integration — ship is the merge point, report sweeps)
+
+Fixes a real lifecycle gap + doc drift: **no skill ever integrated feature → main.** Branches/PRs accumulated with nothing closing them; `/qualia-ship` deployed *from the feature branch* and said "never push to main," so production ran branch code while `main` lagged ("main is always deployable" was false in practice); and three sources disagreed on the policy (the hard rule said "through review", `branch-guard` 6.10 said "accountability not block", `infrastructure.md` still claimed PR-review was enforced). This completes the 6.10 "accountability over block" turn into a coherent trunk model.
+
+### Changed — `/qualia-ship` integrates to main, deploys from main, closes the branch
+- New §3: commit → fast-forward-integrate the feature branch into `main` (auto-rebase if `main` moved; STOP on conflict) → push. `branch-guard` records the main push (accountability). §4 deploys from `main` HEAD, so the deployed artifact == `main` byte-for-byte. New §4b deletes the integrated branch on a verified deploy. The normal path now leaves **zero lingering branches/PRs**.
+
+### Added — `bin/branch-hygiene.js` + `/qualia-report` sweep (the safety net)
+- `branch-hygiene.js`: read-only clock-out sweep — finds local branches with commits **ahead of `main` that were never shipped** (stranded work) and **stale open PRs** (best-effort via `gh`, skipped when absent). Exit 0 clean / 1 found / 2 not-a-repo; `--json`; library `analyze`. Detects `main` or `master` as base.
+- `/qualia-report` Step 5b runs it so stranded work surfaces to the employee + OWNER at clock-out instead of rotting.
+
+### Fixed — policy drift now single-voiced
+- `rules/infrastructure.md`: the stale "main requires PR reviews (enforced by guards)" line replaced with the real model (integrate-at-ship; main pushes allowed + recorded; report sweeps; keep GitHub branch protection off, or switch ship to an auto-merged PR if you re-enable it).
+- Canonical hard rule (`templates/instructions.md` → recompiled `CLAUDE.md`/`AGENTS.md`): "ship through review" → "`/qualia-ship` integrates it to main." Drift guard green.
+
+### Tests
+- `tests/branch-hygiene.test.sh` (new, 13 cases): not-a-repo, clean, stranded branch (ahead count + json), ff-merged-no-longer-stranded, `master` base detection, `analyze()` lib. run-all now 17 suites; manifest + `lib.test.sh` install set updated.
+
+## [6.18.0] - 2026-06-21 (v7 kernel, step 8 — R7: /qualia-eval lane for AI features)
+
+Qualia gates UI and code — `contract-runner` proves the code exists, `verify-panel` proves it's correct — but it had **no gate for the AI artifacts a project builds**. "The chatbot answers the refund question" / "the RAG answer is grounded" / "the agent stays under 2s" is not checkable by a grep. R7 adds the equivalent gate, layered: cheap deterministic assertions first, model judgment only where a model is required.
+
+### Added — `bin/eval-runner.js` (layered assertion runner, zero-dependency)
+- Runs an eval suite (JSON — no YAML parser pulled in) of cases against captured AI outputs. **Deterministic assertion types** settled with no model: `contains`, `not_contains`, `equals`, `regex`, `not_regex`, `min_length`, `max_length`, `json_valid`, `json_path` (`equals`/`contains`), `max_latency_ms`, `max_cost_usd`. Outputs inline or via `output_file`.
+- **`llm_rubric`** is the only model-dependent type — it carries a `verdict` (pass|fail) the skill fills by spawning a judge BEFORE the runner (same pattern `verify-panel` uses for skeptic votes). An unjudged rubric is PENDING and **fails** the suite — never a silent pass. Asserting a latency/cost budget with no metric recorded also fails (no silent pass).
+- Exit 0 = all cases pass, 1 = failure/unjudged, 2 = bad input. `--write` emits `.planning/evals/eval-{feature}.json`. Library exports `run`, `runAssertion`, `getPath`.
+
+### Added — `/qualia-eval` skill (new active surface)
+- The lane: capture the AI feature's real outputs → spawn one judge per `llm_rubric` (reusing the `qualia-verifier` agent, role-anchored) → `eval-runner.js` settles deterministic assertions + folds in verdicts → gate. Usable standalone (`/qualia-eval suite.json`) or as a phase verify-step gate (`/qualia-eval {N}`), where a FAIL has the same standing as a failing contract. Registered in `command-surface.js` `ACTIVE_SKILLS`.
+
+### Tests
+- `tests/eval-runner.test.sh` (new, 19 cases): deterministic pass/fail, latency budget (incl. missing-metric → fail), `json_valid`/`json_path`, `llm_rubric` pass/fail/pending, `output_file` resolution + graceful missing-file, `--write` artifact, `runAssertion`/`getPath` units, malformed→exit 2. run-all now 16 suites; manifest + `lib.test.sh` install set updated; `qualia-eval` passes the skill smoke + refs suites.
+
+## [6.17.0] - 2026-06-21 (v7 kernel, step 7 — R16: dependency-derived wave width + --parallel knob)
+
+`/qualia-build` spawned EVERY task in a contract "wave" concurrently, with no cap — two failure modes at once: over-serialization (the planner's hand-numbered waves can be deeper than the dependency graph requires) and over-parallelization (a wide wave spawns 9 builders past the 3–5 sweet spot where coordination cost overwhelms the gain — the LangGraph `max_concurrency` lesson). R16 replaces orchestrator guesswork with a deterministic scheduler derived from the task DAG.
+
+### Added — `bin/wave-plan.js` (deterministic build scheduler, zero-dependency)
+- Recomputes **minimal-depth waves** from `depends_on` (topological levels = maximal safe parallelism), then splits each level into **batches capped at `max_concurrency`**. Output is an ordered `batches[]` the orchestrator spawns one at a time. Same contract + cap → same schedule.
+- `max_concurrency`: `--parallel N` → exactly N; **auto** (default) → 1 if <3 tasks ("don't parallelize tiny phases"), else 5.
+- Flags **over-serialization** (a task whose declared wave is deeper than the DAG requires — the schedule runs it earlier) and wide-level capping. Cycle in the DAG → exit 1; library exports `deriveLevels`, `resolveConcurrency`, `plan`.
+
+### Changed — `/qualia-build` consumes the derived schedule
+- **§2** now runs `wave-plan.js .planning/phase-{N}-contract.json [--parallel K] --json` and spawns the emitted batches in order (not the raw contract `wave` numbers, not all-at-once). New `--parallel K` usage knob.
+- **Batch fan-in barrier:** `agent-status.js` (R2) gains a `barrier --tasks T1,T2` mode that gates on an explicit batch (no contract needed) — required because derived waves needn't match the contract's declared wave numbers, so the per-wave barrier would mismatch. The build now barriers per batch, keeping R16 + R2 coherent.
+
+### Tests
+- `tests/wave-plan.test.sh` (new, 23 cases): chain/independent/tiny/diamond DAGs, auto vs `--parallel` cap, wide-level batching, over-serialization flag, cycle→exit 1, `deriveLevels`/`resolveConcurrency` units. `tests/agent-status.test.sh` +3 `barrier --tasks` cases. run-all now 15 suites; manifest + `lib.test.sh` install set updated.
+
+## [6.16.0] - 2026-06-21 (v7 kernel, step 6 — R8: verifier panel + adversarial skeptics)
+
+A single LLM judge is adversarially fragile — the literature puts a lone stray token at ~35% false positives, and self-grading bias hides ~70% of findings. `/qualia-verify` was a single cooperative verifier with an optional second pass. R8 replaces it with a **panel** (one verifier per lens) + **per-finding skeptics** (majority-survives), and — crucially — makes the SURVIVE/KILL and PASS/FAIL decision **deterministic math**, not another LLM judgment.
+
+### Added — `bin/verify-panel.js` (deterministic aggregator, zero-dependency)
+- **`aggregate(panel)`**: dedupes findings across lenses (same `file:line:title` → one finding; highest severity wins, lenses union, votes sum), applies **majority-survives** (a finding is killed only when skeptics are a strict majority calling it not-real — ties and unvoted findings survive: unverified ≠ disproven), and computes category + per-lens scores via the **`rules/grounding.md` formula** (`5 − floor(weighted_sum/8)`). Verdict FAIL iff any surviving CRITICAL/HIGH. Exit 0 = PASS, 1 = FAIL.
+- **`assemble <phase>`**: globs the per-lens `phase-{N}-panel-{lens}.json` files into one `phase-{N}-panel.json` skeleton (votes zeroed) so the orchestrator never hand-builds the panel.
+- `--write` emits `.planning/phase-{N}-verification-panel.{json,md}`. Library exports (`aggregate`, `dedupeFindings`, `survives`, `scoreFromCounts`, `assemble`) for reuse.
+
+### Changed — `/qualia-verify` is now panel-based
+- **§3 Panel:** spawns one `qualia-verifier` per *relevant* lens (correctness always; security/performance/design by what the phase touches — cost scales to risk, not a flat 4×), in parallel, each anchored on the same contract-run + harness-eval evidence as shared ground truth, each emitting structured findings JSON.
+- **§3c Skeptics + aggregation:** assemble → 3 skeptics per CRITICAL/HIGH finding (5 with `--adversarial`/Handoff/security lens), each prompted to *refute* with evidence → tally votes → `verify-panel.js` produces the verdict. MEDIUM/LOW auto-survive (documented cost bound, not a silent cap). The old single-verifier + adversarial-second-pass sections are replaced.
+- **§4:** the phase is PASS only if the panel verdict, harness-eval, AND anti-slop all agree. Reuses the existing `qualia-verifier` agent (lens/skeptic are prompt modes — no new agent registration).
+
+### Tests
+- `tests/verify-panel.test.sh` (new, 28 cases): empty→PASS, surviving CRITICAL→FAIL, skeptic-killed→PASS, tie/no-vote survive, cross-lens dedupe (severity-max + vote-sum + lens-union), grounding-formula scores, MEDIUM/LOW-only→PASS, `--write` artifacts, `assemble` round-trip, malformed→exit 2. Registered in `run-all.sh` (now 14 suites); `lib.test.sh` trust-score install set carries `verify-panel.js`.
+
+## [6.15.0] - 2026-06-21 (v7 kernel, step 5 — R4+R5: single-source the dual-runtime surface)
+
+Dual-runtime drift is the #1 risk of supporting both Claude Code and Codex. `CLAUDE.md` and `AGENTS.md` were hand-maintained twins — and they *had already drifted* (the MVP-first line and the substrate list differed between them). This batch makes that class of bug unmergeable: one canonical source, compiled per host, with a drift guard in CI.
+
+### Added — R4: one canonical instruction source, compiled to both files
+- **`templates/instructions.md`** is now the single source of truth. `CLAUDE.md` and `AGENTS.md` are **generated artifacts** (committed, like a lockfile) carrying a `GENERATED` header.
+- **`bin/compile-instructions.js`** compiles the canonical into both files. `--check` mode is the **drift guard**: it exits non-zero if either committed file is stale, making "edited one twin, forgot the other" impossible to merge. Wired into the test suite + an `npm run compile:instructions` script.
+- Host-specific content uses conditional blocks (`<!--QUALIA-HOST claude-->…<!--/QUALIA-HOST-->`): the Claude file keeps the Pocock budget note, the Codex file keeps the cross-vendor (Cursor/Continue/Aider/Devin) note — the **body is byte-identical**, only the footer differs. The pre-existing drift is resolved (AGENTS.md regained the full MVP-first line + the constitution substrate entry).
+
+### Changed — R5: `host-adapters.js` is now the single per-host contract
+- The adapter is the **one place** anything runtime-specific is declared: `instructionFile`, `configFile`, `agentDir`, `agentExt`, and the Claude→Codex `naming` map (lifted out of a hardcoded swap buried in `renderText`). Nothing else branches on runtime — callers ask the adapter. A third runtime becomes one `HOSTS` entry, not a grep-and-patch.
+- Render pipeline split into composable stages: `applyNaming` (display-string swaps) + `applyPaths` (`${QUALIA_*}` tokens + `.claude→.codex`), with `renderText = applyPaths∘applyNaming` (unchanged public behavior) and `compileInstructions = applyNaming∘stripHostBlocks` (naming + blocks, paths/`{{ROLE}}` left for install).
+- **`install.js`** now routes both instruction files through `adapter(host).instructionFile` and renders `AGENTS.md` with `codexText()` — a **latent bug fix**: CLAUDE.md always got token/path rendering, AGENTS.md never did, so any `${QUALIA_*}`/`.claude/` reference in the Codex file would have shipped unresolved.
+
+### Tests
+- `tests/instructions.test.sh` (new, 25 cases): drift guard passes on HEAD + fails on an uncompiled canonical edit (with restore); CLAUDE/AGENTS bodies identical + host-specific footers preserved; adapter contract facts; `stripHostBlocks` keep/drop per host; `compileInstructions` swaps naming but leaves tokens/`{{ROLE}}`; `renderText` path regression. Registered in `run-all.sh` (now 13 suites). End-to-end install verified: both files render with the role substituted and correct footers.
+
+## [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`

package/CLAUDE.md

@@ -1,3 +1,5 @@
+<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->
+
 # Qualia Framework
 
 Company: Qualia Solutions — Nicosia, Cyprus
@@ -8,7 +10,7 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 
 ## Hard rules (non-negotiable)
 - **Read before Write/Edit** — *every edit is informed by the current state of the file.*
-- **Feature branches only** — *changes ship through review; main is always deployable.*
+- **Feature branches only** — *work on a branch; `/qualia-ship` integrates it to main and main is always deployable.*
 - **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
 - **Root cause on failures** — *understand the why before patching the symptom.*
 - **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*

package/agents/roadmapper.md

@@ -83,23 +83,23 @@ Organize requirements under `## Milestone 1 · {Name}`, `## Milestone 2 · {Name
 This is the most important step.
 
 **Hard rules:**
-- **Ceiling: 5 milestones** (including Handoff). If the project needs more, defer remainder to post-handoff v2.
+- **The arc must cover the ENTIRE agreed scope.** Every capability in discovery §9 (the capability inventory) gets a REQ-ID and lands in a milestone; the arc continues until the §10 whole-project done-state is reached. **There is NO milestone ceiling** — plan as many milestones as the scope genuinely needs. Do NOT compress real work into a 5-milestone cap, and do NOT dump overflow into "v2": the only deferred work is what the client explicitly listed in discovery §8 (Out of Scope). If you find yourself wanting to defer agreed work to make the arc shorter, that's the exact failure that forces the team to improvise later — don't.
 - **Floor: 2 milestones** (one feature milestone + Handoff). If smaller, the project should use `/qualia-new --quick` instead.
-- **Final milestone is ALWAYS "Handoff"** with 4 standard phases: Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + domain transfer).
+- **Final milestone is "Handoff"** for client projects, with 4 standard phases: Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + domain transfer). For an internal or ongoing product (no client takeover — see discovery §10/§11), Handoff may be omitted; the arc ends at the milestone that reaches the done-state.
 - **Every non-Handoff milestone must have ≥ 2 phases** OR be an explicit shipped release gate. Single-phase milestones are phases, not milestones — merge them into the preceding milestone.
 - **Milestones are ordered by dependency, not priority.** M2 must be able to use M1's outputs.
 
-**Typical milestone arcs by project type:**
+**Typical milestone arcs by project type (STARTING POINTS, not caps — extend until §9 is fully covered):**
 
-| Type | Arc |
+| Type | Arc (minimum shape — add milestones as the capability set requires) |
 |---|---|
-| Landing / marketing | 2 milestones: Foundation → Handoff |
-| SaaS / dashboard | 4 milestones: Foundation → Core Features → Admin & Reporting → Handoff |
-| Voice / AI agent | 4 milestones: Foundation → Core Flow → Integrations → Handoff |
-| Mobile app | 5 milestones: Foundation → Core → Offline & Notifications → Store Prep → Handoff |
-| Multi-tenant platform | 5 milestones: Foundation → Core → Admin → Scale → Handoff |
+| Landing / marketing | Foundation → Handoff |
+| SaaS / dashboard | Foundation → Core Features → Admin & Reporting → … → Handoff |
+| Voice / AI agent | Foundation → Core Flow → Integrations → … → Handoff |
+| Mobile app | Foundation → Core → Offline & Notifications → Store Prep → … → Handoff |
+| Multi-tenant platform | Foundation → Core → Admin → Scale → … → Handoff |
 
-Use the research SUMMARY.md as your starting point. Don't force-fit the template — shape to this specific project.
+These are floors, not ceilings. Use the research SUMMARY.md and the §9 capability inventory as your real input — the table just shows the smallest sensible shape. Don't force-fit it; a project with 30 agreed capabilities will have more milestones than one with 6, and that is correct.
 
 **For each milestone:**
 - **Name** — short and evocative (e.g., "Core Feature Loop", not "Phase 2 Work")
@@ -124,11 +124,13 @@ For each phase in the milestone(s) you're detailing:
 ### 5. Validate Coverage
 
 Before writing, verify:
-- [ ] Every v1 requirement (all milestones excluding Handoff) has a REQ-ID
-- [ ] Every v1 requirement maps to exactly one milestone
+- [ ] **Every capability in discovery §9 has a REQ-ID** (the whole inventory, not a v1 slice)
+- [ ] Every requirement maps to exactly one milestone, and **every §9 capability is covered by some milestone** — nothing agreed is left unplanned
+- [ ] The final milestone reaches the discovery §10 whole-project done-state
+- [ ] The ONLY items in `Post-Handoff (v2)` / `Out of Scope` are the ones the client explicitly deferred in discovery §8 (no overflow from a milestone cap — there is no cap)
 - [ ] Every milestone has ≥ 2 phases (except Handoff which has the fixed 4)
-- [ ] Milestone count is 2-5 total
-- [ ] Final milestone is literally named "Handoff" with the 4 standard phases
+- [ ] Floor met: ≥ 2 milestones total (no upper bound)
+- [ ] Final milestone is "Handoff" with the 4 standard phases (client projects), or the done-state milestone (internal/ongoing products)
 - [ ] No milestone depends on a later milestone
 - [ ] Milestone 1 has full phase-level detail (goals + success criteria) ready for `/qualia-plan 1`
 - [ ] If `full_detail=false` (default): M2..M{N-1} have phase names + one-line goals (sketch, not full detail)

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,264 @@
+#!/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 expected task ids.
+// Expected set = an explicit opts.tasks list (used by wave-plan batches, whose
+// derived waves needn't match the contract's declared wave numbers), else the
+// contract task ids optionally scoped to opts.wave. ok ⇔ every expected task is
+// DONE. Anything else (missing/running/blocked/partial) holds the barrier.
+function barrier(root, contract, opts = {}) {
+  const expected = Array.isArray(opts.tasks) && opts.tasks.length
+    ? opts.tasks
+    : 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 === "--tasks") flags.tasks = argv[++i];
+    else if (a.startsWith("--tasks=")) flags.tasks = a.slice(8);
+    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 barrier --tasks T1,T2 [--cwd DIR] [--json]   (batch gate; no contract needed)",
+    "  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._;
+    const taskList = flags.tasks ? flags.tasks.split(",").map((s) => s.trim()).filter(Boolean) : null;
+    // --tasks gates on an explicit batch; otherwise the contract supplies the set.
+    let contract = null;
+    if (!taskList) {
+      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;
+      }
+      contract = loaded.contract;
+    }
+    const result = barrier(root, contract, { wave: flags.wave, tasks: taskList });
+    if (flags.json) { console.log(JSON.stringify(result, null, 2)); return result.ok ? 0 : 1; }
+    const scope = taskList ? `batch ${taskList.join(",")}` : (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));
+}