cans-spec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cans-hq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+<p align="center">
+  <strong style="font-size: 2em;">CANS</strong><br>
+  <em>Canonical Agent-Native Spec</em>
+</p>
+
+<p align="center">
+  <b>The outline is the spec. The outline is the state. The outline is the task board.<br>
+  There is nothing else.</b>
+</p>
+
+<p align="center">
+  <code>~1080 lines</code> · <code>0 dependencies</code> · <code>no build step</code> · <code>no schema</code> · <code>no pipeline</code>
+</p>
+
+---
+
+## The pitch
+
+Your spec is a markdown file with bullets. Your AI agent reads it and knows everything. Your state lives in checkboxes. Your coordination protocol is indentation and `see:` links. Your transport layer is git.
+
+There is no registry. There is no adapter. There is no artifact DAG. There is no Zod schema validating your English sentences. There is no telemetry phoning home. There is no 4-phase pipeline gating your Tuesday afternoon.
+
+There is a file. You edit it. `cans check` tells you if it's healthy. That's the whole product.
+
+---
+
+## Why this exists
+
+We used [OpenSpec](https://github.com/Fission-AI/OpenSpec). It's a fine project. It also ships 200+ files, 30+ tool adapters, a 4-artifact pipeline, Zod validation, DAG resolution, delta-spec merges, SHALL/MUST keyword enforcement, scenario counting, a telemetry system, a store/registry layer, and burns 50k–100k tokens per invocation.
+
+We tried deleting things. Everything kept working.
+
+So we kept deleting.
+
+| OpenSpec ships | CANS ships |
+|---|---|
+| 4-artifact pipeline (proposal → specs → design → tasks) | Edit the spec. ADR records why. Task tracks work. |
+| Zod schemas + DAG resolver + 30 adapter files | Structural lint on markdown bullets |
+| Delta-spec merge engine at archive time | `see:` references + `git diff` |
+| SHALL / MUST / WHEN / THEN / GIVEN keywords | Natural language. Dense bullets. |
+| ~36,000 tokens of agent instructions across 12 skills | ~800 tokens. One file. Loaded once. |
+| `openspec status --json` to query project state | Agents read the file. The file IS the state. |
+| 30+ tool-specific command formatters | One prompt block. String-replace the tool name. |
+| YAML frontmatter + markdown headers + requirement blocks | Bullets. Just bullets. |
+| Custom merge logic for spec reconciliation | Git merges. Humans resolve conflicts. |
+| Telemetry, stores, registries, profiles | None. |
+| **50,000–100,000 tokens per invocation** | **~800 tokens, loaded once** |
+
+OpenSpec is a framework. CANS is a file with a linter.
+
+---
+
+## See it in action
+
+```text
+You: cans init
+     ✓ Created cans/ with 7 spec files, _adr/, _tasks/, _collab/
+
+You:  (write your spec as dense bullets)
+      - Authentication
+        - Sign up
+          - Email: requires verification
+          - Google: uses provider verification
+        - Sessions
+          - Expire after 24 hours
+          - Refresh allowed for 30 days
+
+You: cans check
+     ✓ 7 files, 42 nodes, max depth 3
+     ✓ 3 see: refs, 0 broken, 0 deep hops
+     ✓ back-pointers: 3/3 current
+     0 errors, 0 warnings.
+
+You: cans new task add-dark-mode
+     ✓ Created _tasks/add-dark-mode.md
+
+You:  (agent implements, checks off tasks, edits specs directly)
+
+You: cans done add-dark-mode
+     ✓ Archived to _tasks/_archive/2025-09-03-add-dark-mode.md
+```
+
+No `/opsx:propose`. No `/opsx:apply`. No `/opsx:archive`. No pipeline. No phases. You edit the file. The agent edits the file. `cans check` keeps it honest.
+
+<details>
+<summary><b>What do the specs actually look like?</b></summary>
+
+Bullets. Indented. Dense. No special syntax. No keywords. No scenario blocks.
+
+```markdown
+- Authentication
+  - Sign up
+    - Email
+      - Requires verification
+      - Creates user account
+    - Google
+      - Uses provider verification
+  - Sessions
+    - Expire after 24 hours
+    - Refresh allowed for 30 days
+  - Passwords
+    - Never stored in plaintext
+    - Minimum 12 characters
+```
+
+Reference, don't duplicate:
+
+```markdown
+# in 04-api.md
+- Authentication
+  - Session rules: see 02-authentication.md#Sessions
+  - Requires Bearer token
+```
+
+That's it. That's the whole spec format. Your agent reads this and knows what to build.
+
+</details>
+
+---
+
+## Five principles
+
+**1. Dense over verbose.** Every bullet earns its place. No filler levels. No manufactured identifiers.
+
+```markdown
+# bad                          # good
+- Authentication               - Authentication
+  - Capability                   - Sign up
+    - Behavior
+      - Sign up
+```
+
+**2. Canonical over duplicated.** Every concept has one home. Everywhere else uses `see:`.
+
+**3. One hop. Never chain.** A→B is fine. A→B→C is forbidden. `cans check` catches it.
+
+**4. Unknowns are first-class.** `TBD` is valid. Don't guess. Don't block. Mark it, move on.
+
+**5. Structure emerges from subject.** No fixed hierarchy. No required vocabulary. No kebab-casing reality.
+
+---
+
+## What CANS does NOT do
+
+This is the most important section.
+
+- ❌ No schema.yaml / artifact DAG / topological sort
+- ❌ No Zod validation of requirement text
+- ❌ No SHALL / MUST keyword enforcement
+- ❌ No scenario counting (WHEN / THEN / GIVEN)
+- ❌ No 30 tool adapters / adapter registry
+- ❌ No YAML frontmatter in spec files
+- ❌ No "delta operations" (ADDED / MODIFIED / REMOVED)
+- ❌ No telemetry. None. Ever.
+- ❌ No store / registry system for multi-repo
+- ❌ No requirement-block parsing
+- ❌ No phase gates (proposal → specs → design → tasks)
+- ❌ No LLM-powered anything (CANS is deterministic; LLMs *use* CANS)
+- ❌ No auto-fixing (flags only, human decides)
+- ❌ No plugin system (10 commands, no extension points)
+- ❌ No web UI / dashboard
+- ❌ No database backend (files ARE the state)
+- ❌ No merge pipeline (agent edits specs directly)
+- ❌ No versioned schema migrations (delete a config key = disable that check)
+
+**CANS is advisory, not coercive.** The outline is the contract. `cans check` catches drift. Humans resolve it.
+
+---
+
+## Install
+
+Requires [Bun](https://bun.sh) ≥ 1.0 on your PATH (the CLI runs on the Bun runtime). No build step. Source IS distribution.
+
+**npm**
+
+```bash
+npm install -g cans-spec
+```
+
+**Bun**
+
+```bash
+bun install -g cans-spec
+```
+
+**One-shot, no install**
+
+```bash
+npx -p cans-spec cans init
+```
+
+All three give you the same `cans` command:
+
+```bash
+cd your-project
+cans init
+```
+
+Done. You have a `cans/` directory. Start writing bullets.
+
+### How to use it
+
+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.
+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.
+
+Everything else — ADRs, ownership arrows (`← agent-1`, `← @human`), rules in `_rules.yaml` — is documented inline by the scaffolded files.
+
+---
+
+## Commands
+
+```
+cans init          scaffold workspace
+cans check         validate everything (structure, refs, style, redundancy, overflow)
+cans new adr       create a decision record
+cans new task      create a task file
+cans done          archive completed task (blocks on ← @human gates)
+cans status        workspace summary
+cans budget read   token-budgeted reading plan for a concept
+cans budget write  what you can / can't edit for a concept
+cans import        bring in OPML / Logseq / Obsidian
+cans export        push out to OPML / Logseq / Obsidian
+```
+
+Every command supports `--json` for agent consumption.
+
+```bash
+cans check --json
+cans budget read "sessions" --limit 2000 --json
+cans status --json
+```
+
+---
+
+## How agents work with CANS
+
+Agents read one file: `cans/AGENTS.md`. It's ~800 tokens. Here's the gist:
+
+> **Reading:** Find the concept → read its canonical home → follow `see:` (one hop only) → read surrounding hierarchy for context.
+>
+> **Writing:** One canonical home per concept. Reference, don't duplicate. Preserve real identifiers. Mark unknowns as TBD. Smallest correct change.
+>
+> **Deciding:** Create an ADR. ADRs are permanent. Specs are the truth. ADRs record WHY.
+>
+> **Tracking:** Create a task. Agent edits specs directly. When done: `cans done <name>`. Blocks until `← @human` gates are checked.
+>
+> **Token budget:** Before reading: `cans budget read "<concept>" --json`. Read ONLY the files in the plan. Before writing: `cans budget write "<concept>" --json`. Only edit files in `canEdit`.
+
+That's the entire agent instruction surface. No 12 skills. No 30 adapters. No slash commands.
+
+---
+
+## Validation
+
+`cans check` runs five deterministic engines. No ML. No LLM. No embeddings.
+
+| Engine | Catches |
+|---|---|
+| **Structure** | Node length, depth, sibling count, single-child collapse, empty nodes |
+| **Style** | Sibling vs nested grouping, shared prefix detection |
+| **References** | Broken `see:`, deep hops (A→B→C), self-refs, orphans, stale back-pointers |
+| **Redundancy** | Word frequency, phrase overlap, fuzzy typos, cross-file duplication |
+| **Overflow** | Code fences, tables, oversized nodes that belong in separate files |
+
+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
+```
+
+---
+
+## Workspace layout
+
+```
+cans/
+├── _rules.yaml              # validation config
+├── AGENTS.md                # ~800-token agent instructions
+├── 00-overview.md
+├── 01-architecture.md
+├── 02-authentication.md
+├── 03-data.md
+├── 04-api.md
+├── 05-frontend.md
+├── 06-operations.md
+├── _adr/                    # decisions (permanent)
+│   ├── 001-css-variables-over-tailwind.md
+│   └── 002-postgres-over-mysql.md
+├── _tasks/                  # work tracking (transient)
+│   └── add-dark-mode.md
+└── _collab/                 # handoffs, conflicts, decision index
+```
+
+---
+
+## How we compare
+
+**vs. [OpenSpec](https://github.com/Fission-AI/OpenSpec)** — Comprehensive but heavy. 200+ files, 4-artifact pipelines, 30+ adapters, 50k–100k tokens per invocation. CANS is 1080 lines, zero deps, 800 tokens. You don't need a framework. You need a file.
+
+**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Rigid phase gates, Python setup, lots of Markdown. CANS has no phases. You edit the spec. That's the workflow.
+
+**vs. [Kiro](https://kiro.dev)** (AWS) — Locked to their IDE, limited to Claude. CANS is a CLI that reads markdown files. Works with any agent, any editor, any model.
+
+**vs. nothing** — AI coding without specs means vague prompts and drift. CANS gives you a contract in 800 tokens of agent instructions instead of 36,000.
+
+---
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.0
+- Git (for coordination; not required by CANS itself)
+- An AI agent that can read markdown (all of them)
+
+No Node.js. No Python. No `package-lock.json`. No `node_modules`. The `dependencies` field in `package.json` does not exist.
+
+---
+
+## Contributing
+
+The entire codebase is ~1080 lines of TypeScript across 20 files. Read it in an afternoon.
+
+- `bun test` runs the suite (~95 tests)
+- No build step. Edit `src/`, run `bun test`, done.
+- PRs that add features get closed. PRs that delete code get merged.
+- If you want a new command, open an issue and justify it. Most get rejected. That's the point.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "cans-spec",
+  "version": "0.1.0",
+  "description": "Canonical Agent-Native Spec — the outline is the spec, the state, and the task board",
+  "bin": { "cans": "./src/cli.ts" },
+  "type": "module",
+  "engines": { "bun": ">=1.0.0" },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "files": ["src/", "templates/", "README.md", "LICENSE"],
+  "keywords": [
+    "cans",
+    "spec",
+    "spec-driven",
+    "agents",
+    "agent-native",
+    "ai",
+    "markdown",
+    "outline"
+  ],
+  "author": "cans-hq",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cans-hq/cans-spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cans-hq/cans-spec/issues"
+  },
+  "homepage": "https://github.com/cans-hq/cans-spec#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/bun": "^1.1.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env bun
+
+import type { CommandResult } from './types';
+import { emit } from './core/output';
+
+/** §44: version line. Keep in sync with package.json. */
+const VERSION = '0.1.0';
+
+const [cmd, ...args] = Bun.argv.slice(2);
+
+async function dispatch(): Promise<CommandResult> {
+  switch (cmd) {
+    case 'init':    return (await import('./commands/init')).run(args);
+    case 'check':   return (await import('./commands/check')).run(args);
+    case 'new':     return (await import('./commands/new')).run(args);
+    case 'done':    return (await import('./commands/done')).run(args);
+    case 'status':  return (await import('./commands/status')).run(args);
+    case 'budget':  return (await import('./commands/budget')).run(args);
+    case 'import':  return (await import('./commands/import')).run(args);
+    case 'export':  return (await import('./commands/export')).run(args);
+    case 'help':
+    case '-h':      // §20/§44: conventional help shortcuts
+    case '--help':
+      return { ok: true, command: 'help', exitCode: 0 };
+    case 'version':
+    case '--version': // §44: version surface
+      return { ok: true, command: 'version', exitCode: 0, version: VERSION } as CommandResult;
+    default:
+      // §37: unknown / missing command must say what happened and how to fix it.
+      return {
+        ok: false,
+        command: cmd ?? 'unknown',
+        exitCode: 1,
+        error: cmd === undefined
+          ? 'no command given — run `cans help`'
+          : `unknown command "${cmd}" — run \`cans help\``,
+      } as CommandResult;
+  }
+}
+
+try {
+  const result = await dispatch();
+  emit(result, args.includes('--json'), args.includes('--refs-only'));
+  process.exit(result.exitCode);
+} catch (e) {
+  console.error(`✗ Internal error: ${e instanceof Error ? e.message : e}`);
+  process.exit(2);
+}

