test(cli): derive the guard's inputs instead of restating them

Review feedback on the cross-reference guard, three findings, one root
cause each:

- The subcommand alternation was a hand-copied duplicate of the registry
  in src/index.ts. A command added there and forgotten here would drop
  out of the guard silently. Moved the names to src/commands/names.ts and
  had index.ts check its record against them with `satisfies`, so the
  drift is a type error.
- The citation checks anchored on a fixed `taskless|@taskless/cli`
  spelling, which matches nothing a dev/self build renders — under those
  targets every check found zero citations and passed without measuring
  anything. The anchor now derives from `buildInvocation()`, and the
  dangling-citation check fails when it finds no citation at all.
- openspec/specs/cli-agent claimed SKILL.md and tskl.md express the CLI
  as `%(TASKLESS_CLI)s`. They do not, by design: they carry the canonical
  `npx @taskless/cli` that `applyCliInvocation` rewrites. Reworded the
  requirement to describe both mechanisms, and scoped the automated-check
  sentence to recipe sources, which is all it covers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cyga14bww8rmazH2XrF8ms

Author: theCodeDrift

openspec/specs/cli-agent/spec.md

@@ -269,11 +269,14 @@ No embedded recipe SHALL contain the string `taskless help`. Recipes cross-refer
 
 ### Requirement: Recipes name the CLI by its full invocation
 
-Every instruction in shipped agent-facing content that tells a reader to run the Taskless CLI SHALL express the CLI as `%(TASKLESS_CLI)s`, followed by the subcommand and its arguments. This applies to the recipe sources under `packages/cli/src/agent/`, to `skills/taskless/SKILL.md`, and to `commands/tskl/tskl.md`.
+Every instruction in shipped agent-facing content that tells a reader to run the Taskless CLI SHALL name the CLI by the invocation the build resolves for the reader, followed by the subcommand and its arguments — never by a hand-written one. Two mechanisms deliver that, because the content travels by two different paths:
 
-Content SHALL NOT name the CLI as a bare `taskless` binary, because it is not installed on `PATH` for the overwhelming majority of readers, and SHALL NOT hardcode a launcher-and-package string such as `npx @taskless/cli`, because that is the fact `%(TASKLESS_CLI)s` exists to hold in one place. Prose that mentions the product, a config filename, or a directory (`taskless.config`, `.taskless/`) is unaffected — the requirement is about executable instructions.
+- Recipe sources under `packages/cli/src/agent/` SHALL express the CLI as `%(TASKLESS_CLI)s`, which the recipe renderer substitutes at render time.
+- `skills/taskless/SKILL.md` and `commands/tskl/tskl.md` are not rendered through the recipe renderer, so they SHALL carry the canonical `npx @taskless/cli` string, which `applyCliInvocation` rewrites to the build target's invocation when the content is emitted.
 
-An automated check SHALL fail when a bare `` `taskless <subcommand>` `` invocation appears in a recipe source, so the normalization cannot silently regress as recipes are edited.
+Content SHALL NOT name the CLI as a bare `taskless` binary, because it is not installed on `PATH` for the overwhelming majority of readers. A recipe source SHALL NOT hardcode a launcher-and-package string such as `npx @taskless/cli` either, because that is the fact `%(TASKLESS_CLI)s` exists to hold in one place — the string is canonical only in the two files above, where it is the rewrite anchor rather than a hardcoding. Prose that mentions the product, a config filename, or a directory (`taskless.config`, `.taskless/`) is unaffected — the requirement is about executable instructions.
+
+An automated check SHALL fail when a bare `` `taskless <subcommand>` `` invocation, or a hardcoded `npx @taskless/cli`, appears in a recipe source, so the normalization cannot silently regress as recipes are edited. The check SHALL read the subcommand names from the CLI's own registry rather than restating them, so a newly added subcommand is covered without a second edit. It does not extend to `skills/taskless/SKILL.md` or `commands/tskl/tskl.md`, whose rewrite anchor is the very string it flags and which quote invocations as example user utterances.
 
 #### Scenario: A recipe instructs the reader to run a subcommand
 
@@ -294,3 +297,5 @@ An automated check SHALL fail when a bare `` `taskless <subcommand>` `` invocati
 
 - **WHEN** the check that recipe cross-references cite only topics that resolve is run
 - **THEN** it SHALL operate on rendered recipe text, where the invocation is a stable literal, rather than on source text where it is a placeholder
