[Feature]: Separate requirement gates from plan-stage behavior testability

[bigsmartben]

Problem Statement

The workflow currently conflates two different responsibilities:

1. Requirement-stage readiness: whether spec.md is complete, aligned, and ready to enter planning.
2. Plan-stage behavior testability: whether planned behavior has enough contracts, data, environment, assertion, and validation detail for /speckit.tasks.

checklists/behavior-testability.md currently tries to cover both. It is generated by /speckit.checklist as a pre-plan BDD, NFR, and Visual Fidelity gate, while /speckit.plan also needs planning-stage information to make behavior genuinely testable.

This causes several problems:

• The released checklist preflight expects plan.md, while the workflow preset expects the behavior-testability checklist to pass before planning, creating a circular dependency.
• Generic multi-domain requirement checklists and the fixed behavior-testability artifact have conflicting filenames, update rules, and lifecycle semantics inside the same wrapped command.
• Requirement quality checks duplicate behavior-planning concerns that cannot be resolved until contracts, fixtures, environments, and validation decisions exist.
• /speckit.clarify does not consume blocked items from all applicable domain checklists and only narrowly re-evaluates checklists/requirements.md.
• Append-only checklist updates can leave stale blockers, duplicate gate states, and readiness results that no longer match the current spec.md.
• /speckit.tasks has no single plan-stage artifact that maps accepted requirements and formal behavior contracts into task-derivation readiness.

The workflow needs two explicit stages without adding new commands.

Proposed Solution

Stage 1: Requirement alignment and planning readiness

Use the existing commands as an iterative requirement-stage workflow:

/speckit.specify
    -> /speckit.checklist
    -> /speckit.clarify
    -> re-evaluate affected requirement checklists
    -> aggregate Planning Readiness PASS

Responsibilities:

• /speckit.specify owns spec.md and the baseline specification-quality checklist.
• /speckit.checklist runs before plan.md exists, reads only spec.md plus applicable requirement evidence, and creates or updates multi-domain requirement gates such as requirements, UX, security, NFR, visual, API, or other feature-specific checklists.
• Planning Readiness is the derived aggregate state of all applicable requirement-gate checklists. It is not a separate planning-readiness.md artifact and does not require a new command.
• Requirement-gate checklists must be distinguishable from optional advisory checklists through explicit metadata such as stage: requirements, gate: planning-readiness, and status: PASS|BLOCKED.
• /speckit.clarify acts as the alignment and remediation tool. It reads unresolved or blocked items from all applicable Planning Readiness checklists, asks only product-decision questions, writes accepted answers back to spec.md, and re-evaluates the affected checklist items and gate statuses.
• Product requirement gaps return to /speckit.clarify or /speckit.specify. Provider or external-intake evidence gaps return to the owning intake workflow and must not be converted into product clarification questions.
• /speckit.plan starts only when every applicable requirement gate is current and PASS.

The core checklist preflight must therefore use paths-only resolution, require spec.md, reject missing feature specifications, and avoid requiring or reading plan.md or tasks.md.

Stage 2: Plan-stage BDD Plan and behavior testability

Keep BDD Plan as an independent internal substage of the existing /speckit.plan; do not add /speckit.readiness or /speckit.bdd-plan.

Plan preflight
    -> Phase 0 behavior projection
    -> Phase 1 formal contracts and validation decisions
    -> BDD Plan / Behavior Testability
    -> behavior/behavior-testability.md
    -> /speckit.tasks

Use the current behavior-first planning responsibilities:

• Phase 0 produces behavior/bdd.draft.feature, structured scenario drafts, UIF intent, and fixture intent from accepted requirements.
• Phase 1 formalizes contracts/bdd/, contracts/uif/, and contracts/behavior/.
• research.md records test level, fixture strategy, mock or external-system strategy, and error-branch validation decisions.
• quickstart.md records executable validation paths.
• At plan closeout, the BDD Plan substage generates specs/<feature>/behavior/behavior-testability.md.

The new plan-stage artifact maps:

• Required Case IDs from requirement-stage checklists
• formal Scenario IDs
• BDD, Expected UIF, and behavior contract references
• fixture and test-data references
• behavior assertion references
• applicable visual and user-observable NFR references
• research decisions and quickstart validation paths
• blockers that prevent deterministic task derivation

It reports Behavior Testability Status: READY|BLOCKED and serves /speckit.tasks. It must not:

• evaluate requirement prose quality
• perform provider intake or evidence extraction
• create new product requirements
• ask clarification questions
• duplicate test strategy decisions already owned by research.md
• record execution Pass/Fail results

/speckit.tasks must stop when the artifact is missing or BLOCKED. When READY, it derives fixture -> validation/test -> implementation -> evidence task chains for every Required Case. /speckit.analyze verifies traceability from requirement gates through BDD Plan outputs to tasks.

Artifact and Compatibility Policy

