PDX-483: add STEPS_REQUIRED runtime guard on testcase_generate

[mrdailey99]

Summary

• Add an active runtime guard to provar_testcase_generate that rejects the PDX-479 multi-call construction shape (steps:[] + dry_run:false + output_path) with a new STEPS_REQUIRED error code, before any side effects.
• The rejection returns details.suggestion instructing the LLM to pass the FULL step tree in a single call and notes the dry_run=true escape hatch for skeleton inspection. Other empty-steps shapes (dry-run preview, no output_path) remain allowed.
• Completes the defense-in-depth picture: PDX-481 (prompt + resource), PDX-482 (passive tool-description contract), PDX-483 (active runtime guard).

Jira

https://provartesting.atlassian.net/browse/PDX-483

Test plan

• yarn compile passes
• node_modules/.bin/nyc node_modules/.bin/mocha "test/**/*.test.ts" — 1136 passing
• node scripts/mcp-smoke.cjs — 55 / 55 PASS (new entry 6b exercises the STEPS_REQUIRED rejection at protocol surface)
• node scripts/pdx-482-validate.cjs — 28 / 28 PASS (8 new runtime-guard assertions: tools/call returns isError, error_code === STEPS_REQUIRED, retryable=false, details.suggestion non-empty + mentions FULL step tree + dry_run=true, no file on disk)
• yarn lint passes

Edge cases covered by unit tests

steps.length	dry_run	output_path	Result
0	true	absent	Allowed — skeleton inspection
0	true	present	Allowed — dry-run wins (no file written)
0	false	absent	Allowed — no persistence target
0	false	present	REJECTED with STEPS_REQUIRED, no file
≥ 1	true or false	any	Allowed — happy path

Plus an ordering test: when both STEPS_REQUIRED and PATH_NOT_ALLOWED would fire, STEPS_REQUIRED wins (the actionable root-cause error, not the misleading-fix one).

Changes

• src/mcp/tools/testCaseGenerate.ts: runtime guard at top of handler, before try { buildTestCaseXml(...) }, before any assertPathAllowed/fs.writeFileSync side effect.
• test/unit/mcp/testCaseGenerate.test.ts: new STEPS_REQUIRED runtime guard (PDX-483) block with 7 tests covering all 6 edge cases plus the ordering check. Existing writing to disk and path policy tests updated to use a non-empty steps[] so they target their original assertion (FILE_EXISTS, PATH_NOT_ALLOWED, mkdirp) rather than the new guard.
• docs/mcp.md: new STEPS_REQUIRED row in the provar_testcase_generate error codes table, plus an inline behaviour matrix showing which empty-steps shapes are allowed vs rejected and what the suggestion says.
• docs/mcp-pilot-guide.md: Scenario 12 now lists the runtime guard as the third layer of defense (prompt + description + runtime guard).
• scripts/pdx-482-validate.cjs: new runRuntimeGuardValidation() phase drives a real tools/call with the rejected shape and asserts the structured error response and zero side effects. File renamed in spirit (still pdx-482-validate.cjs) but now covers PDX-482 + PDX-483.
• scripts/mcp-smoke.cjs: new entry 6b calls the rejected shape; TOTAL_EXPECTED is dynamic so no static bump needed.

Backwards-compatibility note

The only programmatic caller of provar_testcase_generate is the MCP tool surface itself. A repo-wide search confirms no internal scripts or tests call the tool with the rejected shape outside of the test cases explicitly exercising the guard. Legitimate skeleton-inspection callers continue to work via dry_run=true (the escape hatch is documented in details.suggestion so any caller that hits the rejection learns it from the error response).

External-docs flag

docs/provar-mcp-public-docs.md and docs/university-of-provar-mcp-course.md may want to mention the runtime guard alongside their PDX-482 description-contract notes — flagging for the Provar team since those are maintained separately.

[github-actions]

Quality Orchestrator

🟢 LOW · 2 / 100 · All changed files have mapped tests.

---

🧪 Tests to Run · Running 1 of 51 tests

• unit/mcp/testCaseGenerate.test.ts

▶ Run command

npx vitest run \
  unit/mcp/testCaseGenerate.test.ts

---

_{⚡ quality-orchestrator  ·  /qo stub <file>  ·  qo analyze-local}

[Copilot]

Pull request overview

Adds an active STEPS_REQUIRED runtime guard to provar_testcase_generate so empty persisted test case generation is rejected before side effects, complementing existing prompt/tool-description defenses.

Changes:

• Rejects steps: [] + dry_run: false + output_path with structured guidance.
• Adds unit, smoke, and protocol-surface validation coverage for the guard.
• Updates MCP documentation and pilot guide with the new behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/mcp/tools/testCaseGenerate.ts	Adds the pre-write STEPS_REQUIRED guard.
test/unit/mcp/testCaseGenerate.test.ts	Covers accepted/rejected empty-step cases and preserves existing disk/path tests.
scripts/pdx-482-validate.cjs	Adds protocol-level validation for the runtime guard.
scripts/mcp-smoke.cjs	Exercises the rejected shape during authoring smoke runs.
docs/mcp.md	Documents the new error code and empty-steps behavior matrix.
docs/mcp-pilot-guide.md	Describes the new runtime guard as part of defense-in-depth.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.