+- **AND** it SHALL anchor on the invocation the running build actually renders, so the check does not pass vacuously under a `nightly`, `dev`, or `self` build whose rendered invocation names neither `taskless` nor `@taskless/cli`
+- **AND** it SHALL fail when it finds no cross-reference at all, since an empty result is otherwise indistinguishable from every reference resolving

packages/cli/src/commands/names.ts

@@ -0,0 +1,26 @@
+/**
+ * Every top-level subcommand the CLI dispatches, as a reader would type it.
+ *
+ * This is the single source of truth for the *names*. `src/index.ts` builds its
+ * `subCommands` record against it with `satisfies`, so a command added or
+ * removed there without a matching entry here is a type error rather than a
+ * silent drift — and tests that reason about invocations (see
+ * `test/recipe-cross-references.test.ts`) read the same list instead of
+ * restating it. It deliberately imports nothing: a consumer that only needs the
+ * names must not have to load the whole command tree to get them.
+ */
+export const SUBCOMMAND_NAMES = [
+  "agent",
+  "auth",
+  "check",
+  "detect",
+  "info",
+  "init",
+  "onboard",
+  "rule",
+  "test",
+  "update",
+  "verify",
+] as const;
+
+export type SubcommandName = (typeof SUBCOMMAND_NAMES)[number];

packages/cli/src/index.ts

@@ -7,6 +7,7 @@ import { detectCommand } from "./commands/detect";
 import { initCommand, updateCommand } from "./commands/init";
 import { testCommand, verifyCommand } from "./commands/verify";
 import { infoCommand } from "./commands/info";
