cans-spec 0.2.0 → 0.5.0

package/src/core/structure.ts

@@ -1,7 +1,10 @@
 import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types.ts';
-import { flattenNodes } from './outline.ts';
+import { flattenNodes, isSyntheticNode } from './outline.ts';
 
 /** Structure checks: node length, depth, sibling count, single-child collapse, empty nodes.
+ *  Both sides of every range are enforced (issue #1 — siblings.min and depth.min
+ *  were banner-checked but never enforced): node_length, siblings and depth each
+ *  check their `min` (warning) as well as their `max`.
  *  §18 delete-key semantics: a check whose rules key is null/false is OFF — the
  *  check is skipped entirely (never compared against null, which would coerce
  *  to 0 and flag everything). */
@@ -14,75 +17,135 @@ export function checkStructure(
 
   const walk = (list: OutlineNode[]): void => {
     for (const node of list) {
-      const len = node.text.length;
-      const nl = rules.node_length;
-      if (nl !== null && nl.max !== null && len > nl.max) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'error',
-          category: 'structure',
-          message: `Node too long (${len} > ${nl.max}). Split or move to file.`,
-        });
-      } else if (nl !== null && nl.min !== null && len < nl.min) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `Node too short (${len} < ${nl.min}).`,
-        });
-      }
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not user
+      // structure — never flagged themselves (their children, if any, still
+      // are: the walk recurses below regardless).
+      if (!isSyntheticNode(node)) {
+        const len = node.text.length;
+        const nl = rules.node_length;
+        if (nl !== null && nl.max !== null && len > nl.max) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'error',
+            category: 'structure',
+            message: `Node too long (${len} > ${nl.max}). Split or move to file.`,
+          rule: 'structure.node_length.max', // issue #41: machine-readable rule key
+          });
+        } else if (nl !== null && nl.min !== null && len < nl.min) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `Node too short (${len} < ${nl.min}).`,
+          rule: 'structure.node_length.min', // issue #41: machine-readable rule key
+          });
+        }
 
-      const depth = node.indent + 1;
-      const depthMax = rules.depth !== null ? rules.depth.max : null;
-      if (depthMax !== null && depth > depthMax) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'error',
-          category: 'structure',
-          message: `Depth ${depth} exceeds max ${depthMax}. Flatten.`,
-        });
-      }
+        const depth = node.indent + 1;
+        const depthMax = rules.depth !== null ? rules.depth.max : null;
+        if (depthMax !== null && depth > depthMax) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'error',
+            category: 'structure',
+            message: `Depth ${depth} exceeds max ${depthMax}. Flatten.`,
+          rule: 'structure.depth.max', // issue #41: machine-readable rule key
+          });
+        }
 
-      const count = node.children.length;
-      const siblingsMax = rules.siblings !== null ? rules.siblings.max : null;
-      if (siblingsMax !== null && count > siblingsMax) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `"${node.text}" has ${count} children (max ${siblingsMax}).`,
-        });
-      }
+        const count = node.children.length;
+        const siblingsMax = rules.siblings !== null ? rules.siblings.max : null;
+        if (siblingsMax !== null && count > siblingsMax) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has ${count} children (max ${siblingsMax}).`,
+          rule: 'structure.siblings.max', // issue #41: machine-readable rule key
+          });
+        }
+        // Issue #1: enforce siblings.min — a parent with 0 < count < min children
+        // is under the configured fan-out. Warning level, consistent with the
+        // siblings.max side above. The single_child_collapse advisory below is a
+        // separate check and may fire for the same node — that is acceptable.
+        const siblingsMin = rules.siblings !== null ? rules.siblings.min : null;
+        if (siblingsMin !== null && count > 0 && count < siblingsMin) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has ${count} children (min ${siblingsMin}).`,
+          rule: 'structure.siblings.min', // issue #41: machine-readable rule key
+          });
+        }
 
