fix: enforce non-empty FR in check, drop stale SRD.md, note tech cap

Found and fixed by exercising the skill end-to-end against real product
ideas (privacy analytics, meal-planning, password manager) plus hostile
and degenerate briefs:

- check: an SRD with zero functional requirements now fails the hard
  structural gate instead of only warning. This matches the gate already
  failing when a single FR is missing acceptance criteria, and stops the
  SKILL.md "loop until check passes" flow from terminating on an empty
  scaffold ("nothing to build" is not a complete, buildable SRD).
- render: remove a stale SRD.md left behind by a prior `--merge` run when
  re-rendering without `--merge`, so `check` no longer validates outdated
  merged content (e.g. an already-resolved decision callout). Same hygiene
  the decisions/ directory already gets.
- research/tech: surface an honest note when candidateTech is capped to
  the first 3 technologies, instead of silently dropping the rest.

Adds a regression test per fix and rebuilds the zero-dep bundle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: maxgfr

SKILL.md

@@ -79,9 +79,9 @@ loop to completion; only pause to ask the user a real decision.
 
 5. **Validate (two layers).**
    - *Structural (hard):* `node scripts/construct.mjs check --out <run>`. It
-     fails on any unresolved `🧠`/TODO, an FR with no acceptance criteria, a
-     dangling entity/interface/NFR reference, a missing required NFR category, or
-     a malformed ADR. Fix until it passes.
+     fails on any unresolved `🧠`, no functional requirements at all, an FR with
+     no acceptance criteria, a dangling entity/interface/NFR reference, a missing
+     required NFR category, or a malformed ADR. Fix until it passes.
    - *Grounding (advisory):* the same command prints coverage — what fraction of
      requirements/decisions cite evidence. Raise it where it matters (the load-
      bearing decisions); see `references/grounding-coverage.md`. It never fails

scripts/construct.mjs

