docs: refresh README and DOCUMENTATION for analyze, min-grounding and verify

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

Author: maxgfr

DOCUMENTATION.md

@@ -15,8 +15,9 @@ CI verifies the committed bundle is reproducible (`pnpm run check:build`).
 ## Pipeline
 
 ```
-init → (interview, agent-driven) → research → render → check
-brief.json          evidence/                SRD tree + SRD.json   report
+init → (interview, agent-driven) → research → analyze → render → check → verify
+brief.json          evidence/         gap report   SRD tree + SRD.json   report   build referee
+                                                   + BUILD-PLAN.json
 ```
 
 ### `init`
@@ -41,13 +42,24 @@ subprocesses through `util.ts::sh` — the two mock seams that make the rest
 offline-testable. Every angle degrades honestly to an empty result with a note
 rather than aborting the run.
 
-### `render`  (`src/render.ts`, `src/srd.ts`, `src/templates.ts`)
+### `analyze`  (`src/analyze.ts`)
+The post-research gap signal. Pure read of `brief.json` + the dossier that
+reuses the render's own `matchEvidence`, so every reported gap is a claim that
+WILL render ungrounded: features with no matchable evidence, competitors the
+market angle never surfaced, candidate tech without docs/SO grounding, unmined
+OSS seeds — each with the drill command that fixes it. Informational; exit 0.
+
+### `render`  (`src/render.ts`, `src/srd.ts`, `src/templates.ts`, `src/plan.ts`)
 `buildSRD(brief, evidence, {level})` assembles a pure, deterministic SRD model
 (`src/srd.ts`): one FR per feature with templated Given/When/Then, the required
