spec-kitty / spec-kitty/spec-kitty
Research planning/task gates reject canonical DR/AR/QR requirements
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Problem
The canonical research mission cannot pass generic planning/task validation
after a substantive research spec is committed.
## Reproduction 1: setup-plan
Repository: current `origin/main` plus a research mission created with:
```bash
spec-kitty specify docling-graph-kitty-specs --mission-type research --topology single_branch --json
```
Populate and commit the generated canonical `research-spec-template.md`, then
run:
```bash
SPEC_KITTY_ENABLE_SAAS_SYNC=0 SPEC_KITTY_SYNC_DISABLE=1 \
spec-kitty plan --mission docling-graph-kitty-specs-01M0A0FG --json
```
Observed result:
```json
{
"result": "blocked",
"error_code": "SPEC_NOT_SUBSTANTIVE_OR_UNCOMMITTED",
"spec_committed": true,
"spec_substantive": false,
"blocked_reason": "spec.md must be committed AND substantive before setup-plan can run. Populate the Functional Requirements (at least one FR-### row with real description content), commit spec.md, then re-run setup-plan."
}
```
## Reproduction 2: finalize-tasks
After producing a research WP that traces canonical `DR-###`, `AR-###`, and
`QR-###` requirements, run:
```bash
spec-kitty agent mission finalize-tasks \
--mission docling-graph-kitty-specs-01M0A0FG --validate-only --json
```
Observed: the generic requirement-reference parser recognizes only
`FR|NFR|C`, drops the research references, and rejects WP01 for missing
requirements. A supported `migrate backfill-runtime-state` recovery can seed
runtime state, but does not repair the task-finalization contract.
## Why this is a contract mismatch
The built-in research spec template defines a research question,
sub-questions, scope, outcomes, methodology outline, `DR-###` research
requirements, `AR-###` analysis requirements, and `QR-###` quality
requirements. It does not define software-development `FR-###` rows. The
research runtime nevertheless advances through the research lifecycle and its
task surface should preserve those native references.
Therefore valid research artifacts cannot satisfy the generic setup-plan or
task-finalization gates through their own canonical mission-type schema.
## Expected
Planning and task validation should apply mission-type-specific substantive
and requirement-reference rules. For `research`, validate the required
research question/scope plus `DR/AR/QR`; do not require or silently encourage
fake `FR` rows.
## Environment
- macOS arm64
- Python 3.11
- Spec Kitty CLI 3.2.6rc2 from the current repository checkout
- Hosted sync explicitly disabled for the reproduction
## Impact
Blocks the documented research mission path, drops canonical research
traceability, and encourages agents to add fake software-development
requirements or bypass canonical commands.
Contributor guide
Research direction
Start with the `spec-kitty plan --mission ... --json` setup-plan entry point and the `spec-kitty agent mission finalize-tasks ... --validate-only --json` validation path, using the two reproductions in the issue. Read the canonical `research-spec-template.md` and trace substantive-spec and requirement-reference handling. Done means research missions validate their question/scope and preserve DR-###, AR-###, and QR-### references without requiring FR rows.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100