feat: build phase — machine-readable BUILD-PLAN.json and construct verify

The engine now plans and referees the build; the agent writes all app code.

- BUILD-PLAN.json emitted on every render: deterministic task DAG (T-000
  skeleton + one task per FR, milestone-ordered must→should→could, entity-
  aware dependency edges), acceptance entries POINT into SRD.json (refs,
  never copies)
- merge-by-feature-title preserves agent progress (status, artifacts, tests,
  verify commands, testCommand/appDir) across re-renders — FR ids are
  positional, titles are the stable identity
- new `construct verify`: static referee (plan well-formed + acyclic, refs
  resolve into the SRD, done tasks' files exist, FR→test coverage via the
  FR-tag grep, stale-tag detection); `--run-tests` opt-in executes the
  declared test commands; `--strict` fails a built must-have with no
  referencing test; `--json` for orchestration; status shows task progress
- SKILL.md step 8 (Build): task-by-task TDD with FR-tagged tests, verify
  after every task, `--run-tests --strict` + adversarial review per
  milestone; frontmatter triggers extended to 'build the app from the SRD'
- references/build-playbook.md (the task loop, milestone gates, what to do
  when reality pushes back) and references/verify.md (what each check proves
  and what still needs eyes)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: maxgfr

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: construct
-description: "Use when the user wants to turn a product idea into a serious, buildable requirements document (an SRD/PRD) — e.g. 'write an SRD for my app idea', 'spec out this product', 'turn my idea into requirements', 'design the requirements for X'. construct interviews the user about the product, then GROUNDS every major decision in real research — competitors and market signal (keyless web: SearXNG → DuckDuckGo → your WebSearch), comparable open-source projects and their issues/PRs (GitHub/GitLab), candidate-technology official docs and StackOverflow pitfalls, and an optional local semantic pass (Qdrant + Ollama) — writing an evidence dossier the SRD cites. It then renders a complete SRD suite (vision, scope, numbered functional requirements with Given/When/Then acceptance criteria, non-functional requirements, system context, data model, interfaces, ADRs, competitive landscape, build plan, traceability) and validates it: a HARD structural completeness gate plus an ADVISORY grounding-coverage report. Triggers: SRD, PRD, software requirements document, spec a product, requirements from an idea, greenfield product spec, idea to requirements."
+description: "Use when the user wants to turn a product idea into a serious, buildable requirements document (an SRD/PRD) — and optionally build the app from it. E.g. 'write an SRD for my app idea', 'spec out this product', 'turn my idea into requirements', 'design the requirements for X', 'build the app from the SRD', 'implement the spec'. construct interviews the user about the product, then GROUNDS every major decision in real research — competitors and market signal (keyless web: SearXNG → DuckDuckGo → your WebSearch), comparable open-source projects and their issues/PRs (GitHub/GitLab), candidate-technology official docs and StackOverflow pitfalls, and an optional local semantic pass (Qdrant + Ollama) — writing an evidence dossier the SRD cites. It then renders a complete SRD suite (vision, scope, numbered functional requirements with Given/When/Then acceptance criteria, non-functional requirements, system context, inferred data model and interfaces, ADRs, competitive landscape, build plan, traceability) and validates it: a HARD structural completeness gate plus an ADVISORY grounding-coverage report (opt-in --min-grounding threshold). For building, it emits a machine-readable BUILD-PLAN.json task DAG; the agent implements task-by-task with TDD while `construct verify` referees the app against the SRD (artifacts exist, every requirement is test-covered, suites pass). Triggers: SRD, PRD, software requirements document, spec a product, requirements from an idea, greenfield product spec, idea to requirements, build from spec, implement the SRD."
 license: MIT
 metadata:
   version: 1.0.2
@@ -41,6 +41,11 @@ No `npm install`, no API keys. Run `--help` for the full surface. Key commands:
   gate (exit ≠ 0 on an incomplete SRD) plus the ADVISORY grounding-coverage
   report. `--min-grounding N` opts into a second gate that fails below N%
   grounded claims.
+- `verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json]` — the
+  build referee: BUILD-PLAN.json well-formed and acyclic, every task ref
+  resolves into SRD.json, done tasks' files exist, every requirement is
+  referenced by a test. `--run-tests` also executes the declared test
+  commands; `--strict` fails a built must-have with no referencing test.
 - `status --out <run>` — what exists in the run so far.
 - `semantic up|down|status` — optional local Docker stack (Qdrant + Ollama +
   SearXNG).
