306 lines
13 KiB
Markdown
306 lines
13 KiB
Markdown
---
|
|
description: Read-only pre-implementation validation gate. Runs after tasks and analyze: scans for unresolved markers, validates all artifacts, checks Axiom health, and produces a PASS/BLOCKED report at specs/<feature>/validation.md. No implementation if blocking findings.
|
|
handoffs:
|
|
- label: Implement Project
|
|
agent: speckit.implement
|
|
prompt: Start implementation now that validation has PASSED
|
|
send: true
|
|
---
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
## Required Skills
|
|
|
|
MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`.
|
|
|
|
## Operating Constraints
|
|
|
|
**STRICTLY READ-ONLY**: This command MUST NOT modify any feature artifact EXCEPT `specs/<feature>/validation.md`. It reads everything, validates everything, and reports — but does not implement, fix, or rewrite. The ONLY write is the validation report itself.
|
|
|
|
**Gate Behavior**: If any blocking finding is discovered, the report MUST say `BLOCKED` and `/speckit.implement` MUST refuse to proceed until the finding is resolved.
|
|
|
|
## Outline
|
|
|
|
### Phase 0: Pre-Flight
|
|
|
|
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root. Parse `FEATURE_DIR`, `FEATURE_SPEC`, `IMPL_PLAN`, `TASKS`.
|
|
2. **Verify all prerequisite artifacts exist**:
|
|
- `FEATURE_DIR/spec.md`
|
|
- `FEATURE_DIR/plan.md`
|
|
- `FEATURE_DIR/tasks.md`
|
|
- `FEATURE_DIR/contracts/modules.md` (when plan references contracts)
|
|
- `FEATURE_DIR/data-model.md` (when plan references data model)
|
|
- `FEATURE_DIR/research.md` (when plan references research)
|
|
3. **Capture input provenance before validation**: For every artifact in the validation scope, record its repository-relative path, byte size, modification timestamp, and SHA-256 digest. At minimum include `spec.md`, `plan.md`, `tasks.md`, `traceability.md`, `contracts/modules.md`, `contracts/openapi.yaml`, `ux_reference.md`, `contracts/ux/**`, and `prototype/manifest.md` when present. These values define the exact snapshot covered by the verdict.
|
|
4. **Load context** (progressive disclosure — only load sections needed for each check):
|
|
- All feature artifacts
|
|
- `.specify/memory/constitution.md`
|
|
- `docs/adr/*.md` — all ADRs (for decision-memory checks)
|
|
- `.opencode/skills/semantics-core/SKILL.md` — §VIII Attention Architecture
|
|
- `backend/src/` and `frontend/src/` — current codebase state (for path validation)
|
|
|
|
### Phase 1: Unresolved Marker Scan
|
|
|
|
Scan ALL feature artifacts for any of the following blocking markers:
|
|
|
|
| Marker | Pattern | Severity | Action |
|
|
|--------|---------|:--------:|--------|
|
|
| `[NEEDS CLARIFICATION]` | spec.md | **BLOCKING** | Must be resolved in `/speckit.clarify` before implementation |
|
|
| `[NEED_CONTEXT: *]` | contracts/modules.md | **BLOCKING** | Blind dependency — must be resolved before contracts are implementable |
|
|
| `TODO` (in spec/plan) | spec.md, plan.md | **WARNING** | Review — may indicate incomplete design |
|
|
| `TKTK` | any artifact | **BLOCKING** | Placeholder — must be filled |
|
|
| `???` | any artifact | **WARNING** | Ambiguity — review |
|
|
| `<placeholder>` / `TBD` / `TBC` | any artifact | **WARNING** | Review |
|
|
| `[NEEDS CLARIFICATION: ...]` | any artifact | **BLOCKING** | Unresolved from spec |
|
|
|
|
Report: count of each marker type, file locations, severity.
|
|
|
|
### Phase 2: Artifact Completeness
|
|
|
|
Verify every expected artifact is present and non-empty:
|
|
|
|
| Artifact | Required? | Check |
|
|
|----------|:---------:|-------|
|
|
| `spec.md` | ALWAYS | Has `## User Scenarios`, `## Requirements`, `## Success Criteria` |
|
|
| `ux_reference.md` | ALWAYS | Has personae, narrative, error experience |
|
|
| `plan.md` | ALWAYS | Has `## Summary`, `## Technical Context`, `## Constitution Check`, `## Project Structure` |
|
|
| `tasks.md` | ALWAYS | Has phases, task IDs, file paths |
|
|
| `contracts/modules.md` | When plan references contracts | Has `#region` contracts, `@RELATION` edges |
|
|
| `data-model.md` | When plan references data model | Has entity definitions, schemas |
|
|
| `research.md` | When plan references research | Has decisions, rationale, alternatives |
|
|
| `traceability.md` | When plan declares RTM | Has Story → Model → API → Task → Test matrix |
|
|
| `quickstart.md` | When plan references quickstart | Has verification commands |
|
|
| `contracts/ux/` | When UI surface | Has UX contracts from `/speckit.ux` |
|
|
| `prototype/index.html` | When `/speckit.prototype` was run | Has interactive prototype |
|
|
| `contracts/openapi.yaml` | When `/speckit.openapi` was run | Has valid OpenAPI 3.1 spec |
|
|
| `fixtures/manifest.md` | When plan generated fixtures | Has fixture index |
|
|
|
|
### Phase 3: Schema & Contract Validation
|
|
|
|
1. **OpenAPI validation** (if `contracts/openapi.yaml` exists):
|
|
- YAML parseability (Python `yaml.safe_load`)
|
|
- `operationId` uniqueness
|
|
- `$ref` target existence
|
|
- Required keys: `openapi`, `info`, `paths`, `components`
|
|
- Example coverage for all response classes
|
|
|
|
2. **Contract validation** (via Axiom MCP):
|
|
- Run `axiom_search({operation="status"})` — confirm index is FRESH
|
|
- Run `axiom_audit({operation="audit_contracts"})` — check for invalid tiers, missing metadata, unresolved relations
|
|
- Run `axiom_search({operation="workspace_health"})` — check for orphan/unresolved metrics
|
|
- If Axiom MCP is unavailable, fall back to manual `grep` checks:
|
|
```bash
|
|
# Find all #region contracts in plan's contract files
|
|
grep -rn "#region" specs/<feature>/contracts/
|
|
# Check every #region has a matching #endregion
|
|
```
|
|
|
|
3. **ATTN rules compliance** (for `contracts/modules.md`):
|
|
- ATTN_1: Every `#region` anchor packs `[C:N] [TYPE] [SEMANTICS]` on ONE line
|
|
- ATTN_2: Contract IDs are hierarchical (`Domain.Sub.Name`), not flat
|
|
- ATTN_3: Same-domain contracts share primary `@SEMANTICS` keyword
|
|
- ATTN_4: No contract exceeds 150 lines, no module exceeds 400 lines
|
|
|
|
### Phase 4: Reference & ADR Integrity
|
|
|
|
1. **ADR continuity check**:
|
|
- Every `@REJECTED` path in any ADR → verify NO task in `tasks.md` schedules that path
|
|
- Every architectural decision in `plan.md` → verify it aligns with the governing ADR (or carries `<ESCALATION>`)
|
|
- Every `@RATIONALE` in `contracts/modules.md` → verify it is consistent with upstream ADR rationale
|
|
|
|
2. **Cross-reference integrity**:
|
|
- Every file path in `tasks.md` → verify parent directory exists in `backend/src/` or `frontend/src/`
|
|
- Every `@RELATION -> [TargetId]` in contracts → verify TargetId exists in `contracts/modules.md` or is a known existing contract
|
|
- Every `$ref` in `openapi.yaml` → verify target exists in the same file
|
|
- Every `operationId` in `openapi.yaml` → verify it appears in `traceability.md` (if RTM exists)
|
|
|
|
### Phase 5: Decision-Memory Continuity
|
|
|
|
Verify the three-layer chain is intact:
|
|
|
|
```
|
|
Global ADR → plan/research → contracts → preventive tasks → tests
|
|
```
|
|
|
|
For each `@REJECTED` path at any layer:
|
|
1. **ADR layer**: `@REJECTED` exists `→` downstream layer must NOT schedule it
|
|
2. **Plan layer**: `@RATIONALE` justification exists `→` contracts must propagate it
|
|
3. **Contract layer**: `@REJECTED` guardrail exists `→` at least one task must verify the rejection holds
|
|
4. **Task layer**: `@RATIONALE` / `@REJECTED` inline `→` must trace to a contract or ADR
|
|
|
|
**Findings**:
|
|
- Dangling rationale (downstream missing): **WARNING**
|
|
- Contradictory resurrection (rejected path scheduled): **BLOCKING**
|
|
- Missing guardrail (ADR rejection, no task verification): **WARNING**
|
|
- Unjustified workaround (local `@RATIONALE` without upstream source): **WARNING**
|
|
|
|
### Phase 6: Task Dependency & Path Validation
|
|
|
|
1. **Task dependency graph**:
|
|
- Phase 1 (Setup) tasks exist before Phase 2 (Foundational)
|
|
- Foundational tasks marked before any User Story phase
|
|
- No cross-story dependency that blocks independent verification
|
|
- Circular dependency check: if T001 depends on T002 and T002 depends on T001 → **BLOCKING**
|
|
|
|
2. **Path validation**:
|
|
- Every task with a file path → path starts with `backend/src/`, `frontend/src/`, `specs/`, `docs/`, or `backend/tests/`, `frontend/src/lib/**/__tests__/`
|
|
- No task path references `.kilo/`, `.ai/`, `.kilocode/`
|
|
- No task path references Rust/MCP (`.rs`, `cargo`, `src/server/`)
|
|
- Every task file path is syntactically valid (no unmatched braces, no absolute `/` paths outside repo)
|
|
|
|
### Phase 7: UX State Coverage
|
|
|
|
If the feature has a UI surface (UX contracts or `ux_reference.md` exists):
|
|
|
|
1. **State matrix coverage**: Verify every state class from the edge/failure matrix (speckit.ux.md Phase 2) is accounted for:
|
|
- Each screen's UX contract declares the applicable states
|
|
- No state class was skipped without explicit rationale
|
|
- Every error state has a `@UX_RECOVERY` path
|
|
|
|
2. **Prototype coverage** (if `prototype/index.html` exists):
|
|
- Every `@UX_STATE` in contracts → represented in prototype state switcher
|
|
- Every `@UX_RECOVERY` path → traversable in prototype
|
|
|
|
3. **UX test coverage**:
|
|
- Every `@UX_STATE` declared → at least one `@UX_TEST` scenario
|
|
- Every error state → at least one `@UX_TEST` scenario with recovery path
|
|
- Test ownership (L1/L2) assigned from matrix
|
|
|
|
### Phase 8: Axiom Health Check
|
|
|
|
Run Axiom MCP diagnostics:
|
|
|
|
1. `axiom_search({operation="status"})` — index health: FRESH / STALE / ERROR
|
|
2. `axiom_search({operation="workspace_health"})` — orphan count, unresolved relations, complexity distribution
|
|
3. `axiom_audit({operation="audit_belief_protocol"})` — C4/C5 contracts missing `@RATIONALE`/`@REJECTED`
|
|
|
|
**Interpretation**:
|
|
- Index STALE: **WARNING** — recent changes may not be indexed
|
|
- High orphan count (>10%): **WARNING** — structural drift
|
|
- Unresolved relations: **BLOCKING** if the unresolved target is in this feature's scope
|
|
- Missing belief protocol tags: **WARNING** — will block C4/C5 implementation
|
|
|
|
### Phase 9: Produce Validation Report
|
|
|
|
Write `specs/<feature>/validation.md`:
|
|
|
|
```markdown
|
|
#region Std.Opencode.ValidationReport [C:3] [TYPE ADR] [SEMANTICS validation,gate,[DOMAIN]]
|
|
@defgroup Validation Pre-implementation validation gate for [FEATURE].
|
|
|
|
## Status: [PASS / BLOCKED]
|
|
|
|
**Date**: [DATE]
|
|
**Feature**: [feature name]
|
|
**Branch**: [branch]
|
|
|
|
## Validated Inputs
|
|
|
|
| Artifact | Size (bytes) | Modified (UTC) | SHA-256 |
|
|
|----------|-------------:|----------------|---------|
|
|
| spec.md | [size] | [timestamp] | `[digest]` |
|
|
| plan.md | [size] | [timestamp] | `[digest]` |
|
|
| tasks.md | [size] | [timestamp] | `[digest]` |
|
|
| ... applicable artifacts ... | | | |
|
|
|
|
The verdict is stale and MUST NOT authorize implementation when any listed artifact is missing or its current digest differs. New applicable artifacts created after this report also make the verdict stale.
|
|
|
|
## Blocking Findings
|
|
|
|
> If BLOCKED, these MUST be resolved before `/speckit.implement`.
|
|
|
|
| ID | Check | Severity | Location | Finding |
|
|
|----|-------|:--------:|----------|---------|
|
|
| B01 | Unresolved Marker | BLOCKING | spec.md:L42 | [NEEDS CLARIFICATION: auth mechanism] |
|
|
| B02 | ADR Resurrection | BLOCKING | tasks.md:T017 | Task schedules `@REJECTED` path from ADR-0007 |
|
|
|
|
*If no blocking findings:* "✅ No blocking findings. Proceed to `/speckit.implement`."
|
|
|
|
## Warning Findings
|
|
|
|
| ID | Check | Severity | Location | Finding |
|
|
|----|-------|:--------:|----------|---------|
|
|
| W01 | Missing Guardrail | WARNING | contracts/modules.md:Api.Export | ADR-0004 @REJECTED path has no verification task |
|
|
| W02 | Dangling Rationale | WARNING | plan.md:§Decisions | @RATIONALE exists but no contract propagates it |
|
|
|
|
## Check Results
|
|
|
|
### Phase 1: Unresolved Markers
|
|
- [NEEDS CLARIFICATION]: N
|
|
- [NEED_CONTEXT]: N
|
|
- TODO/TKTK/???: N
|
|
- **Status**: ✅ PASS / ❌ BLOCKED
|
|
|
|
### Phase 2: Artifact Completeness
|
|
| Artifact | Expected | Present | Status |
|
|
|----------|:--------:|:-------:|:------:|
|
|
| spec.md | required | ✅ | PASS |
|
|
| plan.md | required | ✅ | PASS |
|
|
| tasks.md | required | ✅ | PASS |
|
|
| traceability.md | required | ✅ | PASS |
|
|
| ... | | | |
|
|
|
|
### Phase 3: Schema & Contract Validation
|
|
- YAML parse: ✅ / ❌
|
|
- operationId uniqueness: ✅ / ❌
|
|
- Contract audit: N warnings, N errors
|
|
- ATTN rules: N/N contracts pass
|
|
|
|
### Phase 4: Reference & ADR Integrity
|
|
- ADR continuity: N ADRs checked, N issues
|
|
- Cross-reference integrity: N $refs/resolved, N broken
|
|
|
|
### Phase 5: Decision-Memory Continuity
|
|
- Three-layer chain: N chains checked
|
|
- Dangling rationale: N
|
|
- Contradictory resurrection: N
|
|
- Missing guardrail: N
|
|
|
|
### Phase 6: Task Dependency & Path
|
|
- Task count: N
|
|
- Invalid paths: N
|
|
- Circular dependencies: N
|
|
|
|
### Phase 7: UX State Coverage
|
|
- State matrix coverage: N/N state classes evaluated
|
|
- Prototype coverage: N/N @UX_STATEs represented
|
|
- UX test coverage: N/N states have tests
|
|
|
|
### Phase 8: Axiom Health
|
|
- Index status: FRESH / STALE
|
|
- Orphans: N
|
|
- Unresolved relations: N
|
|
|
|
## Gate Decision
|
|
|
|
**Verdict**: ✅ PASS — `/speckit.implement` may proceed.
|
|
OR
|
|
**Verdict**: ❌ BLOCKED — resolve N blocking findings before implementation.
|
|
|
|
## Resolution Instructions
|
|
|
|
If BLOCKED:
|
|
- B01: Run `/speckit.clarify` to resolve [NEEDS CLARIFICATION] markers.
|
|
- B02: Remove or re-scope T017 to avoid the rejected path, or file `<ESCALATION>` to ADR-0007.
|
|
- ...
|
|
|
|
#endregion Std.Opencode.ValidationReport
|
|
```
|
|
|
|
### Phase 10: Report
|
|
|
|
Report:
|
|
- Validation report path: `specs/<feature>/validation.md`
|
|
- Status: PASS or BLOCKED
|
|
- Blocking findings: N
|
|
- Warning findings: N
|
|
- Checks executed: 8 phases, N individual checks
|
|
- If PASS: "Ready for `/speckit.implement`"
|
|
- If BLOCKED: "Resolve N blocking findings, re-run `/speckit.validate`"
|