docs(openspec): make every spec pass validate --all --strict

[thecodedrift]

Stack (root → tip):

• feat(cli): share the platform-binary resolver, add the Vale binary spec #71
  • feat(cli): verify Vale rules from per-rule fixture directories #93
    • feat(cli): dispatch the three engines concurrently and merge their findings #94
      • feat(cli): add the engine-selection topic and archive add-vale-rule-engine #95
        • test(cli): check a project both engines have work in, and fix what it found #100
          • docs(openspec): propose the agent command and the Vale authoring path #102
            • feat: one directory per rule, and path-addressed verify/test #103
              • ➡️ docs(openspec): make every spec pass validate --all --strict #106 (you are here)

Cleanup on top of the stack so pnpm openspec validate --all --strict is green and the gate in #105 can be turned on without landing red.

Two failures, and a third problem that wasn't failing

cli-update-engine — deleted. A tombstone: capability decommissioned, every requirement removed, file kept "for historical reference". --strict needs at least one requirement. specs/ describes what's true now, and the history is already in the 2026-03-30-remove-scaffold-dependency archive, including that change's own cli-update-engine delta. Nothing outside the archives referenced it.

cli-rules — 18 errors. Scenarios and SHALL keywords added to 15 requirements. The five specifying taskless rule verify are removed: this stack deleted that command in favour of the path-addressed verify and test, now owned by cli-rule-validation. A requirement stating the subcommand is gone replaces them. Two requirements named pre-layout paths (.taskless/rule-tests/<id>.yml, and deleting "rule and test files" rather than the rule directory); both repathed while being touched.

The one worth reading. A second ## inside a requirements section ends it, so every requirement below stops being parsed:

Spec	In file	Visible before	--strict before
cli-rules	33	23	failing
infrastructure	20	1	passing
skills	7	1	passing

infrastructure and skills passed throughout, because the single requirement each still exposed was well-formed. 35 requirements were unread while the validator reported success. This is the same shape as the cli-help defect repaired earlier in the stack, where a lost code fence turned a documentation template into real headings.

The topical groupings are kept as bold lead-in lines instead of headings. Un-nesting infrastructure immediately exposed a real requirement with no SHALL, now fixed.

skills also still told agents to fetch recipes via npx @taskless/cli help <topic>.

Result

23 specs, 0 failures, with every requirement actually visible to the parser. 594 tests, lint and typecheck unchanged: this PR touches only openspec/specs/.

Note that --strict alone would not have caught the hidden-requirement class. Detecting it needs a separate check that every ### Requirement: sits under ## Requirements — noted on #105 for whoever wires the gate.

Refs #105

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

[Copilot]

Pull request overview

This PR cleans up OpenSpec capability specs so pnpm openspec validate --all --strict passes across the entire openspec/specs/ tree, removing hidden/invalid requirements and updating spec text to match the current CLI surface.

Changes:

• Remove the decommissioned cli-update-engine capability spec that no longer contains requirements.
• Fix cli-rules strict-validation failures by adding scenarios/SHALL language, removing obsolete taskless rule verify requirements, and repathing rule/test layout references.
• Prevent requirements from being accidentally hidden by nested ## headings in infrastructure and skills, and update skills to reference npx @taskless/cli agent <topic>.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
openspec/specs/skills/spec.md	Reworks section structure to avoid heading-related parser issues; updates recipe-fetch command to agent.
openspec/specs/infrastructure/spec.md	Introduces an explicit ## Requirements section and converts former nested headings into bold lead-ins to keep requirements parseable.
openspec/specs/cli-update-engine/spec.md	Deletes the spec content for a removed capability that had zero remaining requirements.
openspec/specs/cli-rules/spec.md	Adds scenarios/SHALL wording, removes obsolete rule verify requirements, updates paths, and restructures a section to avoid hidden requirements.

Suppressed comments (2)

openspec/specs/skills/spec.md:23

• The scenario title still refers to “CLI help”, but the scenario text and the requirement now reference the agent command. Renaming the scenario keeps the spec consistent and easier to search.

#### Scenario: Skill body delegates to CLI help

openspec/specs/cli-rules/spec.md:246

• This PR adds a requirement that taskless rule verify SHALL NOT exist, but a few lines below the schema requirement’s scenario still references “the rule verify command”. That makes the spec internally inconsistent; the scenario should describe schema usage without naming a removed command.

### Requirement: The rule subcommand group no longer validates rules

`taskless rule verify` SHALL NOT exist. Rule validation is addressed by path through the top-level `verify` and `test` commands, specified by the `cli-rule-validation` capability.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 3m 58s —— View job

---

Review complete