@@ -124,6 +129,26 @@ loop to completion; only pause to ask the user a real decision.
    landscape, the grounded requirements and the key decisions (with their `[E#]`
    evidence and links). Pin any unknowns explicitly rather than guessing.
 
+8. **Build (when the user wants the app, not just the SRD).** The render also
+   emitted `BUILD-PLAN.json` — a machine-readable task DAG (T-000 skeleton +
+   one task per FR, must → should → could, entity-aware dependencies) whose
+   `acceptance` entries POINT into `SRD.json`. **You write all app code; the
+   engine referees.** Follow `references/build-playbook.md`:
+   - Do `T-000` (scaffold, test harness, CI); set `conventions.appDir` and
+     `conventions.testCommand` in `BUILD-PLAN.json`.
+   - Per task, in topological order: read the acceptance criteria from
+     `SRD.json`; TDD them — **every test names its FR id** (e.g.
+     `describe("FR-001 …")`; that's what `verify` greps); record `artifacts` +
+     `tests`; set `status: "done"`; run
+     `node scripts/construct.mjs verify --out <run>` and fix any error before
+     the next task.
+   - Per milestone: `verify --out <run> --run-tests --strict`, then a
+     milestone adversarial review — fresh eyes hunting for an acceptance
+     criterion no test actually exercises (see the playbook;
+     `references/verify.md` explains what verify can and cannot prove).
+   - If an FR proves wrong while building, amend the brief, re-render
+     (progress merges by feature title), retag shifted FR ids, re-`check`.
+
 ## What it produces (the SRD tree, under `--out`)
 
 ```
@@ -133,7 +158,8 @@ requirements/  FUNCTIONAL.md (FR-NNN · priority · Given/When/Then · [E#])
 architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
                decisions/NNNN-*.md  (ADRs)
 competitive/   LANDSCAPE.md (competitors + OSS prior art)
-BUILD-PLAN.md · TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entity ↔ interface)
+BUILD-PLAN.md · BUILD-PLAN.json (task DAG for the build phase)
+TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entity ↔ interface)
 evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json
 ```
 
@@ -165,6 +191,8 @@ See `references/semantic-setup.md`.
 - `references/acceptance-criteria.md` — bad→good Given/When/Then rewrites and measurable NFR metric patterns.
 - `references/citation-format.md` — the `[E#]` grounding convention.
 - `references/grounding-coverage.md` — what the advisory coverage report means and how to raise it.
+- `references/build-playbook.md` — the build loop: task TDD, FR-tag convention, milestone gates, the milestone review.
+- `references/verify.md` — what each `verify` check proves and what still needs eyes.
 - `references/provider-apis.md` — how OSS issues/PRs are fetched per host, keyless.
 - `references/web-discovery.md` — the layered keyless web search.
 - `references/semantic-setup.md` — the optional local Docker stack.

references/build-playbook.md

@@ -0,0 +1,87 @@
+# Build playbook — from a validated SRD to a verified app
+
+The engine plans and verifies; **you write every line of app code**. The
+contract is `BUILD-PLAN.json` (next to `BUILD-PLAN.md`): the engine derives
+its structure from the SRD on every render, and you own the progress fields.
+`construct verify` is the referee between the two.
+
+## The contract
+
+Engine-derived (a re-render refreshes these — never hand-edit):
+`id`, `title`, `milestone`, `frIds`, `acceptance` (pointers into `SRD.json` —
+read the criteria there, they are never copied), `dependsOn`,
+`conventions.frTagPattern`.
+
+Agent-owned (a re-render preserves these, keyed by the feature title):
+`conventions.testCommand`, `conventions.appDir`, and per task `artifacts`,
+`tests`, `verify.commands`, `status` (`todo` → `in-progress` → `done`).
+
+**The FR-tag convention is load-bearing.** Every test you write must name the
+FR id it exercises (in the describe/it string or a comment) — e.g.
+`describe("FR-001 save an article", …)`. This is exactly what
+`construct verify` greps (`conventions.frTagPattern`, default `FR-\d{3}`).
+No tag → the FR reads as untested, and `--strict` fails the build for
+must-haves.
+
+## Setup (once)
+
+1. Read `BUILD-PLAN.json`; topologically order the tasks by `dependsOn`
+   (milestones already order must → should → could).
+2. Do `T-000`: scaffold the app repo, choose and wire the test harness, CI.
+   Set `conventions.appDir` (app directory, relative to the run folder or
+   absolute) and `conventions.testCommand` (e.g. `pnpm test`). Mark `T-000`
+   done with its artifacts.
+
+## The task loop (every FR task)
+
+1. **Pick** the next task whose `dependsOn` are all done. Set
+   `status: "in-progress"`.
+2. **Read the spec, not your memory:** the FR's description and each
+   acceptance criterion via the task's `acceptance` pointers into `SRD.json`.
+3. **TDD against the criteria.** For each acceptance criterion, write a
+   failing test whose name carries the FR id and mirrors the Given/When/Then.
+   Implement until green. Failure-path criteria get failure-path tests.
+4. **Record:** fill `artifacts` (the source files that implement it) and
+   `tests` (the test files), both app-relative. Add any extra
+   `verify.commands` worth running for this task (lint, a smoke script).
+5. **Set `status: "done"`**, then referee:
+   ```
+   node scripts/construct.mjs verify --out <run>
+   ```
+   Static, fast — run it after EVERY task. Fix any error before moving on.
+6. **Per milestone**, run the full gate:
+   ```
+   node scripts/construct.mjs verify --out <run> --run-tests --strict
+   ```
+   It executes `testCommand` + every done task's `verify.commands`, and fails
+   if a built must-have FR has no referencing test.
+
+## The milestone review (adversarial)
+
+After each milestone passes `verify --run-tests --strict`, spawn one reviewer
+subagent (or do a hostile self-pass). Give it ONLY: the milestone's FR ids,
+their acceptance criteria from `SRD.json`, and the diff (or file list) of
+what you built. Its question: **which acceptance criterion is not actually
+exercised by any test?** A test that names an FR but asserts something weaker
+than the criterion is the main target — `verify` greps names, the reviewer
+checks honesty. Fix what it finds before starting the next milestone.
+
+## When reality pushes back
+
+- **An FR proves unimplementable / wrong as specified:** do not silently
+  build something else. Amend the brief (or `SRD.json` + the rendered docs
+  together), re-render, and re-run `check`. The plan merge keys progress by
+  feature title, so other tasks keep their status. Then retag any tests whose
+  FR ids shifted — `verify` warns about stale tags.
+- **A re-render renumbered FR ids:** `verify` reports "tests reference FR
+  id(s) absent from the SRD". Retag those tests before trusting coverage.
+- **A dependency is blocked:** mark the task back to `todo`, note why to the
+  user, and pick another ready task.
+
+## What "done" means
+
+A milestone is done when: every task is `done`, `verify --run-tests --strict`
+exits 0, and the milestone review found nothing unaddressed. The build is
+done when every milestone is — then `construct status` shows
+`build: N/N tasks done`, and you present the app against the SRD's success
+metrics, not just its file tree.

references/verify.md

@@ -0,0 +1,36 @@
+# What `construct verify` proves — and what it cannot
+
+`verify` is the deterministic referee between `BUILD-PLAN.json`, `SRD.json`
+and the app directory. Knowing exactly what each check proves keeps you (and
+the user) honest about the build.
+
+## Static checks (always run, pure reads)
+
+| Check | Proves | Does NOT prove |
+|---|---|---|
+| plan parses, schema version, unique ids | the plan is machine-readable | the plan is sensible |
+| DAG acyclic, `dependsOn` resolve | the task order is executable | the order is optimal |
+| `frIds` / `acceptance` refs resolve into SRD.json | the plan builds *this* SRD, no orphan claims | the SRD itself is right (that is `check`'s job) |
+| done tasks' `artifacts`/`tests` exist under the app dir | the declared files are real | the files do what the task says |
+| FR-tag grep over test files (`conventions.frTagPattern`) | each FR is *referenced* by at least one test | the test actually exercises the criterion — a test can name FR-001 and assert nothing |
+| stale-tag warning | tags match the current SRD's FR ids | — |
+
+Exit ≠ 0 on any hard error. `--strict` upgrades "a built must-have FR has no
+referencing test" from warning to error — use it at every milestone gate.
+
+## `--run-tests` (opt-in execution)
+
+Runs `conventions.testCommand` and every done task's `verify.commands` inside
+the app directory (your own toolchain — the engine installs nothing). Proves
+**the suite passes**. Does not prove the suite is honest: a weakened
+assertion, a skipped test, or a tautological expect all pass. It is opt-in
+because executing user-declared commands is side-effectful — never run it on
+a plan you have not read.
+
+## The gap that needs eyes
+
+Greps prove *reference*; execution proves *green*; neither proves a test
+faithfully encodes its acceptance criterion. That is the milestone
+adversarial review in `references/build-playbook.md`: a fresh reader compares
+each criterion in `SRD.json` against what the tests actually assert. Engine
+for structure, agent for honesty — same split as `check` vs. grounding.