feat(specs): Specs v2 — grounding + scaffold + tiers + evidence-gated review#63
Merged
Conversation
New deterministic grounding script greps the real work tree to verify every Related Files path a task cites (Modify/Delete/Read) actually exists, or is Created earlier in the same spec (intra-spec resolution). Closes the gap where validate-spec-output.cjs checks spec SHAPE but is blind to phantom file paths. Active-grep, not opt-in (field test showed opt-in checks get dodged). Wired into SKILL.md Step 8.5 as Layer 2 + the --validate deterministic gate. Supports --root for monorepo/sibling-project specs. Verified on real spec post_list_screen: 37 paths GROUNDED; injected ghost path -> FAIL; ghost path Created by another task -> GROUNDED (intra-spec).
Small specs no longer pay full-pipeline overhead. Tier is picked right after the 5-Dimension assessment and recorded in design_context.execution_tier: - Light (Clear + Isolated + <=2 tasks): skip external research, minimal discovery, Validate-only. - Standard (default): targeted research, light discovery. - Deep (Complex/critical-path/security/5+ tasks): full research + mandatory Red-Team -> Validate. Quality floor (scope_lock, EARS, Layer 1 structural + Layer 2 grounding) never skips at any tier. Auth/payment/migration/schema/privacy force Deep regardless of size. Tier only scales research/discovery/review depth, never the output contract or DoCT.
Generates spec.json + doc templates + task stubs from canonical templates so the model Edit-fills placeholders instead of hand-Writing whole files (the dominant output-token cost — a 16-task spec emitted ~935K output). Two modes: - full: new spec (spec.json + 3 docs + task stubs), refuses to overwrite. - --tasks-only: merge task stubs + task_files/task_registry into an existing spec.json without touching docs; never overwrites an already-filled task. Wired into SKILL.md Step 7 (--tasks-only) as the standard way to materialize tasks. Verified: full create, tasks-only merge, no-overwrite-of-filled-task.
review.md: add Step 5.5 Evidence Filter — red-team findings whose Location/ Evidence does not cite a concrete task/section or verbatim quote are auto- rejected before adjudication (spec-level analogue of ck-plan's file:line gate). Stops reviewers inventing flaws not actually in the artifact. SKILL.md: add Definition of a Complete Task (DoCT) — the explicit quality bar mapping each completeness element (real paths, contract, measurable acceptance, real evidence commands, reachability, requirement mapping) to the mechanism that enforces it (Layer 1 validator, Layer 2 grounding, or reviewer judgment).
…ent format Field test showed the model dodged P1d sub-criterion coverage by writing a bare numbered list (the opt-in literal format that triggers P1d). Fix the incentive at the source: requirements.md template now uses explicit `- **R1.1** ...` literal IDs (functional + NFR), and SKILL.md Step 5 mandates them for non-trivial specs. Now following the template naturally activates per-criterion coverage instead of silently disabling it. #3 contract markers kept (already routed at Step 6); both opt-in checks are now easy to activate rather than dead.
When a frontend task has a provided visual reference (design image, Figma, screenshot, palette, design tokens, style guide), the task MUST reproduce it faithfully: extract concrete values (exact hex, font, spacing, verbatim UI text) into the task, state a 'MUST: match <reference>' constraint, and prove fidelity in Evidence (visual diff/side-by-side). New components with a reference must cite its tokens; reused components inherit the design system; new components without any reference flag an open design question instead of inventing styling. Closes the gap (seen in the greenfield game spec) where FE tasks omitted the provided palette/text/spacing and the build drifted from the design. Conditional — only applies when a reference exists, so brownfield reuse is unaffected. Added to tasks-generation.md + DoCT table in SKILL.md.
Adds quantitative YAGNI tripwires (ck-plan-inspired) on top of the qualitative 5-Dimension pass: >8 files / >2 new services / >12 tasks -> challenge; >15 tasks -> split into sibling specs. Directly targets the mega-spec failure mode seen in the field test (16-task spec -> 1h38m + 8 timeouts). Tripwires are surfaced in the Scope Inquiry summary for the user to decide (Expand/Hold/Reduce/Split), not silently built. scope-inquiry.md + SKILL.md Step 3.
Specs v2: Layer-2 grounding, spec scaffolding (output-cost), execution tiers,
evidence-gated red-team, DoCT, Frontend Fidelity Rule, complexity smell check,
and literal R{N}.{M} default. All opt-in/progressive or active-grep — legacy
specs unaffected; spec structure unchanged.
Block raw Write to specs/<feature>/tasks/task-*.md so task files are generated by spec-scaffold.cjs and Edit-filled, closing the dodge where the model hand-writes task files and skips the opt-in scaffold step. Scope is narrow (only the Write tool on a task-file path); Edit/MultiEdit, other Writes, and the scaffold script are untouched. Three safety valves: fail-open when the scaffold script is absent, an actionable block message with the exact command, and a runtime.json escape hatch.
A task that still carries an unfilled {{...}} placeholder now hard-fails
the deterministic validator (a leftover .../ path warns) — the fill-side
complement to the scaffold-guard hook, closing the 'stub created but not
filled' gap.
Also realign two self-tests that lagged the Specs-v2 SKILL.md wording
(validate guardrail; init-is-never-a-stop-point) and drop the misleading
'scaffold cuts output tokens' claim from Step 7.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mục tiêu
Nâng
hapo:specsđể spec/plan ra đủ thông tin + đúng thực tế để implement không lạc — lấy cơ chế ck-plan, giữ cấu trúc cafekit. Dựa trên field-test v0.13.0 (specpost_list_screen: 1h38m, 935K output, validator mù 42 path, P1d/#3 bị né).3 lớp đảm bảo chất lượng (v2 vượt cả 2 hệ gốc)
Thay đổi (6 commit)
spec-ground.cjs): grep work tree verify mọiRelated Filespath (Modify/Delete/Read) tồn tại thật, hoặc được Create bởi task khác trong spec. Active-grep (không opt-in). Wired Step 8.5 +--validategate.--rootcho monorepo.spec-scaffold.cjs): tạo skeleton spec.json + task stubs để model Edit-fill thay vì Write tay (cắt output token).--tasks-onlymerge vào spec sẵn có, không ghi đè task đã fill.R{N}.{M}thành format mặc định của requirements template (P1d trước đây bị model né bằng numbered-list).Verify (mọi bước test thật)
--tasks-onlymerge + không ghi đè task đã fill.post_list_screen.node -csạch.Lỗ v0.13.0 → v2 sửa
Ghi chú
.claude/scripts/(mô hình cafekit), KHÔNG cần global binary.🤖 Generated with Claude Code