cans-spec 0.3.0 → 0.5.0

package/README.md

@@ -212,7 +212,7 @@ Done. You have a `cans/` directory. Start writing bullets.
 
 1. **Scaffold** — `cans init` creates `cans/` with 7 spec files, `_adr/`, `_tasks/`, `_collab/`. Use `cans init --flat` for a flat layout, `--bare` for the minimal skeleton, `--tool claude` to also emit `CLAUDE.md`.
 2. **Write your spec as dense bullets** — hierarchy is indentation, cross-links are `see:` references. The outline is the spec; there is nothing else to learn.
-3. **Check health** — `cans check` lints structure, broken refs, deep hops, redundancy, style, and overflow. `cans check --fix` repairs back-pointers. Exit code 0 means clean.
+3. **Check health** — `cans check` lints structure, broken refs, deep hops, redundancy, style, and overflow. `cans check --fix` repairs back-pointers. Exit codes: `0` clean · `1` warnings · `2` errors — agents read `$?`, skip parsing.
 4. **Track work** — `cans new task add-dark-mode` creates a task, `cans status` shows the board, `cans done add-dark-mode` archives it (it blocks on `← @human` gates until a human signs off).
 5. **Mind the budget** — `cans budget read <concept>` gives your agent a token-budgeted reading plan; `cans budget write <concept>` says what it may edit.
 6. **Interoperate** — `cans export logseq --from cans` and `cans import logseq <path>` round-trip OPML / Dynalist, Logseq, and Obsidian. State lives in git; the transport layer is a plain text format your tools already read.
@@ -279,13 +279,22 @@ That's the entire agent instruction surface. No 12 skills. No 30 adapters. No sl
 Configure in `cans/_rules.yaml`. Delete a key to disable that check. No migration.
 
 ```bash
-cans check              # human-readable
-cans check --json       # machine-readable
-cans check --fix        # rebuild back-pointer comments (nothing else)
-cans check --strict     # warnings become errors
-cans check 04-api.md    # single file
+cans check                  # human-readable: one line per pattern, count prefixes,
+                            # root-cause grouping, timing on the summary line
+cans check --json           # machine-readable: sections → {file, line, rule, detail}
+cans check --show redundancy  # expand a folded section (structure|style|refs|
+                            #   redundancy|overflow|all — comma-separated list works)
+cans check --fix            # rebuild back-pointer comments (nothing else)
+cans check --strict         # warnings flip `ok` to false
+cans check 04-api.md        # single file
 ```
 
+The default report groups repeated findings: `61× <min children (2/3)` instead
+of 61 identical lines, `91× missing file` with per-target counts instead of 91
+lines + 91 fix hints. Fix hints appear once per pattern; every `file:line`
+stays present in compact comma lists. Exit codes: `0` clean · `1` warnings ·
+`2` errors.
+
 ---
 
 ## Workspace layout

package/bin/cans.js