package/src/commands/budget.ts

@@ -0,0 +1,238 @@
+import { join } from 'path';
+import type { BudgetReadResult, BudgetWriteResult, OutlineNode, Rules } from '../types';
+import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists, isFile } from '../core/fs';
+import { parseOutline } from '../core/outline';
+import { loadRules } from '../core/rules';
+import { buildRefGraph } from '../core/refs';
+import { buildReadPlan, buildWritePlan } from '../core/token-budget';
+
+export interface BudgetArgs {
+  mode: 'read' | 'write';
+  /** The subcommand candidate found at the first non-flag position
+   *  ('' when absent, or the offending token for unknown-subcommand errors). */
+  sub: string;
+  concept: string;
+  limit: number | null;
+  change: string | null;
+  json: boolean;
+  /** §20/§37: malformed flags (--flag=value, unknown, missing value, invalid
+   *  --limit value) — user errors, never silently ignored. */
+  argErrors: string[];
+}
+
+/** §20 flag-position flexibility: budget's known flags (`--json` bool,
+ *  `--limit`/`--change` value flags) are recognized anywhere on the line —
+ *  including BEFORE the subcommand — so `budget --json read Sessions` ≡
+ *  `budget read Sessions --json`. Values following value-flags are consumed
+ *  even in the pre-scan; leftover tokens decide subcommand + concept.
+ *  Error wording mirrors the shared parser (§20: `--flag value` only). */
+export function parseBudgetArgs(args: string[]): BudgetArgs {
+  const rest: string[] = [];
+  const flagErrors: string[] = [];
+  let json = false;
+  let limitRaw: string | null = null;
+  let change: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+
+    // Reject --flag=value form
+    if (a.startsWith('--') && a.includes('=')) {
+      flagErrors.push(`invalid flag form "${a}" — use "--${a.slice(2).split('=')[0]} <value>"`);
+      continue;
+    }
+
+    // Reject short flags / combined flags
+    if (/^-[a-zA-Z]/.test(a) && !a.startsWith('--')) {
+      flagErrors.push(`unknown flag "${a}" — no short flags supported`);
+      continue;
+    }
+
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      if (name === 'json') {
+        json = true;
+        continue;
+      }
+      if (name === 'limit' || name === 'change') {
+        const val = args[i + 1];
+        if (val === undefined || val.startsWith('--')) {
+          flagErrors.push(`flag "--${name}" requires a value`);
+          continue;
+        }
+        if (name === 'limit') limitRaw = val;
+        else change = val;
+        i++; // consume value
+        continue;
+      }
+      flagErrors.push(`unknown flag "--${name}"`);
+      continue;
+    }
+
+    rest.push(a);
+  }
+
+  // §37: unknown subcommands must error, never silently run as `read`.
+  const sub = rest[0] === 'read' || rest[0] === 'write' ? rest[0] : (rest[0] ?? '');
+  const concept = rest[1] ?? '';
+
+  // §37: a malformed --limit value is a user error, not a silent default.
+  // 0 stays a valid (degenerate) limit; negative / non-numeric / non-integer
+  // values are rejected with the offending value named.
+  let limit: number | null = null;
+  if (limitRaw !== null) {
+    const n = Number(limitRaw);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+      flagErrors.push(`invalid --limit value "${limitRaw}" — pass a positive integer`);
+    } else {
+      limit = n;
+    }
+  }
+
+  return {
+    mode: sub === 'write' ? 'write' : 'read',
+    sub,
+    concept,
+    limit,
+    change,
+    json,
+    argErrors: flagErrors,
+  };
+}
+
+function readFail(concept: string, error: string): BudgetReadResult {
+  return {
+    ok: false, command: 'budget-read', exitCode: 1, concept,
+    plan: [], skipped: [], totalTokens: 0, budgetLimit: 0, usagePercent: 0,
+    error,
+  };
+}
+
+function writeFail(concept: string, error: string): BudgetWriteResult {
+  return {
+    ok: false, command: 'budget-write', exitCode: 1, concept,
+    canEdit: [], mustNotEdit: [], backPointersToUpdate: [],
+    error,
+  };
+}
+
+/** §37: say what happened and what to do when nothing matches the concept. */
+function noMatchError(concept: string): string {
+  return `no files match concept "${concept}" — check spelling or run \`cans status\``;
+}
+
+const NO_WORKSPACE_ERROR = 'no cans workspace found — run `cans init` first, or cd into a project with a cans/ directory';
+
+export async function run(args: string[]): Promise<BudgetReadResult | BudgetWriteResult> {
+  const opts = parseBudgetArgs(args);
+
+  // §37: reject unknown subcommands with a usage error (never success-shaped).
+  if (opts.sub !== 'read' && opts.sub !== 'write') {
+    const error = opts.sub === ''
+      ? 'usage: cans budget <read|write> <concept>'
+      : `unknown subcommand "${opts.sub}" — valid: read, write`;
+    return readFail(opts.sub, error);
+  }
+
+  // §20: `--flag value` only — malformed flags are user errors, not silently ignored.
+  if (opts.argErrors.length > 0) {
+    const error = opts.argErrors.join('\n');
+    return opts.mode === 'write' ? writeFail(opts.concept, error) : readFail(opts.concept, error);
+  }
+
+  if (opts.concept === '') {
+    return opts.mode === 'write'
+      ? writeFail('', 'usage: cans budget write <concept>\n  Example: cans budget write sessions')
+      : readFail('', 'usage: cans budget read <concept>\n  Example: cans budget read sessions');
+  }
+
+  const workspace = resolveWorkspaceRoot();
+  if (workspace === null) {
+    return opts.mode === 'write'
+      ? writeFail(opts.concept, NO_WORKSPACE_ERROR)
+      : readFail(opts.concept, NO_WORKSPACE_ERROR);
+  }
+
+  let rules: Rules;
+  try {
+    rules = loadRules(workspace);
+  } catch (e) {
+    const error = `invalid _rules.yaml: ${e instanceof Error ? e.message : String(e)}`;
+    return opts.mode === 'write' ? writeFail(opts.concept, error) : readFail(opts.concept, error);
+  }
+
+  const files = new Map<string, OutlineNode[]>();
+  for (const rel of discoverSpecFiles(workspace)) {
+    try {
+      files.set(rel, parseOutline(await Bun.file(join(workspace, rel)).text(), rel));
+    } catch {
+      // unreadable spec file: excluded from the plan
+    }
+  }
+  const graph = buildRefGraph(files, workspace);
+
+  if (opts.mode === 'read') {
+    // --change: center the plan on an active task file.
+    let taskFile: string | undefined;
+    if (opts.change !== null) {
+      const p = join(workspace, '_tasks', `${opts.change}.md`);
+      if (isFile(p)) taskFile = p;
+    }
+
+    // §26 step 3: active tasks mentioning the concept join the plan (score 80).
+    const activeTaskPaths = dirExists(join(workspace, '_tasks'))
+      ? discoverActiveTasks(workspace).map(rel => join(workspace, rel))
+      : [];
+
+    const result = buildReadPlan(
+      opts.concept,
+      files,
+      graph.back,
+      rules.token_budget,
+      opts.limit ?? undefined,
+      taskFile,
+      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`,
+          );
+        }
+      }
+      return { ...result, ok: false, exitCode: 1, error: noMatchError(opts.concept) };
+    }
+    // §18 token_budget.warn_threshold: warn when plan usage reaches the
+    // threshold. A deleted key (null) turns the warning off — never compare
+    // against null (it would coerce to 0 and warn on every plan).
+    const threshold = rules.token_budget.warn_threshold;
+    if (threshold !== null && result.usagePercent >= threshold * 100) {
+      console.error(
+        `  ⚠ warning: plan usage ${result.usagePercent}% of ${result.budgetLimit} tokens ` +
+        `exceeds token_budget.warn_threshold (${threshold * 100}%) — trim the plan or raise default_limit in _rules.yaml`,
+      );
+    }
+    return result;
+  }
+
+  // write
+  const activeTasks = dirExists(join(workspace, '_tasks'))
+    ? discoverActiveTasks(workspace).map(rel => join(workspace, rel))
+    : [];
+  const result = buildWritePlan(opts.concept, files, graph.back, activeTasks);
+  // §19: empty scope (no home, no mentioning task, no back-refs) = user-correctable failure.
+  if (result.canEdit.length === 0 && result.mustNotEdit.length === 0) {
+    return { ...result, ok: false, exitCode: 1, error: noMatchError(opts.concept) };
+  }
+  return result;
+}