-      if (rules.single_child_collapse && count === 1) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `"${node.text}" has exactly 1 child. Collapse.`,
-        });
+        if (rules.single_child_collapse && count === 1) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has exactly 1 child. Collapse.`,
+          rule: 'structure.single_child', // issue #41: machine-readable rule key
+          });
+        }
+
+        if (rules.empty_nodes && node.text.trim() === '') {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: 'Empty node.',
+          rule: 'structure.empty_node', // issue #41: machine-readable rule key
+          });
+        }
       }
 
-      if (rules.empty_nodes && node.text.trim() === '') {
+      walk(node.children);
+    }
+  };
+
+  walk(nodes);
+
+  // Issue #1: enforce depth.min at file level — a file whose deepest node is
+  // above the configured minimum is under-specified. Attached to the first
+  // root node's line (there is always at least one node when the file has
+  // nodes); an empty tree skips the check entirely.
+  // LEVEL RATIONALE: depth.min is a warning — a too-shallow file is advisory
+  // (depth.max stays an error because it protects the token budget; making
+  // shallow files hard-fail would break legitimately shallow summary files).
+  // siblings.min is a warning for the same reason: it matches the warning
+  // level of the siblings.max side. Defaults (min: 1 both) can never fire —
+  // `0 < count < 1` is impossible and any non-empty file has max depth ≥ 1 —
+  // so default-rule workspaces stay clean.
+  if (nodes.length > 0) {
+    const depthMin = rules.depth !== null ? rules.depth.min : null;
+    if (depthMin !== null) {
+      let maxNodeDepth = 0;
+      for (const n of flattenNodes(nodes)) {
+        const d = n.indent + 1; // same convention as the per-node depth check above
+        if (d > maxNodeDepth) maxNodeDepth = d;
+      }
+      if (maxNodeDepth < depthMin) {
         issues.push({
           file,
-          line: node.line,
+          line: nodes[0]!.line,
           level: 'warning',
           category: 'structure',
-          message: 'Empty node.',
+          message: `Max depth ${maxNodeDepth} is below min ${depthMin}. Deepen the outline.`,
+          suggestion: `add nested sub-levels until the outline reaches depth ${depthMin}, or lower structure.depth.min in _rules.yaml`,
+          rule: 'structure.depth.min', // issue #41: machine-readable rule key
         });
       }
-
-      walk(node.children);
     }
-  };
+  }
 
-  walk(nodes);
   return issues;
 }
 
@@ -106,6 +169,7 @@ export function checkTbdPolicy(
         level: 'warning',
         category: 'structure',
         message: 'TBD used but content.tbd_allowed is false',
+          rule: 'content.tbd.disallowed', // issue #41: machine-readable rule key
         suggestion: 'resolve the TBD nodes or set content.tbd_allowed: true',
       },
     ];
@@ -118,6 +182,7 @@ export function checkTbdPolicy(
         level: 'warning',
         category: 'structure',
         message: `${tbdNodes.length} TBD nodes exceed content.max_tbd_per_file (${rules.max_tbd_per_file})`,
+          rule: 'content.tbd.max', // issue #41: machine-readable rule key
         suggestion: 'resolve the TBD nodes or raise content.max_tbd_per_file',
       },
     ];

package/src/core/style.ts

@@ -1,6 +1,23 @@
 import type { OutlineNode, Issue, StyleRules } from '../types.ts';
+import { isSyntheticNode } from './outline.ts';
 
-/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint.
+/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint,
+ *  modulated by `style.prefer` (issue #2 — the key was parsed and reconciled but
+ *  never read, so `prefer: nested` still advised "Collapse to sibling style.").
+ *
+ *  Prefer semantics:
+ *    - `prefer: 'sibling'` — the author prefers flat sibling lists: the
+ *      shared-prefix "Group under nested style." hint is suppressed (it argues
+ *      against the declared preference); the collapse-to-sibling hint still
+ *      fires (it agrees with it).
+ *    - `prefer: 'nested'` — the author prefers grouped outlines: the
+ *      "Collapse to sibling style." hint is suppressed; the shared-prefix
+ *      grouping hint still fires.
+ *    - `prefer: null` (key deleted, §18) — NO prefer-driven modulation: both
+ *      base hints fire exactly as they did before the prefer wiring existed.
+ *      "Deleted `prefer` disables prefer-driven style guidance" therefore means
+ *      the prefer-driven MODULATION is off, not that the base guidance is off.
+ *
  *  SEVERITY NOTE (arbitration, same class as the refs-severity decision): §14/§36
  *  show ✗ for style flags, but the frozen §35/§18 fixtures (flat-project,
  *  folder-project, init templates) structurally trigger the ≤N-leaf rule and the
@@ -8,8 +25,9 @@ import type { OutlineNode, Issue, StyleRules } from '../types.ts';
  *  findings stay `warning`-level. Changing test fixtures is out of bounds
  *  (test/ is frozen).
  *  §18 delete-key semantics: a style rule whose key is null/false no longer
- *  fires (deleted force_nested_above / force_sibling_below / prefer or
- *  shared_prefix_detection: false skip their rules entirely). */
+ *  fires — deleted force_nested_above / force_sibling_below or
+ *  shared_prefix_detection: false skip their rules entirely (deleted `prefer`
+ *  is the modulation-off case documented above; it skips nothing). */
 export function checkStyle(
   nodes: OutlineNode[],
   file: string,
@@ -21,49 +39,66 @@ export function checkStyle(
     for (const node of list) {
       const children = node.children;
 
-      const nestedAbove = rules.force_nested_above;
-      if (rules.shared_prefix_detection && nestedAbove !== null && children.length >= nestedAbove) {
-        const groups = new Map<string, number>();
-        for (const child of children) {
-          const word = child.text.split(/\s+/)[0] ?? '';
-          if (word === '') continue;
-          groups.set(word, (groups.get(word) ?? 0) + 1);
-        }
-        for (const [word, size] of groups) {
-          if (size >= nestedAbove) {
-            issues.push({
-              file,
-              line: node.line,
-              level: 'warning',
-              category: 'style',
-              message: `${size} siblings share prefix "${word}". Group under nested style.`,
-            });
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not user
+      // structure — never flagged themselves (their children, if any, still
+      // are: the walk recurses below regardless).
+      if (!isSyntheticNode(node)) {
+        const nestedAbove = rules.force_nested_above;
+        // prefer: 'sibling' declares a flat-list preference — the grouping hint
+        // contradicts it and is suppressed ('nested'/null keep it firing).
+        if (
+          rules.shared_prefix_detection &&
+          rules.prefer !== 'sibling' &&
+          nestedAbove !== null &&
+          children.length >= nestedAbove
+        ) {
+          const groups = new Map<string, number>();
+          for (const child of children) {
+            const word = child.text.split(/\s+/)[0] ?? '';
+            if (word === '') continue;
+            groups.set(word, (groups.get(word) ?? 0) + 1);
+          }
+          for (const [word, size] of groups) {
+            if (size >= nestedAbove) {
+              issues.push({
+                file,
+                line: node.line,
+                level: 'warning',
+                category: 'style',
+                message: `${size} siblings share prefix "${word}". Group under nested style.`,
+          rule: 'style.prefix.shared', // issue #41: machine-readable rule key
+              });
+            }
           }
         }
-      }
 
-      // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
-      // sibling style." `≤` semantics (exactly N is flagged). The file root is
-      // exempt — a root concept with few subtopics is the normal spec shape,
-      // not unnecessary nesting. A single child is reported by the structure
-      // engine ("exactly 1 child"); don't double-report it here.
-      const siblingBelow = rules.force_sibling_below;
-      if (
-        siblingBelow !== null &&
-        node.indent > 0 &&
-        children.length >= 2 &&
-        children.length <= siblingBelow &&
-        children.every((c) => c.children.length === 0)
-      ) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'style',
-          // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
-          // above plus the structure engine owns the 1-child case).
-          message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
-        });
+        // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
+        // sibling style." `≤` semantics (exactly N is flagged). The file root is
+        // exempt — a root concept with few subtopics is the normal spec shape,
+        // not unnecessary nesting. A single child is reported by the structure
+        // engine ("exactly 1 child"); don't double-report it here.
+        const siblingBelow = rules.force_sibling_below;
+        // prefer: 'nested' declares a grouped-outline preference — the collapse
+        // hint contradicts it and is suppressed ('sibling'/null keep it firing).
+        if (
+          siblingBelow !== null &&
+          rules.prefer !== 'nested' &&
+          node.indent > 0 &&
+          children.length >= 2 &&
+          children.length <= siblingBelow &&
+          children.every((c) => c.children.length === 0)
+        ) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'style',
+            // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
+            // above plus the structure engine owns the 1-child case).
+            message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
+          rule: 'style.nesting.prefer', // issue #41: machine-readable rule key
+          });
+        }
       }
 
       walk(children);

package/src/core/token-budget.ts

@@ -4,7 +4,7 @@ import type {
   OutlineNode, BackPointer, TokenBudgetRules,
   BudgetReadPlanItem, BudgetReadResult, BudgetWriteResult,
 } from '../types.ts';
-import { flattenNodes, parseOutline } from './outline.ts';
+import { flattenNodes, parseOutline, isSyntheticNode } from './outline.ts';
 import { targetMatchesKey } from './refs.ts';
 
 export function estimateTokens(text: string, charsPerToken: number): number {
@@ -19,7 +19,10 @@ function relPath(file: string): string {
 }
 
 function serializedNodeText(nodes: OutlineNode[]): string {
-  return flattenNodes(nodes).map(n => n.text).join('\n');
+  // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not content —
+  // including them inflated every token estimate for files opening with a
+  // table/fence.
+  return flattenNodes(nodes).filter(n => !isSyntheticNode(n)).map(n => n.text).join('\n');
 }
 
 /** Token estimate for a workspace key (loaded nodes) or a raw file path (content read). */
@@ -53,6 +56,8 @@ export function findCanonicalHome(
   const candidates: Array<{ file: string; node: OutlineNode }> = [];
   for (const [file, nodes] of allFiles) {
     for (const node of flattenNodes(nodes)) {
+      // Issue #8: a synthetic placeholder must never be the canonical home.
+      if (isSyntheticNode(node)) continue;
       if (node.text.toLowerCase().includes(lc)) candidates.push({ file, node });
     }
   }
@@ -103,9 +108,22 @@ export function buildReadPlan(
   }
 
   const backRefFiles = new Set<string>();
+  // §26 step 3 forward-ref tier (QA-17 F28): the files the canonical home
+  // POINTS TO — targets of see: refs made from the home file — connect at 40.
+  // (Back-refs, the files that point AT the home, stay 60; a file that is
+  // both keeps the higher tier.)
+  const forwardFiles = new Set<string>();
   if (home !== null) {
     for (const bp of backPointers) {
       if (targetMatchesKey(bp.toFile, home.file)) backRefFiles.add(bp.fromFile);
+      if (bp.fromFile === home.file) {
+        for (const key of allFiles.keys()) {
+          if (targetMatchesKey(bp.toFile, key)) {
+            forwardFiles.add(key);
+            break;
+          }
+        }
+      }
     }
   }
   for (const key of allFiles.keys()) {
@@ -114,6 +132,10 @@ export function buildReadPlan(
       items.set(key, { file: key, anchor: null, reason: 'see: back-ref', score: 60, estTokens: tokens(key), rank: 2 });
       continue;
     }
+    if (forwardFiles.has(key)) {
+      items.set(key, { file: key, anchor: null, reason: 'forward ref', score: 40, estTokens: tokens(key), rank: 3 });
+      continue;
+    }
     const mentions = flattenNodes(allFiles.get(key)!).some(n => n.text.toLowerCase().includes(lc));
     if (mentions) {
       items.set(key, { file: key, anchor: null, reason: 'mentions concept', score: 20, estTokens: tokens(key), rank: 3 });
@@ -177,10 +199,14 @@ export function buildReadPlan(
   const plan: BudgetReadPlanItem[] = [];
   const skipped: string[] = [];
   let totalTokens = 0;
-  let cut = false;
+  // §26 step 4 (issue #16): best-effort greedy packing. Items are walked in
+  // score order and each item that fits under the remaining budget is
+  // planned. An item that does not fit is skipped (listed in `skipped`) but
+  // does NOT cut the walk — cheaper lower-scored items that still fit are
+  // considered, so a limit below the canonical home (score 100) can still
+  // afford a cheaper back-ref (score 60) instead of yielding plan: [].
   for (const item of sorted) {
-    if (cut || totalTokens + item.estTokens > budgetLimit) {
-      cut = true;
+    if (totalTokens + item.estTokens > budgetLimit) {
       skipped.push(item.file);
       continue;
     }
@@ -193,6 +219,16 @@ export function buildReadPlan(
   for (const key of allFiles.keys()) {
     if (!items.has(key)) skipped.push(key);
   }
+  // §26 step 4 (QA-17 F25): skipped lists EVERY file not in the plan — active
+  // task files are in budget scope (§22), so a task file with no connection
+  // to the concept (never scored into `items`) is listed too, never
+  // invisible. Planned-but-unaffordable task files already landed in skipped
+  // via the packing loop above.
+  if (activeTaskPaths !== undefined) {
+    for (const taskPath of activeTaskPaths) {
+      if (!items.has(taskPath)) skipped.push(taskPath);
+    }
+  }
   skipped.sort();
 
   const usagePercent = budgetLimit > 0

package/src/types.ts

@@ -20,12 +20,25 @@ export interface OutlineNode {
   refs: RefTarget[];
   hasCodeFence: boolean;
   hasTable: boolean;
+  /** Issue #8: true ONLY for parser-created placeholder nodes (text "(table)"
+   *  or "(code fence)") that represent a table/fence appearing BEFORE the
+   *  first bullet of a file. They carry the hasTable/hasCodeFence signal but
+   *  are not user content — consumers that count nodes or compare node text
+   *  as content must exclude them (isSyntheticNode). Never set on nodes
+   *  parsed from real bullets. */
+  synthetic?: boolean;
 }
 
 export interface BackPointer {
   fromFile: string;
   fromLine: number;
   toFile: string;
+  /** The anchor side of the back-pointer. For graph-built back-pointers
+   *  (buildRefGraph): the ref's raw anchor token, null for file-level refs.
+   *  For extracted `<!-- ref-by: ... -->` comments (extractBackPointers,
+   *  issue #19): the text of the node whose bullet line carries the comment
+   *  (INLINE form — a node mark), or null when the comment stands on its own
+   *  line (STANDALONE form — a file-level mark). */
   toAnchor: string | null;
 }
 
@@ -41,6 +54,10 @@ export interface Issue {
   category: IssueCategory;
   message: string;
   suggestion?: string;
+  /** issue #41: machine-readable dotted rule key (e.g. "refs.broken.file",
+   *  "structure.node_length.max") — stable vocabulary for report grouping and
+   *  agent consumption. Optional so non-engine Issue constructors stay legal. */
+  rule?: string;
 }
 
 // ── Rules ──
@@ -63,7 +80,9 @@ export interface StructureRules {
 }
 
 export interface StyleRules {
-  /** Deleted `prefer` disables prefer-driven style guidance (§18). */
+  /** Style-guide selector: `sibling` suppresses the nested-grouping hint,
+   *  `nested` suppresses the sibling-collapse hint; null (deleted, §18) → no
+   *  prefer-driven modulation — both base style hints fire unchanged. */
   prefer: 'sibling' | 'nested' | null;
   force_nested_above: number | null;
   force_sibling_below: number | null;
@@ -90,6 +109,8 @@ export interface RedundancyRules {
   word_frequency_threshold: number | null;
   phrase_overlap_threshold: number | null;
   cross_file_threshold: number | null;
+  /** Layer 3 switch: deleted → false (§18 delete-key semantics). */
+  fuzzy: boolean;
   /** Parameters (not checks): keep their defaults when deleted (§18). */
   stopwords: string[];
   synonyms: string[][];
@@ -149,6 +170,13 @@ export interface CheckResult extends CommandResult {
   errorCount: number;
   warningCount: number;
   backPointersUpdated: number;
+  /** Issue #11: spec-relative paths of the files --fix actually rewrote
+   *  (sorted). Empty without --fix or when nothing needed a write; with a
+   *  [file] filter only matching files can ever appear here. */
+  backPointersUpdatedFiles: string[];
+  /** issue #41: wall-clock duration of the whole checkWorkspace run,
+   *  rounded to whole ms (0 for the static checkFail paths). */
+  elapsedMs: number;
   /** §22/§36: human-facing one-line summary of the active _rules.yaml limits (QA-02 F17). */
   rulesSummary?: string;
 }

package/templates/_rules.yaml

@@ -27,6 +27,7 @@ redundancy:
   word_frequency_threshold: 4
   phrase_overlap_threshold: 0.7
   cross_file_threshold: 2
+  fuzzy: true
   stopwords: [the, a, an, of, to, in, for, and, or, with, must, shall, requires]
   synonyms:
     - [postgres, postgresql, pg]