Planned Taskless Rules

[thecodedrift]

Stack (root → tip):

• ➡️ Planned Taskless Rules #168 (you are here)
  • style: widen the house-style rules to CLAUDE.md and .conventions #176

Ten rules for our own repository, mined from the places we already state our conventions in prose: CLAUDE.md, the two .conventions styleguides, and the PostHog notes. Nothing here is settled — the point of landing it is to have somewhere concrete to argue about what we actually want enforced.

Rule	Engine	Flags	Today
docs-npx-cli	vale	pnpm dlx @taskless/cli / pnpm cli in any README	2 real violations
no-em-dashes	vale	em and en dashes	24 findings in READMEs
no-blocklist-phrases	vale	the house blocklist (reflexive agreement, performative candor, load-bearing)	clean
no-hedging	vale	"simply", "obviously", "of course", "trivially"	clean
no-index-imports	sg	relative imports ending in /index	clean
no-pii-in-telemetry	sg	email/displayName/etc. in capture(), identify(), groupIdentify()	clean
no-regex-over-build-output	sg	a test function that reads dist/ and then regexes it	clean
pr-workflow-no-branches-filter	sg	a branches: filter under a pull_request: trigger	clean
pr-workflow-ready-for-review	sg	a pull_request: types: list that omits ready_for_review	1 finding, see below
prefer-do-rpc	sg	… as DurableObjectStub<T> casts	no instances here

The two docs-npx-cli findings — README.md:37 and packages/cli/README.md:17 — are left unfixed on purpose, so the PR demonstrates a rule catching something rather than only asserting it would.

The two Vale house-style rules come from the dogfooding issue (#104 / OSS-28), scoped to **/README.md. Widening them is #169, because repo-wide they are roughly 2300 findings. Two corrections to that issue's spec, both measured and both in the rule files: no-em-dashes needs nonword: true or it silently never fires, and the proposed landed on token fires on "the plane landed on time" and was dropped.

The 24 em-dash findings in READMEs are unfixed. Rewriting them is an editorial pass on user-facing prose, so it wants a decision rather than a default: rewrite the prose, or drop the rule to warning until someone does.

The two pr-workflow-* rules come from OSS-49, which names both and records that an earlier onboarding pass stalled on whether ast-grep handles YAML. It does — Yaml is one of its 26 languages — so both build locally instead of needing a login.

pr-workflow-ready-for-review reports one finding, and it is a question rather than a defect: stack-breadcrumb.yml names types: [opened, reopened, edited, closed] with no ready_for_review. It reacts to PR metadata rather than to readiness, so omitting it may well be correct. Settling that is part of what this PR is for.

Where the rules are narrower than the conventions

Three are worth arguing about specifically, because each is a deliberate retreat from what the styleguide actually says:

• no-index-imports is not "no barrel imports." Telling from "../wizard" (a directory barrel) from from "./ask" (a file) needs filesystem resolution, which is a cross-file question and therefore runtime-tier. The rule catches only the explicit /index form, which means packages/cli/src/commands/init.ts:16 is a real violation that nothing in this PR flags.
• no-regex-over-build-output scopes to the enclosing function, not the file. Scoped to the file it fired three times on packages/cli/test/prompts.test.ts, where a helper deliberately regexes hand-written source and the same file separately loads a built artifact. That helper is correct and the styleguide says so.
• prefer-do-rpc has no instances in this repository — no octokit, no Durable Objects. Its tests are synthetic and it is carried from the shared styleguide as a pre-emptive rule. Reasonable to drop it here and keep it wherever the DO code actually lives.

Two conventions could not be expressed at all while logged out, both for the same reason — they need the cross-file graph: "a type reachable from an exported signature must itself be exported" (the declaration: true trap) and "a hand-written type must not duplicate a library type."

Where to start

The two Vale .vale.ini files. Scoping is the decision most likely to be wrong and the least visible in a diff: both rules are restricted to READMEs, both exclude **/test/fixtures/** (they were firing on CLI test inputs), and docs-npx-cli deliberately does not cover CLAUDE.md, which documents the local pnpm cli path on purpose.

docs-npx-cli also carries scope: [raw, code, text]. Without it the rule passes every fixture and catches nothing real, because every command in a README is in a code span or a fenced block.

Carried along

The rules/ engine partition, taskless.json, the embedded SKILL.md, and the no-eval move were already in the working tree from the install. Also backfilled: tests for no-eval, which had been failing verify for a missing test file, and every rule's language: is now on ast-grep's own spelling rather than lowercase.

Refs #165
Refs #166
Refs #167

[thecodedrift]

prefer-do-rpc feels like we won't need it here. The taskless services need it, but the CLI doesn't since it doesn't require cloudflre

no-pii-in-telemetry is a great usecase. Having a way to assert PII is being managed responsibly helps ensure mistakes don't get made

docs-npx-cli I'd definitely prefer this and add a note in the README that there's a "cli" script inside of package.json for running the CLI in a local environment

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.