Verified structurally sound: I checked heading levels in all three edited spec files (cli-rules, infrastructure, skills) — each now has exactly one ## Requirements heading with all subsequent sections using bold lead-ins instead of ##, so the "second ## ends the requirements section" defect described in the PR body is genuinely fixed. I also confirmed the deleted cli-update-engine/spec.md has no remaining references outside openspec/changes/archive/, and that the new cli-rule-validation cross-reference in cli-rules/spec.md resolves to a real capability.

Findings posted inline — the theme across all of them is that this PR repathed/updated some requirements but left sibling text in the same file inconsistent:

1. cli-rules/spec.md:94 (highest severity) — Rules create writes test files to disk now nests test output under the new .taskless/rules/sg/<id>/.tests/ directory layout, but the sibling Rules create writes rule files to disk requirement (unchanged, ~line 85) still writes the rule file itself to the old flat .taskless/rules/<id>.yml. The Rules delete requirement this same PR repathed (line 182) expects the rule file to live inside .taskless/rules/<engine>/<id>/ — matching the real implementation in packages/cli/src/rules/files.ts — so as written, create and delete now disagree about where the rule file lives. The anonymous-flow numbered list (line 270) also still writes generated tests to the old .taskless/rule-tests/<id>.yml.
2. cli-rules/spec.md:245 — the new "taskless rule verify SHALL NOT exist" requirement is contradicted elsewhere in the same file: the "Schema imported in verify command" scenario still says the schema is needed by "the rule verify command," and "Rule improve supports anonymous local-only flow" still describes exposing "the rule verify primitive."
3. skills/spec.md:13 — text now instructs fetching recipes via npx @taskless/cli agent <topic> but in the same sentence says those files are "served by the help subcommand." agent is a separate top-level command (packages/cli/src/commands/agent.ts), not a help subcommand.
4. skills/spec.md:23 (nit, same as a Copilot-suppressed comment) — the scenario title "Skill body delegates to CLI help" wasn't renamed when its body switched to referencing agent.

None of these break validate --all --strict (they're prose-level contradictions, not missing SHALL/scenario/heading structure), so they're consistent with the PR's stated scope, but #1 in particular describes actually-contradictory behavior between rule create and rule delete that's worth fixing given the PR's goal of a fully self-consistent spec tree. #2–#4 are smaller leftover inconsistencies in files this PR is already touching.

No correctness/security/performance issues found in the mechanical parts of the diff (the heading restructuring, the cli-update-engine deletion, the SHALL/scenario additions). This is a docs-only change (openspec/specs/), so no lint/typecheck/test impact expected.
· branch: openspec/spec-strict-cleanup → openspec/self-contained-vale-rules

[claude]

Two path inconsistencies introduced/exposed by this repath:

1. The sibling requirement above ("Rules create writes rule files to disk", unchanged, ~line 85) still writes the rule file to the flat path .taskless/rules/<id>.yml, while this requirement now nests test files under .taskless/rules/sg/<id>/.tests/. Per the "Rules delete" requirement below (also repathed by this PR, line 182), the rule file itself is expected to live inside that same .taskless/rules/<engine>/<id>/ directory — and the actual implementation (packages/cli/src/rules/files.ts) agrees, writing to .taskless/rules/sg/{kebab-id}/{kebab-id}.yml. create and delete now describe two different locations for the rule file.
2. The anonymous local-only flow further down (line 270, 4. Write any generated test files to \.taskless/rule-tests/.yml`) still uses the old pre-layout path and wasn't updated to match this new .taskless/rules/sg//.tests/` convention.

[claude]

This new requirement states taskless rule verify SHALL NOT exist, but two unchanged passages elsewhere in this same file still assume it does:

• The "Generated schema is importable at build time" scenario a few lines below ("Schema imported in verify command") still reads: **WHEN** the \rule verify` command needs the ast-grep schema`.
• "Rule improve supports anonymous local-only flow" (further down) still says the flow supports the feedback loop "by exposing the rule verify primitive that the agent invokes between edits."

Since this PR is specifically about making every requirement internally consistent and strict-clean, these two leftover references to the removed rule verify command are worth fixing in the same pass (the codegen-schema scenario should probably reference verify/test from cli-rule-validation instead, matching the wording used here).

[claude]

This now says recipes are fetched via npx @taskless/cli agent <topic> but in the same sentence still claims the recipe files under packages/cli/src/help/<topic>.txt are "served by the help subcommand." Per packages/cli/src/commands/agent.ts, agent is its own top-level command (not a help subcommand) that calls getRecipe from ../prompts/recipes. Worth updating "served by the help subcommand" to reference the agent command so the requirement doesn't contradict itself.

[claude]

Minor/nit (already flagged by the Copilot review as a suppressed comment): the scenario title "Skill body delegates to CLI help" and its body ("fetch the canonical recipe via npx @taskless/cli agent <topic>") are now out of sync — the title still says "CLI help" though the command referenced is agent. Low severity since it doesn't affect validate --strict, but worth a rename while this file is already being touched.