@@ -1,21 +1,41 @@
 #!/usr/bin/env node
 /**
- * Portable launcher for the `cans` bin (issue #12).
+ * Portable launcher for the `cans` bin (issue #12; warning hygiene per issue #41).
  *
  * Priority: Bun stays the primary runtime.
  *   1. Already executing under Bun (`bunx cans-spec`, `bun run`) → run the CLI
- *      in-process; the runtime shim's Bun fast paths apply.
+ *      in-process; the runtime shim's Bun fast paths apply. No hooks needed.
  *   2. Bun on PATH but this launcher was started by Node (`npm i -g cans-spec`
  *      then `cans ...`) → re-exec `bun src/cli.ts` so Bun fast paths apply.
  *   3. No Bun → run the CLI in-process on Node, stripping TypeScript via
- *      Node's builtin `stripTypeScriptTypes` through bin/ts-loader.mjs (Node's
- *      default stripping refuses files under node_modules — see issue #12 QA).
+ *      Node's builtin `stripTypeScriptTypes`, installed in this order:
+ *        a. `module.registerHooks()` (Node ≥ 23.5) — in-process SYNCHRONOUS
+ *           hooks. No loader thread, so Node never prints the loader-thread
+ *           ExperimentalWarning, and `module.register()` is never called —
+ *           so Node ≥ 26 can never emit its
+ *           "`module.register()` is deprecated. Use `module.registerHooks()`"
+ *           DeprecationWarning (issue #41: that line leaked into users'
+ *           captured stdout pipelines). The fix is by construction, not by
+ *           filtering.
+ *        b. `module.register()` fallback (Node 23.2–23.4, no registerHooks) —
+ *           spawns bin/ts-loader.mjs in a loader thread; both the
+ *           stripTypeScriptTypes ExperimentalWarning and any
+ *           `module.register` DeprecationWarning are suppressed below
+ *           (CANS_DEBUG_WARNINGS=1 restores them).
+ *        c. Neither hook API → actionable error, exit 1.
+ *
+ * Warning policy (issue #41 design rule 6): runtime warnings NEVER reach
+ * stdout. The stripTypeScriptTypes ExperimentalWarning is always suppressed;
+ * every other warning goes to stderr via console.error — never stdout.
+ *
+ * Node's builtin stripping refuses files under node_modules — bin/ts-loader.mjs
+ * documents why the stripping lives here (issue #12 QA).
  *
  * This file is plain JavaScript ON PURPOSE: it must execute on any Node that
  * npm can provide, before any TypeScript capability is available.
  */
 import { spawnSync } from 'node:child_process';
-import { register } from 'node:module';
+import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -35,7 +55,8 @@ async function runInProcess() {
   }
 }
 
-// 1. Already under Bun — in-process, Bun fast paths.
+// 1. Already under Bun — in-process, Bun fast paths. Bun prints no runtime
+//    warnings for this workload; no hooks or filters are installed here.
 if (typeof globalThis.Bun !== 'undefined') {
   await runInProcess();
 }
