feat: one directory per rule, and path-addressed verify/test

[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 (you are here)
              • docs(openspec): make every spec pass validate --all --strict #106

Why

A rule is spread across locations today, and for Vale one of them is shared by every rule in the project. Five sandboxed harness runs against create-vale-rule (on #102) found silent failures in that shared .vale.ini and nowhere else — an assignment above the first matcher, a glob that missed the fixture's extension, three names that had to agree with nothing reporting when they didn't.

The same reasoning generalizes past Vale: sg and runtime rules are also split between a rules/ tree and a parallel rule-tests/ tree, so no engine has a single path meaning "this rule". Fixing Vale alone would leave three layouts instead of one.

What changes

One directory per rule, identical across engines:

.taskless/rules/sg/no-eval/
    no-eval.yml
    .tests/no-eval-20260101-test.yml

.taskless/rules/vale/no-simply/
    no-simply.yml
    .vale.ini            # this rule's matchers, excludes, tskl) metadata
    .tests/pass/ok.md
    .tests/fail/bad.md

.taskless/rules/runtime/unused-exports/
    check.ts
    captures/exported-symbol.yml
    .tests/…

check assembles the Vale and ast-grep configs from the per-rule tree and gitignores them. rule verify <id> is replaced by path-addressed verify <path> (required components) and test <path> (tests), with verify running as a prerequisite layer of test.

Adds example/ — a small real project so a reader can see an install rather than infer it from tests that build their own fixtures, with a check test so it can't drift.

The dot on .tests/ is load-bearing, and measured

Probe	ast-grep 0.41.0	Vale 3.17.1
tests/ inside the rule dir	fails — missing field 'language'	fine
__tests__/	fails	fine
.tests/	skipped by rule discovery ✓	fine, even containing a .yml
test runner reads it	testDir: …/.tests works; snapshots land inside	buckets lint when targeted

ruleDirs recurses and parses every .yml beneath as a rule, so a plain tests/ directory hard-fails the scan.

This is a dependency on undocumented behavior and D2 records it as one, with two mitigations: the failure is loud — a parse error naming the file, not a test silently reinterpreted as a rule — and a test pins it. The rejected alternative (materialize a rules-only tree for ast-grep, keeping a plain tests/) is written down as the fallback if the assumption breaks.

Other measured constraints

• <id>/<id>.yml resolves as check <id>.<id> only under a StylesPath naming its parent; under StylesPath = . it resolves to nothing. This reverses the note in migration 0004 — correct for the flat layout, backwards for this one — so the task list rewrites that docstring rather than deleting it.
• Vale rejects unknown keys in a style (E201), so scope cannot ride inside the style file. ast-grep can express scoping in the rule, which is why it gets no per-rule config — an empty file per rule is symmetry as decoration.

Delivery shape

Stacked, merging down on #102. 0005 layers on 0004; both are unreleased and both ship in this stack, so consumers run them as one upgrade and never observe the intermediate layout.

openspec validate --all --strict will flag the cli-agent-authoring delta until #102 archives — that capability is introduced there.

Spec-only. Implementation follows on approval.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jwc9FFroR3mTZ4hLiSkkX3

Contains #106

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 standardizes Taskless rule authoring around a “one directory per rule” layout under .taskless/rules/<engine>/<id>/, replaces id-addressed rule verify with path-addressed verify <path> / test <path>, and introduces deterministic assembly of engine configs (Vale .vale.ini + ast-grep .sgconfig.yml) from per-rule sources. It also updates migrations/spec/docs/tests accordingly and adds a committed example/ project kept honest by tests.

Changes:

• Introduce per-rule directory layout across sg, vale, and runtime, including .tests/ and per-rule .vale.ini.
• Add path-addressed verify and test commands (with shared path resolution) and remove id-addressed rule verify.
• Add deterministic config assembly for Vale and ast-grep; update check/dispatch, migration wiring, and fixtures; add a committed example/ project plus coverage.

Reviewed changes

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

Show a summary per file

File	Description
packages/cli/test/vale-verify.test.ts	Updates Vale verification tests to the per-rule directory + .tests/ layout and new check naming.
packages/cli/test/vale-run.test.ts	Updates Vale runner tests to read the assembled config and new per-rule style locations.
packages/cli/test/vale-orchestration.test.ts	Adjusts orchestration tests to new assembled config flow and per-rule rule tree.
packages/cli/test/vale-map.test.ts	Updates mapping tests to the new Vale check id shape <id>.<id> and normalization behavior.
packages/cli/test/sgconfig.test.ts	Removes tests for legacy sgconfig generation (now replaced by assembly).
packages/cli/test/sg-committed-config.test.ts	Removes tests for committed sg config handling (replaced by assembly + new layout).
packages/cli/test/runtime-harness.test.ts	Updates runtime harness fixture writer to new runtime rule directory structure (captures/).
packages/cli/test/rule-verify-dispatch.test.ts	Removes tests for id-addressed rule verify dispatch/ambiguity behavior.
packages/cli/test/onboard.test.ts	Updates install manifest version expectations to version 5.
packages/cli/test/mixed-engine-check.test.ts	Updates integration test to author Vale rules/config per-rule and validate runtime warnings behavior.
packages/cli/test/migrate-round-trip.test.ts	Adds end-to-end behavioral migration coverage (rules still fire, tests still run, bytes stable).
packages/cli/test/migrate-install.test.ts	Updates migration/version assertions to version 5.
packages/cli/test/init-no-interactive.test.ts	Updates init scaffold manifest version assertion to version 5.
packages/cli/test/fixtures/mixed-engines-project/.taskless/vale/.vale.ini	Removes old committed shared Vale config from the fixture.
packages/cli/test/fixtures/mixed-engines-project/.taskless/taskless.json	Bumps fixture manifest version to 5.
packages/cli/test/fixtures/mixed-engines-project/.taskless/sg/sgconfig.yml	Removes old committed ast-grep config from the fixture.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/no-simply.yml	Adds Vale rule fixture in the new per-rule directory layout.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/.vale.ini	Adds per-rule Vale config fixture enabling <id>.<id>.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/no-obviously.yml	Adds a second Vale rule fixture for mixed-engine coverage.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/.vale.ini	Adds per-rule config for the second Vale rule fixture.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/sg/no-eval/no-eval.yml	Adds sg rule fixture in the new per-rule directory layout.
packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/sg/no-console-warn/no-console-warn.yml	Adds another sg rule fixture in the new directory layout.
packages/cli/test/example-project.test.ts	Adds tests ensuring the committed example/ project remains a valid, non-drifting demo.
packages/cli/test/error-envelope.test.ts	Removes rule verify error-envelope coverage and updates delete paths to new layout.
packages/cli/test/engine-layout.test.ts	Adds tests pinning the .tests/ dot-directory behavior required for ast-grep discovery.
packages/cli/test/detect.test.ts	Updates detect tests to report .taskless/rules/sg as a rule style source.
packages/cli/test/bootstrap.test.ts	Updates bootstrap/migration tests to the new rule directory layout and .tests/ placement.
packages/cli/test/assemble.test.ts	Adds direct tests for deterministic Vale/sg config assembly outputs.
packages/cli/test/anonymous-flag.test.ts	Removes rule verify --anonymous coverage (command removed).
packages/cli/src/rules/verify.ts	Updates sg verification to new path helpers and assembly-based test execution.
packages/cli/src/rules/vale/verify.ts	Updates Vale verify to use per-rule directories and new StylesPath resolution.
packages/cli/src/rules/vale/run.ts	Switches Vale runs to the assembled config path and keeps “no paths” behavior safe (.).
packages/cli/src/rules/vale/map.ts	Updates Vale check id normalization to collapse only <id>.<id> and leave foreign styles intact.
packages/cli/src/rules/scan.ts	Switches ast-grep scanning to the assembled config path.
packages/cli/src/rules/runtime/discover.ts	Updates runtime discovery to load capture rules from captures/ under each rule directory.
packages/cli/src/rules/resolve-path.ts	Adds path→(engine, ruleId) resolution for verify/test, including directory scoping rules.
packages/cli/src/rules/owner.ts	Removes id-based owner detection (no longer needed with path addressing).
packages/cli/src/rules/inspect.ts	Adds per-engine verify/test logic used by the new CLI commands.
packages/cli/src/rules/files.ts	Updates rule file/test writing and deletion to operate on per-rule directories.
packages/cli/src/rules/dispatch.ts	Updates Vale presence detection and ast-grep dispatch to use a single assembled config.
packages/cli/src/rules/assemble.ts	Adds deterministic assembly for .taskless/.vale.ini and .taskless/.sgconfig.yml.
packages/cli/src/index.ts	Registers new top-level verify and test commands.
packages/cli/src/help/verify-rule.txt	Updates recipe to the new verify/test commands and path semantics.
packages/cli/src/help/route.txt	Updates detect output example paths to the new .taskless/rules/sg location.
packages/cli/src/help/improve-rule.txt	Updates rule location references for improving existing rules in the new layout.
packages/cli/src/help/improve-rule.anonymous.txt	Updates anonymous improvement flow to use verify/test and new file paths.
packages/cli/src/help/detect.txt	Updates rule style source path examples to .taskless/rules/sg.
packages/cli/src/help/delete-rule.txt	Updates delete-rule documentation to new layout (but currently overstates engine support).
packages/cli/src/help/create-sg-rule.txt	Updates sg authoring recipe for per-rule directory layout and verify/test.
packages/cli/src/help/create-runtime-rule.txt	Updates runtime authoring docs for captures/ + new directory layout.
packages/cli/src/help/create-remote-rule.txt	Updates remote authoring docs to new per-rule directory + .tests/ layout.
packages/cli/src/help/ci.txt	Updates CI documentation paths for runtime rules under the new root.
packages/cli/src/help/check.txt	Updates check documentation to new rule locations and per-rule file naming.
packages/cli/src/filesystem/sgconfig.ts	Removes legacy sgconfig generation (superseded by assembly).
packages/cli/src/filesystem/migrations/0004-vale-engine.ts	Updates docstring notes to clarify StylesPath correctness depends on layout.
packages/cli/src/filesystem/migrate.ts	Wires in migration 0005.
packages/cli/src/detect/scan.ts	Updates rule style discovery to only use the new .taskless/rules/sg root.
packages/cli/src/commands/verify.ts	Adds the new top-level verify and test commands operating on paths.
packages/cli/src/commands/rules.ts	Removes rule verify and updates delete errors for the new layout.
packages/cli/src/commands/check.ts	Switches check to assembled config generation and new sg rule discovery.
openspec/specs/cli-rule-validation/spec.md	Adds the new capability spec for path-addressed validation/testing.
openspec/specs/cli-agent-authoring/spec.md	Updates authoring requirements to per-rule config + verify/test usage.
openspec/changes/archive/2026-08-15-self-contained-rules/tasks.md	Archives task list for the self-contained rule layout change.
openspec/changes/archive/2026-08-15-self-contained-rules/specs/cli-vale-rule-engine/spec.md	Archived delta documenting Vale engine behavior under the new layout.
openspec/changes/archive/2026-08-15-self-contained-rules/specs/cli-rule-validation/spec.md	Archived delta documenting verify/test behavior and requirements.
openspec/changes/archive/2026-08-15-self-contained-rules/specs/cli-rule-format/spec.md	Archived delta documenting the new canonical rule layout and config assembly.
openspec/changes/archive/2026-08-15-self-contained-rules/specs/cli-agent-authoring/spec.md	Archived delta updating agent authoring requirements for per-rule layout.
openspec/changes/archive/2026-08-15-self-contained-rules/proposal.md	Archives proposal for the self-contained rules change.
openspec/changes/archive/2026-08-15-self-contained-rules/.openspec.yaml	Adds archive metadata for the self-contained rules change.
openspec/changes/archive/2026-08-15-agent-command-and-vale-authoring/resume.md	Notes the stacked PR relationship and measured constraints relied on by implementation.
example/README.md	Adds human-readable demo documentation for the new layout and commands.
example/example.html	Adds example prose file intended to trigger Vale rules.
example/example.cjs	Adds example JS file intended to trigger sg rules.
example/.taskless/taskless.json	Adds version-5 manifest for the demo project.
example/.taskless/rules/vale/no-simply/no-simply.yml	Adds example Vale rule style.
example/.taskless/rules/vale/no-simply/.vale.ini	Adds example per-rule Vale config + scope.
example/.taskless/rules/vale/no-simply/.tests/pass/direct.md	Adds example passing Vale fixture.
example/.taskless/rules/vale/no-simply/.tests/fail/hedged.md	Adds example failing Vale fixture.
example/.taskless/rules/sg/no-eval/no-eval.yml	Adds example sg rule.
example/.taskless/rules/sg/no-eval/.tests/no-eval-20260814-test.yml	Adds example sg test cases under .tests/.
example/.taskless/.gitignore	Ignores assembled config artifacts inside the demo project.
eslint.config.js	Excludes example/ from linting (demo includes intentionally “bad” content).
.prettierignore	Excludes example/ from formatting (fixtures and demo content are intentionally shaped).
.changeset/vale-rule-engine.md	Updates changeset to include new layout and verify/test command changes.

Suppressed comments (1)

packages/cli/src/help/delete-rule.txt:26

• This removal list still describes deleting .taskless/rules/<engine>/<id>/, but the current rule delete implementation deletes only the ast-grep rule directory (.taskless/rules/sg/<id>/). Either the command needs an engine-aware argument or this doc should be narrowed to what is actually removed.

---

💡 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 12m 42s —— View job

---

Claude finished the review

Todo list

• Gather context and diff (origin/openspec/agent-command-and-vale-authoring...HEAD)
• Angle A: line-by-line diff scan
• Angle B: removed-behavior audit
• Angle C: cross-file tracer
• Reuse / Simplification / Efficiency / Altitude / Conventions angles
• Verify candidates
• Post inline comments + final summary

Overall assessment

This is a well-reasoned refactor — the design docs and the new test suite are unusually thorough about the failure modes they're guarding against (silent-disable, stale config, ambiguous ids). I found one high-severity correctness gap, one real performance bug, a vacuous test assertion, a doc/behavior mismatch, and a couple of smaller cleanup items. All are posted as inline comments; summary below.

Most significant — assemble.ts:122 / dispatch.ts's runValeEngine: check never verifies that assembleValeConfig produced a fresh .taskless/.vale.ini for the current run before invoking Vale — unlike the ast-grep path, which explicitly skips when assembleSgConfig returns undefined. A Vale rule directory that exists without yet (or no longer) contributing a valid .vale.ini — the exact "mid-authoring" state the now-deleted mixed-engine-check.test.ts test used to guarantee check handles quietly — will either make Vale error on a missing config file or silently reuse a stale one from an earlier run. I couldn't run the real Vale binary in this sandbox to pin down which of the two happens, but the code path and the deleted-without-replacement test both point at a real gap.

Other findings (see inline comments for detail):

• rules/inspect.ts — test <path> spawns sg test twice per ast-grep rule (verifyOneRule and testOneRule each call verifyRule, which always runs the test layer).
• test/example-project.test.ts — the "commits no assembled config" test's git ls-files pathspec is wrong (cwd is already example/), so it always returns empty and the assertion passes vacuously.
• help/delete-rule.txt — now documents rule delete as engine-generic, but deleteRuleFiles still only ever deletes the sg rule directory (pre-existing limitation, but the doc update overclaims what changed).
• filesystem/migrations/0005-rule-directories.ts — the Vale-config-splitting migration depends on a tskl) breadcrumb that no pre-this-PR code or docs ever wrote; likely moot given the PR's claim that 0004+0005 always ship together, but worth confirming that's airtight.
• rules/resolve-path.ts — a dead branch where both arms of an if return the same value.
• commands/verify.ts — verify/test process rules strictly sequentially despite each being an independent subprocess call; could run concurrently.

Branch: openspec/self-contained-vale-rules