+import { type SubcommandName } from "./commands/names";
 import { onboardCommand } from "./commands/onboard";
 import { ruleCommand } from "./commands/rules";
 import {
@@ -19,6 +20,11 @@ import { DIR_FLAGS, hasHelpFlag, splitRawArguments } from "./util/argv";
 import { showResolvedUsage } from "./util/help";
 import { CLIError } from "./util/cli-error";
 
+// `satisfies` against the name list (minus `agent`, which is constructed from
+// this record below) is what keeps `SUBCOMMAND_NAMES` honest: adding a command
+// here without naming it there — or naming one there that is never registered —
+// fails typecheck instead of quietly drifting away from every consumer that
+// reads the list.
 const subCommands = {
   init: initCommand,
   update: updateCommand,
@@ -30,7 +36,7 @@ const subCommands = {
   rule: ruleCommand,
   verify: verifyCommand,
   test: testCommand,
-};
+} satisfies Record<Exclude<SubcommandName, "agent">, unknown>;
 
 const agentCommand = createAgentCommand(subCommands);
 
@@ -61,7 +67,7 @@ const main = defineCommand({
   subCommands: {
     ...subCommands,
     agent: agentCommand,
-  },
+  } satisfies Record<SubcommandName, unknown>,
   async run({ rawArgs, cmd }) {
     // citty always calls the parent's run handler, even after a subcommand.
     // Only take action when no positional args (i.e. no subcommand) were

packages/cli/test/recipe-cross-references.test.ts

@@ -2,7 +2,9 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { describe, expect, it } from "vitest";
 
+import { SUBCOMMAND_NAMES } from "../src/commands/names";
 import { getRecipe } from "../src/prompts/recipes";
+import { buildInvocation } from "../src/util/invocation";
 
 /**
  * Recipes cite each other by topic name, in prose. Nothing resolves those
@@ -24,9 +26,41 @@ import { getRecipe } from "../src/prompts/recipes";
  */
 const recipeDirectory = resolve(import.meta.dirname, "../src/agent");
 
-/** The CLI's subcommands, as a recipe would name one. */
-const SUBCOMMANDS =
-  "agent|auth|check|detect|info|init|onboard|rule|test|update|verify";
+function escapeRegExp(literal: string): string {
+  return literal.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw`\$&`);
+}
+
+/**
+ * The CLI's subcommands, as a recipe would name one — read from the registry
+ * in `src/commands/names.ts` rather than restated here. A restated list is a
+ * blind spot with a delay on it: a subcommand added to the CLI but forgotten
+ * here drops out of the alternation, and the guard below stops flagging a
+ * hand-written `taskless <that-command>` without anything going red.
+ */
+const SUBCOMMANDS = SUBCOMMAND_NAMES.map((name) => escapeRegExp(name)).join(
+  "|"
+);
+
+/**
+ * Every spelling the CLI can carry in RENDERED recipe text, longest first so
+ * the alternation prefers the most specific.
+ *
+ * `<taskless-cli>` is what a prod build with no detected launcher renders, and
+ * `buildInvocation()` is whatever THIS build bakes in — `npx @taskless/cli` for
+ * prod, `npx @taskless/cli-nightly@<version>` for a nightly, and a bare
+ * `node <path>/index.js` for `dev`/`self`. That last one is why the list is
+ * derived rather than written out: a fixed `taskless|@taskless/cli` anchor
+ * matches nothing under `TASKLESS_BUILD_TARGET=self`, so every citation check
+ * below would find zero citations and pass without checking anything. The two
+ * bare legacy spellings stay in the list so a citation that regresses to one of
+ * them is still checked rather than silently skipped.
+ */
+const CLI_NAMES = [
+  escapeRegExp(buildInvocation()),
+  "<taskless-cli>",
+  "@taskless/cli",
+  "taskless",
+].join("|");
 
 /**
  * A CLI invocation spelled out in a recipe source instead of deferred to
@@ -74,7 +108,7 @@ describe("shipped recipes name only commands that exist", () => {
     const offenders: string[] = [];
     for (const [file, rendered] of await renderedRecipes()) {
       for (const [index, line] of rendered.split("\n").entries()) {
-        if (/(?:taskless|@taskless\/cli|<taskless-cli>) help\b/.test(line)) {
+        if (new RegExp(String.raw`(?:${CLI_NAMES}) help\b`).test(line)) {
           offenders.push(`${file}:${String(index + 1)}: ${line.trim()}`);
         }
       }
@@ -87,26 +121,33 @@ describe("shipped recipes name only commands that exist", () => {
   it("cites only topics that resolve to an embedded recipe", async () => {
     const topics = await embeddedTopics();
     const dangling: string[] = [];
+    const citation = new RegExp(
+      String.raw`(?:${CLI_NAMES}) agent ([a-z][a-z-]*)`,
+      "g"
+    );
+    let cited = 0;
 
     for (const [file, rendered] of await renderedRecipes()) {
       for (const [index, line] of rendered.split("\n").entries()) {
-        // `<taskless-cli> agent <topic>` is what the invocation renders to
-        // under a prod build with no detected launcher, and it is the form
-        // every recipe now uses. The two older spellings stay matched so a
-        // citation that regresses to one of them is still checked rather than
-        // silently skipped.
-        for (const match of line.matchAll(
-          /(?:taskless|@taskless\/cli|<taskless-cli>) agent ([a-z][a-z-]*)/g
-        )) {
+        for (const match of line.matchAll(citation)) {
           const topic = match[1];
-          if (topic !== undefined && !topics.has(topic)) {
+          if (topic === undefined) continue;
+          cited += 1;
+          if (!topics.has(topic)) {
             dangling.push(`${file}:${String(index + 1)} cites '${topic}'`);
           }
         }
       }
     }
 
     expect(dangling).toEqual([]);
+    // An empty `dangling` is the same result whether every citation resolved or
+    // the pattern matched none of them, and the second reads as a pass. Recipes
+    // cross-reference each other heavily, so a run that finds no citation at
+    // all has stopped measuring the thing it reports on.
+    expect(cited, "found no recipe cross-references to check").toBeGreaterThan(
+      10
+    );
   });
 
   // Every recipe is reachable by the name its filename implies. A header that
@@ -152,8 +193,13 @@ describe("recipes defer the CLI invocation to the renderer", () => {
 
   it("renders a real invocation into every recipe that names the CLI", async () => {
     const rendered = await renderedRecipes();
-    const naming = rendered.filter(([, text]) =>
-      text.includes("<taskless-cli>")
+    // Same build-target reasoning as CLI_NAMES: a prod build with no detected
+    // launcher renders the `<taskless-cli>` marker, every other target renders
+    // its own invocation, and hardcoding the marker would make this assert
+    // nothing under `dev`/`self`.
+    const naming = rendered.filter(
+      ([, text]) =>
+        text.includes("<taskless-cli>") || text.includes(buildInvocation())
     );
     // Nearly every recipe tells the reader to run something; if this drops to
     // a handful, the normalization has been undone rather than improved.