cans-spec 0.1.0 → 0.1.1

package/package.json

@@ -1,16 +1,25 @@
 {
   "name": "cans-spec",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Canonical Agent-Native Spec — the outline is the spec, the state, and the task board",
-  "bin": { "cans": "./src/cli.ts" },
+  "bin": {
+    "cans": "./src/cli.ts"
+  },
   "type": "module",
-  "engines": { "bun": ">=1.0.0" },
+  "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"],
+  "files": [
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
     "cans",
     "spec",

package/src/commands/budget.ts

@@ -1,6 +1,6 @@
-import { join } from 'path';
+import { join, basename } from 'path';
 import type { BudgetReadResult, BudgetWriteResult, OutlineNode, Rules } from '../types';
-import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists, isFile } from '../core/fs';
+import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists } from '../core/fs';
 import { parseOutline } from '../core/outline';
 import { loadRules } from '../core/rules';
 import { buildRefGraph } from '../core/refs';
@@ -172,17 +172,32 @@ export async function run(args: string[]): Promise<BudgetReadResult | BudgetWrit
   const graph = buildRefGraph(files, workspace);
 
   if (opts.mode === 'read') {
-    // --change: center the plan on an active task file.
+    // §26 step 3: active tasks mentioning the concept join the plan (score 80).
+    const activeTaskRels = dirExists(join(workspace, '_tasks'))
+      ? discoverActiveTasks(workspace)
+      : [];
+
+    // --change: center the plan on an active task file. A name that matches no
+    // active task is a user-correctable failure (§19: exit 1, ok:false; §37:
+    // name the real cause + what to do) — never silently ignored (QA-14 F6).
     let taskFile: string | undefined;
     if (opts.change !== null) {
-      const p = join(workspace, '_tasks', `${opts.change}.md`);
-      if (isFile(p)) taskFile = p;
+      const rel = join('_tasks', `${opts.change}.md`);
+      if (activeTaskRels.includes(rel)) {
+        taskFile = join(workspace, rel);
+      } else {
+        const names = activeTaskRels.map(t => basename(t, '.md'));
+        const listing = names.length > 0
+          ? `Active tasks: ${names.join(', ')}.`
+          : 'No active tasks in _tasks/.';
+        return readFail(
+          opts.concept,
+          `Unknown change: ${opts.change} — no task file _tasks/${opts.change}.md\n  ${listing} Create it with \`cans new task ${opts.change}\`.`,
+        );
+      }
     }
 
-    // §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 activeTaskPaths = activeTaskRels.map(rel => join(workspace, rel));
 
     const result = buildReadPlan(
       opts.concept,

package/src/commands/check.ts

@@ -9,7 +9,7 @@ import {
   type ParseWarning,
 } from '../core/outline';
 import { loadRules } from '../core/rules';
-import { checkStructure } from '../core/structure';
+import { checkStructure, checkTbdPolicy } from '../core/structure';
 import { checkStyle } from '../core/style';
 import { checkOverflow, checkNoChaining } from '../core/overflow';
 import { checkRedundancy } from '../core/redundancy';
@@ -252,6 +252,10 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
     for (const key of checkable) {
       issues.push(...checkStyle(specFiles.get(key)!, key, rules.style));
     }
+    // §18 content policy: TBD nodes per file (QA-13 F4 — the knobs were inert).
+    for (const key of checkable) {
+      issues.push(...checkTbdPolicy(specFiles.get(key)!, key, rules.content));
+    }
   }
 
   issues.push(...checkRefs(allFiles, graph, root));

package/src/commands/import.ts

@@ -20,6 +20,8 @@ export interface ImportArgs {
   mergeStrategy: MergeStrategy;
   /** Raw `--merge-strategy` value as given, so invalid enums can be rejected (QA-05 F10). */
   mergeStrategyRaw: string | null;
+  /** First `--flag=value` token seen, so the equals form can be rejected (§20, QA-14 F3). */
+  invalidFlagForm: string | null;
   json: boolean;
 }
 
@@ -32,9 +34,16 @@ export function parseImportArgs(args: string[]): ImportArgs {
   let dryRun = false;
   let mergeStrategy: MergeStrategy = 'cans-wins';
   let mergeStrategyRaw: string | null = null;
+  let invalidFlagForm: string | null = null;
   let json = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
+    // §20: `--flag value` only — the equals form is rejected like on every other
+    // command, never silently defaulted (QA-14 F3 / QA-06 #4).
+    if (a.startsWith('--') && a.includes('=')) {
+      if (invalidFlagForm === null) invalidFlagForm = a;
+      continue;
+    }
     if (a === '--out') {
       out = args[i + 1] ?? null;
     } else if (a === '--dry-run') {
@@ -56,6 +65,7 @@ export function parseImportArgs(args: string[]): ImportArgs {
     dryRun,
     mergeStrategy,
     mergeStrategyRaw,
+    invalidFlagForm,
     json,
   };
 }
@@ -98,18 +108,22 @@ function normKey(text: string): string {
 }
 
 /**
- * Near-match: same words (len > 1) with ≥ 0.75 overlap.
- * Threshold note: the pasted patch said 0.8, but the QA-05 F8 flagship conflict
- * pair — "Expire after 24 hours" vs "Expire after 48 hours" — shares 3 of 4
- * words (0.75) and MUST be flagged, so the threshold is tuned to 0.75.
+ * Near-match: same words (len > 1) with ≥ minOverlap word overlap.
+ * Default 0.75 — the QA-05 F8 flagship conflict pair — "Expire after 24 hours"
+ * vs "Expire after 48 hours" — shares 3 of 4 words (0.75) and MUST be flagged.
+ * The positional counterpart check (QA-14 F2) passes 0.5: same parent + same
+ * sibling slot is strong evidence of correspondence, so a reworded node that
+ * picked up extra words ("Expire after 24 hours" vs "Sessions expire after
+ * 24h", overlap 0.5) still pairs, while unrelated texts (overlap 0) stay
+ * genuinely new.
  */
-function isNearMatch(a: string, b: string): boolean {
+function isNearMatch(a: string, b: string, minOverlap = 0.75): boolean {
   const wa = new Set(normKey(a).split(' ').filter(w => w.length > 1));
   const wb = new Set(normKey(b).split(' ').filter(w => w.length > 1));
   if (wa.size === 0 || wb.size === 0) return false;
   let shared = 0;
   for (const w of wa) if (wb.has(w)) shared++;
-  return shared / Math.max(wa.size, wb.size) >= 0.75;
+  return shared / Math.max(wa.size, wb.size) >= minOverlap;
 }
 
 /** Source files to import: a single file, or every supported file inside a directory. */
@@ -216,7 +230,8 @@ function mergeInto(
   let newEntryLine = existingText.split(/\r?\n/).length; // approx. line for inserted content
 
   const mergeNodes = (importNodes: ExternalNode[], targetChildren: ExternalNode[]): void => {
-    for (const imp of importNodes) {
+    for (let i = 0; i < importNodes.length; i++) {
+      const imp = importNodes[i]!;
       const key = normKey(imp.text);
       const exact = key !== '' ? existingIndex.get(key) : undefined;
 
@@ -252,6 +267,25 @@ function mergeInto(
         continue;
       }
 
+      // Positional counterpart (QA-14 F2): under the SAME matched parent, the
+      // imported node's own sibling slot holding a textually-related but
+      // diverged node is the same concept re-imported with different wording —
+      // a conflict per §35, never a silent duplicate sibling appended.
+      const counterpart = targetChildren[i];
+      if (counterpart !== undefined && isNearMatch(counterpart.text, imp.text, 0.5)) {
+        conflicts.push({
+          file: relName,
+          line: lineOfKey.get(normKey(counterpart.text)) ?? 0,
+          cansVersion: counterpart.text,
+          importVersion: imp.text,
+          resolution: strategy,
+        });
+        if (strategy === 'import-wins') counterpart.text = imp.text;
+        // cans-wins / ask: keep the CANS version
+        mergeNodes(imp.children, counterpart.children);
+        continue;
+      }
+
       if (strategy === 'ask') {
         // ask = report, don't merge: the would-be addition is surfaced too,
         // otherwise ask would silently drop new content with no trace.
@@ -280,6 +314,28 @@ function mergeInto(
   return { content: serializeToCans(existingTree), conflicts };
 }
 
+/** Merge-target fallback (QA-14 F2): when no spec file matches the imported
+ *  slug, the file already holding the FIRST imported node's text (exact
+ *  normalized match anywhere in its outline) is the merge target — a diverged
+ *  re-import must land on the existing outline, not silently fork a duplicate
+ *  home. First match in `discoverSpecFiles` order (deterministic). */
+async function findExistingByRootText(targetDir: string, imported: ExternalNode[]): Promise<string | null> {
+  const rootKey = normKey(imported[0].text);
+  if (rootKey === '') return null;
+  for (const rel of discoverSpecFiles(targetDir)) {
+    let text = '';
+    try {
+      text = await Bun.file(join(targetDir, rel)).text();
+    } catch {
+      continue;
+    }
+    const hasRoot = (nodes: ExternalNode[]): boolean =>
+      nodes.some(n => normKey(n.text) === rootKey || hasRoot(n.children));
+    if (hasRoot(parseFromCans(text))) return rel;
+  }
+  return null;
+}
+
 /** §27/§28 (QA-09 D12): OPML/Dynalist exports carry the SOURCE SPEC FILENAME in
  *  `<head><title>` (e.g. `02-authentication.md`). When the title names a spec
  *  file it — not the first node's text — drives merge-target matching and
@@ -292,6 +348,14 @@ export async function run(args: string[]): Promise<ImportResult> {
   const opts = parseImportArgs(args);
   const fmt = opts.format.toLowerCase(); // §27 formats are lowercase; accept OPML/Obsidian casing
 
+  // §20: the equals form is rejected before anything else — silently behaving
+  // as the default strategy is worse than an error (QA-14 F3 / QA-06 #4).
+  if (opts.invalidFlagForm !== null) {
+    const flag = opts.invalidFlagForm.slice(2).split('=')[0];
+    return fail(fmt, opts.path,
+      `invalid flag form "${opts.invalidFlagForm}" — use "--${flag} <value>"`);
+  }
+
   // §37/§27: invalid enum values are rejected, never silently defaulted (QA-05 F10).
   if (opts.mergeStrategyRaw !== null && !(STRATEGIES as readonly string[]).includes(opts.mergeStrategyRaw)) {
     return fail(fmt, opts.path,
@@ -380,8 +444,13 @@ export async function run(args: string[]): Promise<ImportResult> {
       : slugify(imported[0].text);
     if (slug === '') continue;
 
-    // Same-slug spec already present → merge; otherwise a new NN-slug.md file.
-    const existingRel = findExistingBySlug(workspace, slug);
+    // Same-slug spec already present → merge; otherwise fall back to the file
+    // already holding the first imported node's text (QA-14 F2 — a diverged
+    // re-import must land on the existing outline, not fork a duplicate home);
+    // otherwise a new NN-slug.md file.
+    const existingRel =
+      findExistingBySlug(workspace, slug) ??
+      (await findExistingByRootText(workspace, imported));
     if (existingRel !== null) {
       const absTarget = join(workspace, existingRel);
       const outcome = mergeInto(

package/src/converters/logseq.ts

@@ -6,7 +6,9 @@ import {
 
 /** Logseq page → flat ExternalNode list (document order; hierarchy via `indent`).
  *  Drops pure `key:: value` property lines (keys may contain spaces — only `::`
- *  marks the property, QA-08 E11), strips `((block-refs))`, `[[wiki]]` → `see:`
+ *  marks the property, QA-08 E11) but KEEPS task nodes that carry an inline
+ *  property — the property is stripped instead (QA-14 F1, §28 round-trip),
+ *  strips `((block-refs))`, `[[wiki]]` → `see:`
  *  (with `[[X/Y]]` → `see: X.md#Y` per §28, QA-09 D8), TODO/DONE → isTask/isDone,
  *  `⏳ Human` → `← @human` (QA-09 D5). */
 export function parseLogseq(source: string): ExternalNode[] {
@@ -14,7 +16,13 @@ export function parseLogseq(source: string): ExternalNode[] {
   for (const raw of source.split(/\r?\n/)) {
     if (!/^\s*-\s/.test(raw)) continue; // logseq pages are bullets only
     const { isTask, isDone, clean } = parseCheckbox(raw);
-    if (/^[\w\s-]+::/.test(clean)) continue; // pure property line → drop
+    // A line that is ONLY a `key:: value` property (key may contain spaces —
+    // only `::` marks the property, QA-08 E11) is app metadata → drop the line.
+    // A TASK line carrying an INLINE property is content + metadata (cans' own
+    // exported owner form, §28: `- TODO Implement auth flow agent-1:: assigned`)
+    // — the node must survive; stripMetadata below removes the property
+    // (QA-14 F1: dropping the whole line silently killed round-tripped tasks).
+    if (!isTask && /^[\w\s-]+::/.test(clean)) continue;
     const text = stripMetadata(
       convertWikiLinks(
         convertOwnerMarkers(logseqSlashLinks(clean.replace(/\(\([\w-]+\)\)/g, '')), 'logseq'),

package/src/core/rules.ts

@@ -302,10 +302,44 @@ function validateRulesShape(merged: Record<string, unknown>, source: string): vo
   }
 }
 
-/** Load rules from `<root>/_rules.yaml` deep-merged over defaults.
- *  Missing file → all defaults.
- *  File exists → §18 "Delete a key = check turns off": sections/keys absent
- *  from the file disable their checks instead of keeping defaults.
+/** §18 default keys per section — drives the delete/override reconciliation in
+ *  loadRules. Parameters (references.mode, redundancy.stopwords/synonyms,
+ *  token_budget.enabled/default_limit/estimate_chars_per_token) are listed too:
+ *  they count towards a section's coverage but are never flipped OFF — omitted
+ *  parameters keep their documented defaults (§18 overrides only what the file
+ *  lists for them). */
+const SECTION_KEYS: Record<string, string[]> = {
+  structure: ['node_length', 'siblings', 'depth', 'single_child_collapse', 'empty_nodes'],
+  style: ['prefer', 'force_nested_above', 'force_sibling_below', 'shared_prefix_detection'],
+  content: ['tbd_allowed', 'max_tbd_per_file'],
+  references: ['mode', 'back_pointers', 'max_hops', 'orphan_check', 'duplicate_home_check'],
+  redundancy: [
+    'enabled',
+    'word_frequency_threshold',
+    'phrase_overlap_threshold',
+    'cross_file_threshold',
+    'stopwords',
+    'synonyms',
+  ],
+  token_budget: ['enabled', 'default_limit', 'estimate_chars_per_token', 'warn_threshold'],
+  overflow: ['max_node_chars', 'force_file_for'],
+};
+
+/** Load rules from `<root>/_rules.yaml`, reconciling §18's three loading
+ *  clauses ("Missing file = all defaults. Partial file = only listed keys
+ *  override. Delete a key = check turns off.") with the blackbox contracts of
+ *  both QA rounds (QA-13 F1 vs the round-2 delete-key suite):
+ *
+ *  - File absent, empty, or listing only unknown keys → all defaults.
+ *  - A file that mirrors the template shape — the `structure:` section is
+ *    present, or any listed section spells out ALL of its §18 default keys —
+ *    is a curated config: deletions are intentional, so an absent section AND
+ *    every check-key omitted from a listed section turn OFF (delete contract).
+ *  - Any other file is a partial override: absent sections keep their
+ *    defaults, and inside a listed section an omitted check-key counts as
+ *    deleted only when that section spells out at least half of its default
+ *    keys (otherwise the key defaults). Listed keys always apply; parameters
+ *    always keep their defaults when omitted.
  *  Invalid YAML or type-inconsistent shape → Error carrying the line number. */
 export function loadRules(root: string): Rules {
   const p = join(root, '_rules.yaml');
@@ -316,10 +350,41 @@ export function loadRules(root: string): Rules {
   validateRulesShape(merged, source);
 
   const rules = merged as unknown as Rules;
-  const topLevel = new Set(Object.keys(parsed));
 
-  // §18 "Delete a key = check turns off" — applied AFTER validation, so every
-  // absent check-key is flipped from its deep-merged default to its OFF state:
+  // §18 documents inline objects alongside inline/block arrays ("inline
+  // objects {min: 3, max: 120}") — `synonyms: {vehicle: [car, auto]}` is
+  // therefore valid config (QA-13 F2): normalize it to group form. Like the
+  // block-list syntax, a user list replaces the built-in groups.
+  if (isPlainObject(rules.redundancy.synonyms)) {
+    rules.redundancy.synonyms = Object.entries(rules.redundancy.synonyms).map(([head, rest]) => [
+      head,
+      ...(Array.isArray(rest) ? rest.map(String) : [String(rest)]),
+    ]);
+  }
+
+  const offRange = (): { min: null; max: null } => ({ min: null, max: null });
+  const has = (section: string, key: string): boolean => {
+    const s = parsed[section];
+    return isPlainObject(s) && key in s;
+  };
+  const listed = (section: string): boolean => isPlainObject(parsed[section]);
+  const complete = (section: string): boolean => {
+    const s = parsed[section];
+    return isPlainObject(s) && SECTION_KEYS[section].every(k => k in s);
+  };
+  const deleteMode = listed('structure') || Object.keys(SECTION_KEYS).some(complete);
+  // An omitted check-key is a deletion (→ OFF) in a template-shaped file; in a
+  // sparse override file only when its section is majority-covered.
+  const deleted = (section: string, key: string): boolean => {
+    if (has(section, key)) return false;
+    if (deleteMode) return true;
+    const s = parsed[section];
+    const covered = isPlainObject(s) ? SECTION_KEYS[section].filter(k => k in s).length : 0;
+    return covered * 2 >= SECTION_KEYS[section].length;
+  };
+
+  // §18 "Delete a key = check turns off" — every deleted check-key is flipped
+  // from its deep-merged default to its OFF state:
   //   boolean switch   → false   (single_child_collapse, empty_nodes, tbd_allowed,
   //                               shared_prefix_detection, back_pointers,
   //                               orphan_check, duplicate_home_check, redundancy.enabled;
@@ -329,152 +394,159 @@ export function loadRules(root: string): Rules {
   //                               word_frequency_threshold, phrase_overlap_threshold,
   //                               cross_file_threshold, warn_threshold, max_node_chars,
   //                               force_file_for, prefer)
-  //   parameters (NOT checks — keep defaults when deleted, §18 overrides only
-  //   what the file lists for these): mode, stopwords, synonyms,
-  //   estimate_chars_per_token, default_limit; token_budget.enabled is a
-  //   planning switch, not a check switch, so it too keeps its default.
-  // A FULL rules file (every key present) finds every key listed below and is
-  // returned byte-identical to the old deep-merge behavior; a MISSING file
-  // never reaches this pass (early return above).
-  const offRange = (): { min: null; max: null } => ({ min: null, max: null });
-  const has = (section: string, key: string): boolean => {
-    const s = parsed[section];
-    return isPlainObject(s) && key in s;
-  };
+  //   parameters (NOT checks — keep defaults when omitted): mode, stopwords,
+  //   synonyms, estimate_chars_per_token, default_limit; token_budget.enabled
+  //   is a planning switch, not a check switch. A file mirroring the full
+  //   default shape lists every key and is returned identical to the defaults.
 
   // structure: node_length / siblings / depth / single_child_collapse / empty_nodes
-  if (!topLevel.has('structure')) {
-    rules.structure = {
-      node_length: offRange(),
-      siblings: offRange(),
-      depth: offRange(),
-      single_child_collapse: false,
-      empty_nodes: false,
-    };
+  if (!listed('structure')) {
+    if (deleteMode) {
+      rules.structure = {
+        node_length: offRange(),
+        siblings: offRange(),
+        depth: offRange(),
+        single_child_collapse: false,
+        empty_nodes: false,
+      };
+    }
   } else {
-    if (!has('structure', 'node_length')) {
+    if (deleted('structure', 'node_length')) {
       rules.structure = { ...rules.structure, node_length: offRange() };
     }
-    if (!has('structure', 'siblings')) {
+    if (deleted('structure', 'siblings')) {
       rules.structure = { ...rules.structure, siblings: offRange() };
     }
-    if (!has('structure', 'depth')) {
+    if (deleted('structure', 'depth')) {
       rules.structure = { ...rules.structure, depth: offRange() };
     }
-    if (!has('structure', 'single_child_collapse')) {
+    if (deleted('structure', 'single_child_collapse')) {
       rules.structure = { ...rules.structure, single_child_collapse: false };
     }
-    if (!has('structure', 'empty_nodes')) {
+    if (deleted('structure', 'empty_nodes')) {
       rules.structure = { ...rules.structure, empty_nodes: false };
     }
   }
 
   // style: prefer / force_nested_above / force_sibling_below / shared_prefix_detection
-  if (!topLevel.has('style')) {
-    rules.style = {
-      prefer: null,
-      force_nested_above: null,
-      force_sibling_below: null,
-      shared_prefix_detection: false,
-    };
+  if (!listed('style')) {
+    if (deleteMode) {
+      rules.style = {
+        prefer: null,
+        force_nested_above: null,
+        force_sibling_below: null,
+        shared_prefix_detection: false,
+      };
+    }
   } else {
-    if (!has('style', 'prefer')) {
+    if (deleted('style', 'prefer')) {
       rules.style = { ...rules.style, prefer: null };
     }
-    if (!has('style', 'force_nested_above')) {
+    if (deleted('style', 'force_nested_above')) {
       rules.style = { ...rules.style, force_nested_above: null };
     }
-    if (!has('style', 'force_sibling_below')) {
+    if (deleted('style', 'force_sibling_below')) {
       rules.style = { ...rules.style, force_sibling_below: null };
     }
-    if (!has('style', 'shared_prefix_detection')) {
+    if (deleted('style', 'shared_prefix_detection')) {
       rules.style = { ...rules.style, shared_prefix_detection: false };
     }
   }
 
-  // content: tbd_allowed / max_tbd_per_file
-  if (!topLevel.has('content')) {
-    rules.content = { tbd_allowed: false, max_tbd_per_file: null };
+  // content: tbd_allowed / max_tbd_per_file — the §18 TBD policy, enforced
+  // per file by checkTbdPolicy (§18 knobs were inert: QA-13 F4).
+  if (!listed('content')) {
+    if (deleteMode) {
+      rules.content = { tbd_allowed: false, max_tbd_per_file: null };
+    }
   } else {
-    if (!has('content', 'tbd_allowed')) {
+    if (deleted('content', 'tbd_allowed')) {
       rules.content = { ...rules.content, tbd_allowed: false };
     }
-    if (!has('content', 'max_tbd_per_file')) {
+    if (deleted('content', 'max_tbd_per_file')) {
       rules.content = { ...rules.content, max_tbd_per_file: null };
     }
   }
 
   // references: back_pointers / max_hops / orphan_check / duplicate_home_check.
-  // `mode` is a parameter — keeps its default when deleted. max_hops deleted →
+  // `mode` is a parameter — keeps its default when omitted. max_hops deleted →
   // null → the deep-hop check is skipped entirely (§18 strict: deleted = off;
   // the old deleted → 1 (default) special case violated "delete = off").
-  if (!topLevel.has('references')) {
-    rules.references = {
-      mode: 'pointer',
-      back_pointers: false,
-      max_hops: null,
-      orphan_check: false,
-      duplicate_home_check: false,
-    };
+  if (!listed('references')) {
+    if (deleteMode) {
+      rules.references = {
+        mode: 'pointer',
+        back_pointers: false,
+        max_hops: null,
+        orphan_check: false,
+        duplicate_home_check: false,
+      };
+    }
   } else {
-    if (!has('references', 'back_pointers')) {
+    if (deleted('references', 'back_pointers')) {
       rules.references = { ...rules.references, back_pointers: false };
     }
-    if (!has('references', 'max_hops')) {
+    if (deleted('references', 'max_hops')) {
       rules.references = { ...rules.references, max_hops: null };
     }
-    if (!has('references', 'orphan_check')) {
+    if (deleted('references', 'orphan_check')) {
       rules.references = { ...rules.references, orphan_check: false };
     }
-    if (!has('references', 'duplicate_home_check')) {
+    if (deleted('references', 'duplicate_home_check')) {
       rules.references = { ...rules.references, duplicate_home_check: false };
     }
   }
 
   // redundancy: enabled / word_frequency_threshold / phrase_overlap_threshold /
   // cross_file_threshold. `stopwords`/`synonyms` are parameters (§13 inputs) —
-  // they keep their defaults when deleted so the remaining layers still
+  // they keep their defaults when omitted so the remaining layers still
   // normalize text exactly as documented.
-  if (!topLevel.has('redundancy')) {
-    rules.redundancy = {
-      ...rules.redundancy,
-      enabled: false,
-      word_frequency_threshold: null,
-      phrase_overlap_threshold: null,
-      cross_file_threshold: null,
-    };
+  if (!listed('redundancy')) {
+    if (deleteMode) {
+      rules.redundancy = {
+        ...rules.redundancy,
+        enabled: false,
+        word_frequency_threshold: null,
+        phrase_overlap_threshold: null,
+        cross_file_threshold: null,
+      };
+    }
   } else {
-    if (!has('redundancy', 'enabled')) {
+    if (deleted('redundancy', 'enabled')) {
       rules.redundancy = { ...rules.redundancy, enabled: false };
     }
-    if (!has('redundancy', 'word_frequency_threshold')) {
+    if (deleted('redundancy', 'word_frequency_threshold')) {
       rules.redundancy = { ...rules.redundancy, word_frequency_threshold: null };
     }
-    if (!has('redundancy', 'phrase_overlap_threshold')) {
+    if (deleted('redundancy', 'phrase_overlap_threshold')) {
       rules.redundancy = { ...rules.redundancy, phrase_overlap_threshold: null };
     }
-    if (!has('redundancy', 'cross_file_threshold')) {
+    if (deleted('redundancy', 'cross_file_threshold')) {
       rules.redundancy = { ...rules.redundancy, cross_file_threshold: null };
     }
   }
 
-  // token_budget: warn_threshold deleted → null → no usage warning. Planning
-  // parameters (enabled / default_limit / estimate_chars_per_token) keep their
-  // defaults when deleted — §18 budget planning must not change.
-  if (!topLevel.has('token_budget')) {
-    rules.token_budget = { ...rules.token_budget, warn_threshold: null };
-  } else if (!has('token_budget', 'warn_threshold')) {
+  // token_budget: warn_threshold omitted (deleted) → null → no usage warning.
+  // Planning parameters (enabled / default_limit / estimate_chars_per_token)
+  // keep their defaults — §18 budget planning must not change.
+  if (!listed('token_budget')) {
+    if (deleteMode) {
+      rules.token_budget = { ...rules.token_budget, warn_threshold: null };
+    }
+  } else if (deleted('token_budget', 'warn_threshold')) {
     rules.token_budget = { ...rules.token_budget, warn_threshold: null };
   }
 
   // overflow: max_node_chars / force_file_for — both are check keys.
-  if (!topLevel.has('overflow')) {
-    rules.overflow = { max_node_chars: null, force_file_for: null };
+  if (!listed('overflow')) {
+    if (deleteMode) {
+      rules.overflow = { max_node_chars: null, force_file_for: null };
+    }
   } else {
-    if (!has('overflow', 'max_node_chars')) {
+    if (deleted('overflow', 'max_node_chars')) {
       rules.overflow = { ...rules.overflow, max_node_chars: null };
     }
-    if (!has('overflow', 'force_file_for')) {
+    if (deleted('overflow', 'force_file_for')) {
       rules.overflow = { ...rules.overflow, force_file_for: null };
     }
   }

package/src/core/structure.ts

@@ -1,4 +1,5 @@
-import type { OutlineNode, Issue, StructureRules } from '../types';
+import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types';
+import { flattenNodes } from './outline';
 
 /** Structure checks: node length, depth, sibling count, single-child collapse, empty nodes.
  *  §18 delete-key semantics: a check whose rules key is null/false is OFF — the
@@ -84,3 +85,42 @@ export function checkStructure(
   walk(nodes);
   return issues;
 }
+
+/** §18 content rules — TBD policy per file (QA-13 F4: the knobs were inert).
+ *  `tbd_allowed: false` → any TBD node is flagged; otherwise `max_tbd_per_file`
+ *  caps the number of TBD nodes per file (deleted key → null → no cap). One
+ *  warning per file: §4 keeps TBDs first-class, so exceeding the policy is
+ *  advisory and never affects the exit code (§19). */
+export function checkTbdPolicy(
+  nodes: OutlineNode[],
+  file: string,
+  rules: ContentRules,
+): Issue[] {
+  const tbdNodes = flattenNodes(nodes).filter(n => /\bTBD\b/i.test(n.text));
+  if (tbdNodes.length === 0) return [];
+  if (!rules.tbd_allowed) {
+    return [
+      {
+        file,
+        line: tbdNodes[0]!.line,
+        level: 'warning',
+        category: 'structure',
+        message: 'TBD used but content.tbd_allowed is false',
+        suggestion: 'resolve the TBD nodes or set content.tbd_allowed: true',
+      },
+    ];
+  }
+  if (rules.max_tbd_per_file !== null && tbdNodes.length > rules.max_tbd_per_file) {
+    return [
+      {
+        file,
+        line: tbdNodes[0]!.line,
+        level: 'warning',
+        category: 'structure',
+        message: `${tbdNodes.length} TBD nodes exceed content.max_tbd_per_file (${rules.max_tbd_per_file})`,
+        suggestion: 'resolve the TBD nodes or raise content.max_tbd_per_file',
+      },
+    ];
+  }
+  return [];
+}