-NFRs for the level, ADRs from the candidate stack, a competitive table, a build
-plan and a traceability matrix. Evidence `[E#]` hooks are auto-attached by
-keyword overlap (`matchEvidence`). `templates.ts` turns each model slice into
-Markdown (pure, golden-testable); `render.ts` writes the tree + `SRD.json`.
+NFRs for the level, an *inferred* data model and interface set (recurring nouns
++ boundary detection, FR references closed symmetrically), ADRs from the
+candidate stack, a competitive table, a build plan and a traceability matrix.
+Evidence `[E#]` hooks are auto-attached by keyword overlap (`matchEvidence`).
+`templates.ts` turns each model slice into Markdown (pure, golden-testable);
+`render.ts` writes the tree + `SRD.json` + `BUILD-PLAN.json` (`src/plan.ts`:
+`derivePlan` builds the task DAG from the SRD; `mergePlan` preserves the
+building agent's progress across re-renders, keyed by feature title).
 
 Conventions: `> 🧠 **Decide:**` for open decisions; `[E#]` for grounded claims.
 
@@ -57,7 +69,18 @@ Two independent passes:
   acceptance criteria and resolving entity/interface/NFR references; required
   NFR categories present for the level; ADRs well-formed; required files present.
 - **Grounding coverage (advisory):** per-section grounded fraction, dangling
-  `[E#]`, uncited evidence. Never changes the exit code.
+  `[E#]`, uncited evidence, renderer-templated criteria nudges. Never changes
+  the exit code — unless the caller opts into `--min-grounding <0-100>`, which
+  adds a third gate failing below the threshold.
+
+### `verify`  (`src/verify.ts`)
+The build referee. Static by default: `BUILD-PLAN.json` well-formed and
+acyclic, every `frIds`/`acceptance` ref resolves into `SRD.json`, done tasks'
+declared artifacts/tests exist under the app dir, and every FR is referenced by
+a test (greps `conventions.frTagPattern` over test files via `walk.ts`; stale
+tags after an id shift are flagged). `--run-tests` opts into executing
+`conventions.testCommand` + per-task `verify.commands` (via `util.ts::sh`);
+`--strict` fails a built must-have FR with no referencing test.
 
 ## The three axes
 
@@ -72,6 +95,10 @@ Two independent passes:
   openQuestions.
 - `evidence/evidence.json` — `EvidenceItem[]` with stable `E#` ids.
 - `SRD.json` — the full `SRD` manifest the `check` reads.
+- `BUILD-PLAN.json` — `BuildPlanDoc`: engine-derived task structure (ids,
+  milestones, `acceptance` pointers into `SRD.json`, dependency edges) +
+  agent-owned progress (`status`, `artifacts`, `tests`, `verify.commands`,
+  `conventions.testCommand`/`appDir`) that survives re-renders.
 
 ## Release
 

README.md

@@ -19,11 +19,18 @@ by Conventional Commits.
    - **oss** — comparable open-source projects + their issues/PRs (GitHub/GitLab),
    - **tech** — candidate-technology docs + StackOverflow pitfalls,
    - **semantic** *(optional)* — a local-embedding relevance pass (Qdrant + Ollama).
-3. **Render** a complete SRD tree (vision, scope, numbered functional requirements
-   with Given/When/Then, non-functional requirements, system context, data model,
-   interfaces, ADRs, competitive landscape, build plan, traceability) + `SRD.json`.
-4. **Check** it: a **hard** structural-completeness gate plus an **advisory**
-   grounding-coverage report.
+3. **Analyze** the dossier: name every feature/competitor/tech/seed that would
+   render ungrounded, with the drill command that fixes each gap.
+4. **Render** a complete SRD tree (vision, scope, numbered functional requirements
+   with Given/When/Then, non-functional requirements, system context, an
+   *inferred* data model and interfaces, ADRs, competitive landscape, build plan,
+   traceability) + `SRD.json` + a machine-readable `BUILD-PLAN.json` task DAG.
+5. **Check** it: a **hard** structural-completeness gate plus an **advisory**
+   grounding-coverage report (opt-in `--min-grounding` threshold).
+6. **Verify** the build *(optional)*: the agent implements the app task-by-task
+   from `BUILD-PLAN.json`; `construct verify` referees it against the SRD —
+   declared files exist, every requirement is referenced by a test, and (with
+   `--run-tests`) the declared test commands pass.
 
 No API keys. No `npm install` at skill-use time.
 
@@ -39,8 +46,10 @@ npx skills add maxgfr/construct
 node scripts/construct.mjs init --idea "a self-hosted read-it-later app" --out ./readpile
 # …fill ./readpile/brief.json via the interview…
 node scripts/construct.mjs research --out ./readpile --angles market,oss,tech
+node scripts/construct.mjs analyze  --out ./readpile          # what's thin? drill it
 node scripts/construct.mjs render   --out ./readpile --level complex
-node scripts/construct.mjs check    --out ./readpile
+node scripts/construct.mjs check    --out ./readpile          # add --min-grounding 70 to enforce
+node scripts/construct.mjs verify   --out ./readpile --app ./readpile-app --run-tests --strict
 ```
 
 Add `--merge` to also emit a single-file `SRD.md`. Run `--help` for the full
@@ -54,7 +63,7 @@ surface, or see [`SKILL.md`](SKILL.md) for the agent playbook and
 requirements/  FUNCTIONAL.md · NON-FUNCTIONAL.md
 architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md · decisions/NNNN-*.md
 competitive/   LANDSCAPE.md
-BUILD-PLAN.md · TRACEABILITY.md
+BUILD-PLAN.md · BUILD-PLAN.json (task DAG for the build phase) · TRACEABILITY.md
 evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json
 ```
 
@@ -64,7 +73,9 @@ evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SR
 on an incomplete SRD (unresolved `🧠` decisions, an FR with no acceptance
 criteria, a dangling reference, a missing required NFR category, a malformed
 ADR). The **grounding coverage** is a report — it tells you how well-cited the
-SRD is so you can invest research where it matters, but it never fails the build.
+SRD is so you can invest research where it matters, but it never fails the build
+by default. When you *do* want it enforced, `--min-grounding <0-100>` opts into
+a second gate that fails below the threshold.
 
 ## Optional local stack