@@ -54,7 +75,8 @@ if (!probe.error && probe.status === 0) {
 // 3. Node fallback — needs node:module.stripTypeScriptTypes (Node ≥23.2; made
 //    stable in 23.6). Termux `pkg install nodejs` ships 26.x, which qualifies.
 //    Namespace access (not a named import) so older Nodes link this file fine.
-const { stripTypeScriptTypes } = await import('node:module');
+const nodeModule = await import('node:module');
+const { stripTypeScriptTypes } = nodeModule;
 if (typeof stripTypeScriptTypes !== 'function') {
   console.error(
     `✗ cans requires Bun >= 1.0 (primary) or Node >= 23.2 with builtin TypeScript stripping; found Node ${process.versions.node} without Bun.`,
@@ -63,14 +85,65 @@ if (typeof stripTypeScriptTypes !== 'function') {
   process.exit(1);
 }
 
-// Node prints an ExperimentalWarning for stripTypeScriptTypes on every run;
-// suppress just that one and pass everything else through untouched.
+// Warning policy (issue #41, design rule 6): keep runtime warnings off stdout.
+//  - The stripTypeScriptTypes ExperimentalWarning is always suppressed: it
+//    describes Node's own machinery, not the user's spec. It fires once per
+//    process on the first strip call (registerHooks path) or inside the loader
+//    thread (register path — silenced there too, see bin/ts-loader.mjs).
+//  - The `module.register()` DeprecationWarning can only exist when register()
+//    is actually called (fallback b, Node 23.2–23.4); suppressing it here as
+//    well is by-construction safe — path (a) never calls register(), so the
+//    warning cannot exist there.
+//  - Anything else still goes to stderr (console.error) — never stdout.
+//  - CANS_DEBUG_WARNINGS=1 restores every warning on both paths (escape hatch).
 process.removeAllListeners('warning');
 process.on('warning', (w) => {
-  if (w && w.name === 'ExperimentalWarning' && String(w.message).includes('stripTypeScriptTypes')) return;
-  console.error(`(node:${process.pid}) [${w?.name ?? 'Warning'}] ${w?.message ?? w}`);
+  const msg = String(w?.message ?? w ?? '');
+  if (process.env.CANS_DEBUG_WARNINGS === '1') {
+    console.error(`(node:${process.pid}) [${w?.name ?? 'Warning'}] ${msg}`);
+    return;
+  }
+  if (w?.name === 'ExperimentalWarning' && /striptypescript|type.?stripping/i.test(msg)) return;
+  if (w?.name === 'DeprecationWarning' && msg.includes('module.register')) return;
+  console.error(`(node:${process.pid}) [${w?.name ?? 'Warning'}] ${msg}`);
 });
 
-// 4. Register the .ts loader hook, then execute the CLI in-process.
-register(new URL('./ts-loader.mjs', import.meta.url));
-await runInProcess();
+// 4a. Preferred: in-process synchronous hooks (Node ≥ 23.5). Same
+//     load(url, context, nextLoad) contract as the register() loader, but no
+//     loader thread → no ExperimentalWarning, and no register() call → no
+//     DeprecationWarning on Node ≥ 26. registerHooks hooks must be
+//     SYNCHRONOUS (Node validates the returned source synchronously), so this
+//     is the sync twin of bin/ts-loader.mjs's load hook — keep the two
+//     logic-for-byte equivalent.
+if (typeof nodeModule.registerHooks === 'function') {
+  nodeModule.registerHooks({
+    load(url, context, nextLoad) {
+      if (url.endsWith('.ts')) {
+        const file = fileURLToPath(url);
+        // Node ≥23.2 returns an object ({ source }); some versions return the
+        // stripped string directly — accept both shapes (same as ts-loader).
+        const result = stripTypeScriptTypes(readFileSync(file, 'utf8'), { sourceUrl: file });
+        const source = typeof result === 'string' ? result : result?.source;
+        return { format: 'module', source, shortCircuit: true };
+      }
+      return nextLoad(url, context);
+    },
+  });
+  await runInProcess();
+}
+
+// 4b. Fallback: loader-thread register() (Node 23.2–23.4, no registerHooks).
+//     bin/ts-loader.mjs performs the same stripping inside the thread (where
+//     the thread's own ExperimentalWarning is silenced, unless
+//     CANS_DEBUG_WARNINGS=1).
+if (typeof nodeModule.register === 'function') {
+  nodeModule.register(new URL('./ts-loader.mjs', import.meta.url));
+  await runInProcess();
+}
+
+// 4c. Neither hook API exists — too old to run the CLI without Bun.
+console.error(
+  `✗ cans needs module.registerHooks (Node >= 23.5) or module.register (Node >= 23.2) to run without Bun; found Node ${process.versions.node}.`,
+);
+console.error('  Install Bun: https://bun.sh — Termux: pkg install nodejs.');
+process.exit(1);

package/bin/ts-loader.mjs

@@ -1,5 +1,5 @@
 /**
- * ESM loader hook for the Node fallback runtime (issue #12).
+ * ESM loader hook for the Node fallback runtime (issue #12, register() path).
  *
  * Node's built-in TypeScript type-stripping refuses to process files under
  * `node_modules`, which breaks `npm i -g cans-spec` on machines without Bun —
@@ -7,6 +7,12 @@
  * SAME erasable-syntax stripping ourselves via Node's builtin
  * `node:module.stripTypeScriptTypes` (no dependencies, no build step — source
  * stays distribution), bypassing only that path-based veto.
+ *
+ * Issue #41: since Node ≥ 23.5 offers `module.registerHooks()` (in-process
+ * synchronous hooks), bin/cans.js prefers it and this file is only loaded when
+ * register() is the only option (Node 23.2–23.4) — the loader thread that
+ * register() spawns. cans.js carries a synchronous twin of the load() hook
+ * below for the registerHooks path; keep the two logic-for-byte equivalent.
  */
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
@@ -14,7 +20,8 @@ import { stripTypeScriptTypes } from 'node:module';
 
 // This hook runs inside Node's loader thread, whose default handler prints the
 // `stripTypeScriptTypes` ExperimentalWarning on every CLI run. Suppress warnings
-// scoped to THIS thread only (CANS_DEBUG_WARNINGS=1 restores them).
+// scoped to THIS thread only (CANS_DEBUG_WARNINGS=1 restores them). The main
+// thread's warning policy lives in bin/cans.js.
 if (process.env.CANS_DEBUG_WARNINGS !== '1') {
   process.removeAllListeners('warning');
   process.on('warning', () => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cans-spec",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Canonical Agent-Native Spec — the outline is the spec, the state, and the task board",
   "bin": {
     "cans": "./bin/cans.js"

package/src/cli.ts

@@ -45,7 +45,12 @@ async function dispatch(): Promise<CommandResult> {
 
 try {
   const result = await dispatch();
-  emit(result, args.includes('--json'), args.includes('--refs-only'));
+  // issue #41: check's --show sections are parsed for the EMIT side only —
+  // lazily, so non-check commands never load the check module.
+  const show = cmd === 'check'
+    ? (await import('./commands/check.ts')).showSectionsFromArgs(args)
+    : undefined;
+  emit(result, args.includes('--json'), args.includes('--refs-only'), show);
   process.exit(result.exitCode);
 } catch (e) {
   console.error(`✗ Internal error: ${e instanceof Error ? e.message : e}`);

package/src/commands/budget.ts

@@ -1,5 +1,7 @@
 import { join, basename } from 'path';
-import type { BudgetReadResult, BudgetWriteResult, OutlineNode, Rules } from '../types.ts';
+import type {
+  BudgetReadResult, BudgetWriteResult, OutlineNode, Rules, TokenBudgetRules,
+} from '../types.ts';
 import { readText } from '../core/runtime.ts';
 import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists } from '../core/fs.ts';
 import { parseOutline } from '../core/outline.ts';
@@ -101,6 +103,47 @@ export function parseBudgetArgs(args: string[]): BudgetArgs {
   };
 }
 
+/** §18/§26 (QA-17 round 6, F16/F47/F50): the `token_budget` values are user
+ *  config consumed by BOTH budget commands — validated exactly like the
+ *  `--limit` flag, so a garbage value or a dead switch can never silently
+ *  succeed. Returns the §19 user-correctable error message naming the key and
+ *  the file, or null when the config is valid.
+ *
+ *  - `enabled` must be a boolean. `false` observably disables budget planning:
+ *    `budget read` / `budget write` refuse (F16 — the switch is real config,
+ *    not dead). An empty value (null) keeps the documented default (true),
+ *    the same §18 empty-value convention `prefer:`/`mode:` follow.
+ *  - `default_limit` gets the SAME validation as `--limit` (flag≡config
+ *    parity, issue #15): a finite non-negative integer. 0 stays a valid
+ *    (degenerate) limit that affords nothing — the truthful empty-plan
+ *    diagnosis names it, exactly like `--limit 0` does.
+ *  - `estimate_chars_per_token` must be a finite positive number. A value of
+ *    0 or less makes every estimate Infinity and no limit could ever fix it
+ *    (F50) — the error names the real cause instead of blaming the limit. */
+export function validateTokenBudgetRules(tb: TokenBudgetRules): string | null {
+  // Values arrive from the YAML merge at runtime; the static types describe
+  // the valid shape only, so compare through unknown.
+  const enabled: unknown = tb.enabled;
+  if (enabled !== null && typeof enabled !== 'boolean') {
+    return `invalid token_budget.enabled "${String(enabled)}" in _rules.yaml — pass true or false`;
+  }
+  if (enabled === false) {
+    return 'budget planning disabled: token_budget.enabled is false in _rules.yaml — set it to true (or delete the key) to plan budgets';
+  }
+  const defaultLimit: unknown = tb.default_limit;
+  if (
+    typeof defaultLimit !== 'number' || !Number.isFinite(defaultLimit) ||
+    !Number.isInteger(defaultLimit) || defaultLimit < 0
+  ) {
+    return `invalid token_budget.default_limit "${String(defaultLimit)}" in _rules.yaml — pass a positive integer`;
+  }
+  const cpt: unknown = tb.estimate_chars_per_token;
+  if (typeof cpt !== 'number' || !Number.isFinite(cpt) || cpt <= 0) {
+    return `invalid token_budget.estimate_chars_per_token "${String(cpt)}" in _rules.yaml — pass a positive number`;
+  }
+  return null;
+}
+
 function readFail(concept: string, error: string): BudgetReadResult {
   return {
     ok: false, command: 'budget-read', exitCode: 1, concept,
@@ -162,6 +205,18 @@ export async function run(args: string[]): Promise<BudgetReadResult | BudgetWrit
     return opts.mode === 'write' ? writeFail(opts.concept, error) : readFail(opts.concept, error);
   }
 
+  // §18/§26 (QA-17 round 6): both budget commands validate the token_budget
+  // VALUES the moment the rules load — flag≡config parity for limit values
+  // (issue #15, F47), a real `enabled` switch (F16), and finite token
+  // estimates (F50). A garbage config value is a user-correctable error even
+  // when a valid --limit is present: silently ignoring it was the F47 hole.
+  const budgetConfigError = validateTokenBudgetRules(rules.token_budget);
+  if (budgetConfigError !== null) {
+    return opts.mode === 'write'
+      ? writeFail(opts.concept, budgetConfigError)
+      : readFail(opts.concept, budgetConfigError);
+  }
+
   const files = new Map<string, OutlineNode[]>();
   for (const rel of discoverSpecFiles(workspace)) {
     try {
@@ -210,21 +265,37 @@ export async function run(args: string[]): Promise<BudgetReadResult | BudgetWrit
       activeTaskPaths,
     );
     if (result.plan.length === 0) {
-      // §37 truthfulness: distinguish "the concept matches nothing" from
-      // "the limit is smaller than the cheapest matching item" — a limit
-      // problem must never be reported as a spelling problem (QA-10 M2b).
-      if (opts.limit !== null) {
-        const unbounded = buildReadPlan(
-          opts.concept, files, graph.back, rules.token_budget,
-          undefined, taskFile, activeTaskPaths,
-        );
-        if (unbounded.plan.length > 0) {
-          const cheapest = Math.min(...unbounded.plan.map(p => p.estTokens));
-          return readFail(
-            opts.concept,
-            `plan empty: --limit ${opts.limit} is below the cheapest item (${cheapest} tok) — raise the limit`,
-          );
-        }
+      // §37 truthfulness (issues #15/#16): distinguish "the concept matches
+      // nothing" from "the effective limit cannot afford any matching item" —
+      // a limit problem must never be reported as a spelling problem
+      // (QA-10 M2b), regardless of whether the limit came from an explicit
+      // --limit flag or from token_budget.default_limit in _rules.yaml (the
+      // two paths to the identical limit value must behave identically). The
+      // comparison plan is TRULY unbounded (Infinity — `undefined` would fall
+      // back to rules.default_limit and hide cases behind the same tiny
+      // limit), so it is non-empty exactly when the concept matches at least
+      // one file.
+      const unbounded = buildReadPlan(
+        opts.concept, files, graph.back, rules.token_budget,
+        Infinity, taskFile, activeTaskPaths,
+      );
+      if (unbounded.plan.length > 0) {
+        // Best-effort packing (§26 step 4) already includes every matching
+        // item that fits, so an empty plan means the limit is below EVERY
+        // item — name the top-priority item that busts it (file + estTokens),
+        // the actual source of the limit, and the matching remedy; never a
+        // false cause.
+        const top = unbounded.plan[0]!;
+        const source = opts.limit !== null
+          ? `--limit ${opts.limit}`
+          : `token_budget.default_limit (${result.budgetLimit}) in _rules.yaml`;
+        const remedy = opts.limit !== null
+          ? 'raise the limit'
+          : 'raise default_limit or pass --limit';
+        return {
+          ...result, ok: false, exitCode: 1,
+          error: `plan empty: ${source} is below the top-priority item ${top.file} (${top.estTokens} tok) — ${remedy}`,
+        };
       }
       return { ...result, ok: false, exitCode: 1, error: noMatchError(opts.concept) };
     }