fix(cli): correct verify-schema docstrings to the current command form

[thecodedrift]

Stack (root → tip):

• ➡️ fix(cli): correct verify-schema docstrings to the current command form #318 (you are here)
  • fix(cli): route file-set/tests guard in rule create+improve through fail() #319
    • test(cli): stop asserting the winner of a 1ms race in the Vale timeout test #320
      • fix(cli): skip an oversized file instead of letting Vale time out on it #323

Summary

packages/cli/src/schemas/index.ts published verifyOutputSchema and valeVerifyOutputSchema under docstrings naming taskless rule verify <id> --json. That command form does not exist: taskless rule has four subcommands (create/improve/meta/delete), and verify is a top-level, path-addressed command — deliberately so, since an id can name a rule under two engines and a path cannot (resolve-path.ts:25).

Digging past the surface-level fix, the real history is stranger than "wrong command name": rule verify <id> was removed entirely in c4dc03d (Aug 13) when rule addressing moved from id to path. @taskless/cli/schemas (the entry these docstrings live in) was created a month later, in 189afa5 (Sep 4), specifically to publish the real verify --json envelope for the Cloud eval team (issue #263). That commit re-exported verifyOutputSchema/valeVerifyOutputSchema from rules-verify.ts alongside the correct verifyTestOutputSchema, without checking whether the command they described was still current. It wasn't.

So the docstrings weren't just misnamed — the shape they describe is not emitted by any current CLI command. taskless verify --json / taskless test --json print verifyTestOutputSchema's flattened { ok, rules: [{ errors, violations, ... }] } envelope. verifyOutputSchema / valeVerifyOutputSchema describe the pre-flattening per-layer detail (schema/requirements/tests for ast-grep; fixtures/missingFailures/unexpectedFindings for Vale) that verifyRule() / verifyValeRule() compute internally, and that the removed rule verify <id> command used to print verbatim as { engine: "sg", ...verifyRule(...) } (confirmed by reading that command's source before its removal).

Docstrings on both exports (and the module-adjacent comment block in rules-verify.ts) are corrected to say this accurately, rather than naming a command form — old or new — that doesn't correspond to real output. Also fixed a second stale reference: ast-grep-rule.ts credited the embedded JSON Schema to rule verify --schema, a flag removed CLI-wide back in May.

Two open questions from the issue, investigated and answered

1. Are getSchemaPayload/schemaOutputSchema orphaned?

• schemaOutputSchema (in schemas/rules-verify.ts, not published): confirmed genuinely unused. Nothing in src or test imports it, and the package's exports map in package.json restricts subpath resolution to declared entries only (., ./prompts, ./layout, ./schemas, ./node/runtimes, ./reference.json), so no external consumer can reach it either. I'm leaving it in place rather than removing it in this PR — it's adjacent cleanup, not what the issue asks for, and I'd rather flag it than fold in an unrelated deletion.
• getSchemaPayload (in src/rules/verify.ts, outside this PR's file scope — owned by another agent's PR territory): the --schema CLI flag that once called it was removed in May (commit 7813546), whose message says it was kept "since the recipe will reuse the payload content." I checked: nothing in src/help or src/prompts references astGrepSchema/tasklessRequirements, so that reuse hasn't happened four months later. However it's still directly imported and exercised by test/verify.test.ts, which is outside my assigned files. I did not establish it's safe to remove, so per the guardrail in .conventions/STYLEGUIDE-CODE.md I'm leaving it and flagging it here instead.

2. Is the rule create/improve vs verify/test publication asymmetry deliberate?
Not deliberate in the sense of a documented policy — it tracked one consumer's specific ask. 189afa5's own commit message says the entry exists because "the Cloud eval team is doing exactly that today against the verify envelope" (#263). Nothing in that commit or since asked to publish create/improve's shapes. I'm not expanding this PR to publish new export paths — that's a surface change with its own tradeoffs (what's the compatibility commitment, does notices stay optional forever, etc.) and deserves its own proposal, not a rider on a docstring fix.

Tests

test/schemas-export.test.ts only name-checked the export list and exercised verifyTestOutputSchema against real CLI output — nothing exercised verifyOutputSchema/valeVerifyOutputSchema, which is exactly why the command-form mismatch went unnoticed for a month.

Given the finding above (no command emits this shape any more), I can't pin it the way verifyTestOutputSchema is pinned — spawning the built CLI and parsing stdout. The closest real pin: reconstruct the exact envelope the removed command built ({ engine: "sg", ...verifyRule(...) }, and the passed → success mapping for Vale) from the real return values of verifyRule() / verifyValeRule() (imported directly from source, since they're intentionally not part of the public surface — see the module docstring's "What this is NOT" section), and parse it with the built schema. This fails if either function's return shape ever drifts from what's published, which is the property that matters.

Mutation-checked both new assertions:

• Renamed verifyOutputSchema's ruleId field to id → the new sg test failed with a real Zod error (invalid_type at path ["id"]). Reverted → passes again.
• Reverted valeVerifyOutputSchema's success mapping back to the internal passed field name → the new vale test failed (invalid_type at path ["success"]). Reverted → passes again.

Full suite: pnpm typecheck (clean), pnpm test (85 files / 1372 tests, all pass, including the vale-gated test since a vale binary is present in this environment), pnpm lint (clean, including the taskless check house-style pass over the rebuilt CLI: "No issues found").

Changeset

patch. No runtime behavior changes — the schemas themselves are byte-identical, only docstrings and one internal comment changed, plus tests. It's a patch rather than no-release-note because these docstrings ship inside @taskless/cli/schemas, the artifact this repo's own convention says a consumer reads via editor tooltips or generated docs; a consumer following the old docstring would be pointed at a command that doesn't exist.

Scope note

I stayed within my assigned files (packages/cli/src/schemas/ and packages/cli/test/schemas-export.test.ts) and did not touch packages/cli/src/commands/rules.ts, test/error-envelope.test.ts, or test/verify-test-commands.test.ts, which other agents own.

Fixes #283

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 2m 45s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contains no reviewThreads, no reviews, and only the triggering @claude /review comment — this is the first review of this PR, so everything below is new.

• Read prior review data and PR context
• Fetch full diff (gh pr diff) and read changed files
• Review docstring/comment accuracy against actual code behavior
• Review new test coverage in schemas-export.test.ts
• Post final review

---

The core fix is accurate: I independently confirmed taskless rule has no verify subcommand today (commands/verify.ts has no --schema flag either), getSchemaPayload/schemaOutputSchema are reachable only from test/verify.test.ts and their own definitions (no command wiring), and the new tests' passed: 1, failed: 0 assertion matches the existing pattern for the identical one-valid/one-invalid fixture in test/verify.test.ts:126. The valeVerifyOutputSchema test's constructed envelope also matches verifyValeRule's real return shape field-for-field.

Two findings, both about the PR's own stated goal — eliminating stale references to the removed rule verify/--schema command forms — where a same-class reference was left behind:

1. packages/cli/src/rules/verify-examples.ts:2 — [New]

/**
 * Curated annotated examples for `rule verify --schema` output.
 * These teach agents how to write valid ast-grep rules.
 */
export const RULE_EXAMPLES = [

This is the exact stale command form (rule verify --schema) the PR fixes in ast-grep-rule.ts's docstring — and RULE_EXAMPLES is precisely what that docstring now points to (getSchemaPayload()'s examples field, itself built from RULE_EXAMPLES). The PR's scope note excludes commands/rules.ts and two test files as "owned by other agents," but doesn't mention this file, and it isn't obviously in another agent's territory. Worth a follow-up so the "second stale reference" fix is actually complete.

2. packages/cli/src/schemas/rules-verify.ts:3 — [New]

// --- Schema mode output (--schema --json) ---

Same file this PR already touches — two sections below, the PR correctly rewrote // --- Verify mode output (rule verify <id> --json) --- into // --- Verify layer detail --- for exactly this reason. This header, for schemaOutputSchema, still names the same removed --schema flag and was left as-is. Low severity since schemaOutputSchema is confirmed dead/unpublished (per the PR body), but it's an inconsistency in a file being edited for precisely this class of staleness.

Nothing else stood out: the docstring rewrites in schemas/index.ts and rules-verify.ts accurately describe current behavior (verified against verifyRule()/verifyValeRule()'s real return shapes in src/rules/verify.ts and src/rules/vale/verify.ts), the changeset correctly uses patch per this repo's pre-1.0 convention, and the new tests' mutation-testing claims in the PR body are consistent with what the assertions actually check.