• Requirement readiness remains a set of domain checklist artifacts under checklists/; there is no planning-readiness.md.
• Existing requirement-readiness content in checklists/behavior-testability.md moves into the applicable domain requirement checklists.
• The new behavior/behavior-testability.md contains only plan-stage testability and task-derivation information.
• Existing checklists/behavior-testability.md files are legacy artifacts. They are not automatically deleted and must not be treated as authoritative by plan, tasks, analyze, or implementation stages.
• The next /speckit.plan run regenerates the new artifact from current planning inputs rather than copying or trusting the legacy file.
• Gate and behavior-testability updates must be recomputed or updated by stable IDs; append-only behavior must not retain stale blockers or duplicate status sections.
• Source revision or equivalent freshness checks must prevent a checklist PASS or behavior-testability READY result from surviving incompatible spec.md or planning changes.

Alternatives Considered

1. Add /speckit.readiness or /speckit.bdd-plan.

   Rejected because Planning Readiness belongs to /speckit.checklist, while BDD Plan belongs to /speckit.plan.

2. Create checklists/planning-readiness.md.

   Rejected because readiness is the aggregate state of applicable multi-domain requirement gates, not another artifact that duplicates them.

3. Keep checklists/behavior-testability.md as a pre-plan gate.

   Rejected because fixtures, environments, contracts, assertions, and executable validation paths are planning outputs.

4. Use BDD contracts alone as the task-readiness source.

   Rejected because tasks need one cross-contract view of scenarios, fixtures, assertions, validation levels, evidence paths, and blockers.

Component

Agent integrations (command files, workflows)

AI Agent

All agents

Use Cases

1. A specification author runs specify -> checklist before planning and receives requirement gates for every applicable domain.
2. A blocked checklist item flows into /speckit.clarify, the accepted decision is written to spec.md, and affected gates are re-evaluated without manually copying findings.
3. A provider-evidence blocker is routed back to intake instead of being presented as a product decision.
4. A planner projects only accepted requirements into behavior drafts and formal contracts.
5. BDD Plan produces one behavior-testability view that is complete enough for deterministic task generation.
6. /speckit.tasks creates traceable fixture, validation, implementation, and evidence work for every Required Case.
7. /speckit.analyze detects gaps across requirement gates, BDD Plan outputs, contracts, quickstart paths, and tasks.

Acceptance Criteria

• A fresh feature can run /speckit.specify followed by /speckit.checklist successfully without plan.md.
• Core checklist preflight uses paths-only resolution, requires spec.md, and does not require or read plan.md or tasks.md.
• /speckit.checklist generates or updates applicable multi-domain requirement gates and does not generate behavior-testability.md.
• Planning Readiness is derived from all applicable requirement-gate checklists; no planning-readiness.md or new command is introduced.
• /speckit.clarify consumes blocked product-decision items from applicable requirement gates, updates spec.md, and re-evaluates affected gate statuses.
• Provider or external-intake evidence blockers are routed to intake and are not converted into clarification questions.
• /speckit.plan performs no planning writes when an applicable requirement gate is missing, stale, or BLOCKED.
• After requirement gates pass, /speckit.plan completes Phase 0 projection and Phase 1 contract and validation planning before generating behavior/behavior-testability.md.
• The plan-stage artifact maps every Required Case to a formal Scenario ID or an explicit task-readiness blocker.
• The artifact references applicable BDD, UIF, behavior, fixture, assertion, research, quickstart, visual, and user-observable NFR inputs without duplicating their owned content.
• /speckit.tasks stops when Behavior Testability is missing or BLOCKED.
• When Behavior Testability is READY, /speckit.tasks covers every Required Case with fixture, validation/test, implementation, and evidence work.
• /speckit.analyze validates requirement-gate -> behavior projection -> formal contract -> behavior-testability -> task traceability.
• Legacy checklists/behavior-testability.md files are preserved but ignored as authoritative inputs and regenerated into the new location by the next plan run.
• Repeated checklist, clarify, and plan runs do not retain stale blockers or duplicate status sections.
• Bash, PowerShell, all supported agent integrations, workflow-preset contract tests, and workflow documentation cover the new ordering and responsibilities.
• Tests cover non-UI features, NFR Not Applicable, provider-evidence blockers, post-clarification spec changes, legacy-path migration, stale-source detection, and repeated runs.

Additional Context

This design separates three concepts:

• Requirement readiness: whether spec.md is aligned and ready to plan, derived from applicable domain checklists.
• Behavior testability planning: whether planned behavior is sufficiently specified for task derivation.
• Test execution: concrete implementation tasks, commands, receipts, and observed Pass/Fail evidence.

Authorship disclosure: Updated on behalf of @bigsmartben by OpenAI Codex (GPT-5, autonomous).

[bigsmartben]

Implementation is complete.

• Core requirement-gate and paths-only flow: Separate requirement gates from plan materialization #65
• Source workflow-preset implementation and compatibility releases: Separate requirement gates from plan-stage behavior testability spec-kit-workflow-preset#25 and Update repository-governance extension to v2.0.6 #28
• Bundled workflow-preset v2.0.0 integration: Update workflow-preset to v2.0.0 #72
• Core smoke/regression alignment after the v2 integration: fix: align workflow-preset v2 integration validation #75 (51368345)
• Local focused validation: 11 release/integration tests and 452 extension/integration regressions passed; fix: align workflow-preset v2 integration validation #75 also passed init-smoke, community integration validation, Ruff, ShellCheck, Markdown, CodeQL, and component-standard before merge.

The separate Ruff baseline governance remains tracked in #67.

Posted on behalf of @bigsmartben by Codex (model: GPT-5, autonomous).