feat(specs): context optimization + validator hardening (timestamps, sub-criteria, contract drift)#62
Merged
Conversation
…sub-criteria)
P0: spec-state hook emits full Tollgate block only on state change;
unchanged turns get a one-line reminder (~460 tok/turn saved). Fingerprint
cached in .claude/hooks/.logs/tollgate-last.txt (gitignored, fail-open).
P1b: validator fails when requirements_done/design_done/tasks_done reuse
timestamps.init — prompt-only rule moved to deterministic backstop.
P1d: validator verifies per-criterion coverage (R3.4), not just group (R3).
Progressive: enforced only when requirements.md uses explicit R{N}.{M} literals
+ numeric task mapping; legacy numbered-list specs skipped (no false failures).
…y validator Step 9.5 Finalization Audit and Pre-Finalization Checklist now separate validator-enforced checks (collapsed to one pointer line) from judgment-only checks the validator cannot see. Removes hand-restated rules the deterministic validator already hard-fails on; preserves every semantic rule verbatim (deletion policy, provider drift, decision propagation, EARS measurability, Mermaid diagrams). ~290 tokens off the always-loaded skill body, no loss of enforcement.
design.md can declare a named contract via `<!-- contract:NAME -->` + a fenced block. Every task that declares `Contracts: NAME` must copy that block verbatim. validate-spec-output.cjs fails the spec when a task's copy diverges from the canonical definition (e.g. orderId vs order_id) or names an undefined contract. Closes the BE/FE/DB contract-drift gap where each layer "inherits verbatim" by hand-copying prose and silent divergence only surfaces at integration. Opt-in: specs without contract markers are unaffected. templates/design.md documents the syntax. Verified on a synthetic BE+FE fixture (match PASS, field rename FAIL, unknown name FAIL) + regression on both real specs (no effect).
…cross-layer specs Tells the design phase to declare cross-layer data shapes as <!-- contract:NAME --> blocks so the new validator drift check actually engages on BE/FE/DB specs, instead of the syntax sitting unused in the template.
Drops Step 8 (Task Hydration) and deletes references/task-hydration.md. It created session-scoped Claude Tasks that died with the session and were re-derived from task files regardless; develop reads task files directly, so the hydration step was effectively dead weight. Pipeline renumbered: 1-7 + Validation (8) + Finalization Audit (8.5) + Completion (9). Task files + task_registry remain the single source of truth — no behavior loss.
The 34-line rules/tasks-parallel-analysis.md was ~90% a restatement of tasks-generation.md's Parallel Analysis section. Merged its 3 unique points (env/setup precondition, (P) outside checkbox brackets, skip container-only majors) into tasks-generation.md and deleted the file. Step 7 no longer loads a separate parallel-analysis rule. No behavior change; one fewer file to load.
Specs pipeline streamlined (9 steps, Task Hydration removed), lower per-turn tollgate context, leaner SKILL.md, and deterministic validator hardening (timestamps, sub-criteria coverage, cross-layer contract drift — all opt-in).
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.
Summary
Improves the
specsskill along two axes surfaced during an audit: runtime cost and quality enforcement. Every change follows one principle — move rules from LLM-must-remember (prompt) to machine-enforced (validator), and keep every new check opt-in / progressive so existing specs never false-fail.Changes
Context / speed
spec-statehook emits the full Tollgate block only when spec state (phase + done/total) changes; unchanged turns get a one-line reminder (~460 tok/turn saved). Fingerprint cached, gitignored, fail-open.SKILL.mdStep 9.5 + Pre-Finalization Checklist split into "validator-enforced" (collapsed to a pointer) vs "judgment-only". ~290 tok off the always-loaded body; all semantic rules preserved verbatim.Validator hardening (
validate-spec-output.cjs)requirements_done/design_done/tasks_donereusetimestamps.init.R3.4), not just group (R3). Opt-in: only when requirements use explicitR{N}.{M}literals + numeric task mapping.<!-- contract:NAME -->block indesign.mdmust be copied verbatim by every task declaringContracts: NAME; diverging copy or unknown name fails. Opt-in via markers;templates/design.md+SKILL.mddocument the syntax.Verification
node -cclean; src ↔ installed.claudecopies synced.Notes