@@ -1092,10 +1092,16 @@ ${body || "(no body)"}`,
 
 // src/research/tech.ts
 async function techAngle(ctx) {
-  const techs = ctx.brief.candidateTech.slice(0, 3);
+  const allTechs = ctx.brief.candidateTech;
+  const techs = allTechs.slice(0, 3);
   const ideaKw = ctx.query || ctx.brief.idea;
   const docItems = [];
   const docNotes = [];
+  if (allTechs.length > techs.length) {
+    docNotes.push(
+      `Only the first ${techs.length} of ${allTechs.length} candidate technologies were grounded; skipped: ${allTechs.slice(techs.length).join(", ")}. Drill them with \`construct tech --out <run> --q "<tech>"\`.`
+    );
+  }
   for (const tech of techs) {
     const q = `${tech} official documentation`;
     const { urls, via, notes } = await discover(q, ctx.webEngine, ctx.perSource);
@@ -2029,6 +2035,8 @@ function renderSRD(brief, evidence, opts) {
   files.push("SRD.json");
   if (opts.merge) {
     writeFile(out, "SRD.md", renderMergeBundle(srd), files);
+  } else {
+    rmSync2(join8(out, "SRD.md"), { force: true });
   }
   return { dir: out, files, srd };
 }
@@ -2177,7 +2185,9 @@ function checkRun(runDir) {
     for (const i of fr.interfaces) if (!interfaceNames.has(i)) errors.push(`${fr.id} references unknown interface "${i}".`);
     for (const n of fr.nfrs) if (!nfrIds.has(n)) errors.push(`${fr.id} references unknown NFR "${n}".`);
   }
-  if (srd.functional.length === 0) warnings.push("No functional requirements \u2014 the SRD has nothing to build.");
+  if (srd.functional.length === 0) {
+    errors.push("No functional requirements \u2014 an SRD must specify at least one. Capture features in the brief (featureWishlist) and re-render.");
+  }
   const noTrace = srd.functional.filter((fr) => fr.entities.length === 0 && fr.interfaces.length === 0).length;
   if (noTrace) {
     warnings.push(`${noTrace} functional requirement(s) have no data/interface traceability \u2014 fill DATA-MODEL.md / INTERFACES.md and set FR.entities/interfaces.`);

src/check.ts

@@ -170,7 +170,14 @@ export function checkRun(runDir: string): CheckResult {
     for (const i of fr.interfaces) if (!interfaceNames.has(i)) errors.push(`${fr.id} references unknown interface "${i}".`);
     for (const n of fr.nfrs) if (!nfrIds.has(n)) errors.push(`${fr.id} references unknown NFR "${n}".`);
   }
-  if (srd.functional.length === 0) warnings.push("No functional requirements — the SRD has nothing to build.");
+  // Zero FRs is a HARD failure, not a nudge: the gate certifies a *buildable*
+  // SRD, and a document with nothing to build is incomplete by definition. It
+  // also keeps the gate consistent — one FR missing acceptance criteria fails,
+  // so an SRD missing every FR must fail too (else the SKILL.md "loop until
+  // check passes" terminates on an empty scaffold).
+  if (srd.functional.length === 0) {
+    errors.push("No functional requirements — an SRD must specify at least one. Capture features in the brief (featureWishlist) and re-render.");
+  }
 
   // Advisory enrichment nudges (never fail the gate): point the author at the
   // parts a deterministic render leaves generic.

src/render.ts

@@ -72,6 +72,12 @@ export function renderSRD(brief: Brief, evidence: EvidenceItem[], opts: RenderOp
 
   if (opts.merge) {
     writeFile(out, "SRD.md", renderMergeBundle(srd), files);
+  } else {
+    // A prior `--merge` run may have left an SRD.md behind. Drop it on a
+    // non-merge re-render — same hygiene as the decisions dir above — so the
+    // tree stays the single source of truth and `check` never validates a stale
+    // bundle (e.g. an old 🧠 the current render already resolved).
+    rmSync(join(out, "SRD.md"), { force: true });
   }
 
   return { dir: out, files, srd };

src/research/tech.ts

@@ -8,12 +8,20 @@ import { stackoverflow } from "./stackoverflow.js";
 //   (b) mines StackOverflow for the known pitfalls of that technology.
 // Emits `docs` + `so` evidence the ADRs and NFRs can cite.
 export async function techAngle(ctx: ResearchContext): Promise<SourceResult[]> {
-  const techs = ctx.brief.candidateTech.slice(0, 3);
+  // Bound the run to the first few technologies; surface the cap honestly rather
+  // than silently dropping the rest of the user's candidateTech list.
+  const allTechs = ctx.brief.candidateTech;
+  const techs = allTechs.slice(0, 3);
   const ideaKw = ctx.query || ctx.brief.idea;
 
   // --- docs: official documentation of each candidate technology. ----------
   const docItems: RawItem[] = [];
   const docNotes: string[] = [];
+  if (allTechs.length > techs.length) {
+    docNotes.push(
+      `Only the first ${techs.length} of ${allTechs.length} candidate technologies were grounded; skipped: ${allTechs.slice(techs.length).join(", ")}. Drill them with \`construct tech --out <run> --q "<tech>"\`.`,
+    );
+  }
   for (const tech of techs) {
     const q = `${tech} official documentation`;
     const { urls, via, notes } = await discover(q, ctx.webEngine, ctx.perSource);

tests/check.test.ts

@@ -80,6 +80,12 @@ describe("checkRun — hard structural gate", () => {
     expect(r.ok).toBe(false);
     expect(r.structural.errors.join(" ")).toMatch(/Missing required NFR category.*usability/);
   });
+
+  it("fails when the SRD has no functional requirements (nothing to build)", () => {
+    const r = checkRun(renderRun({ briefOverride: { featureWishlist: [] } }));
+    expect(r.ok).toBe(false);
+    expect(r.structural.errors.join(" ")).toMatch(/no functional requirements/i);
+  });
 });
 
 describe("checkRun — advisory grounding (never fails the build)", () => {

tests/render.test.ts

@@ -87,6 +87,17 @@ describe("renderSRD", () => {
     expect(existsSync(stale)).toBe(false);
   });
 
+  it("drops a stale SRD.md from a prior --merge run when re-rendering without --merge", () => {
+    const out = freshDir();
+    // First render WITH merge (and an open question, so SRD.md carries a 🧠).
+    renderSRD({ ...brief, openQuestions: ["Pick a license model"] }, evidence, { level: "complex", out, merge: true, generatedAt: "T" });
+    expect(existsSync(join(out, "SRD.md"))).toBe(true);
+    // Re-render WITHOUT merge and with the decision resolved — the stale bundle
+    // must not linger for `check` to flag.
+    renderSRD(brief, evidence, { level: "light", out, merge: false, generatedAt: "T" });
+    expect(existsSync(join(out, "SRD.md"))).toBe(false);
+  });
+
   it("is byte-deterministic for the same inputs and generatedAt", () => {
     const a = freshDir();
     const b = freshDir();

tests/tech.test.ts

@@ -43,4 +43,12 @@ describe("techAngle StackOverflow", () => {
     expect(so!.items.length).toBe(3); // distinct question ids, deduped by ref
     expect(docs!.source).toBe("docs");
   });
+
+  it("notes honestly when candidateTech is capped beyond the first three", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => fail())); // no docs/SO results
+    const [docs] = await techAngle(ctx(["Next.js", "PostgreSQL", "Prisma", "Redis", "Kafka"]));
+    const notes = docs!.notes.join(" ");
+    expect(notes).toMatch(/Only the first 3 of 5 candidate technologies/);
+    expect(notes).toMatch(/Redis, Kafka/);
+  });
 });