forgedock 1.1.1 → 1.1.3

package/packages/protocol/src/validate.js

@@ -0,0 +1,122 @@
+/**
+ * FORGE Annotation Protocol v1.0 — validator.
+ *
+ * validate(annotation) → { valid: boolean, errors: string[] }
+ *
+ * Checks:
+ *   - Completion sentinel presence (§3.2) — for types that define one
+ *   - Required field presence (§4.1 per-type field tables)
+ *   - Required field enum values (Verdict, Confidence, Severity, Task Type)
+ *   - Inline-value non-empty (§3.4)
+ *   - Partial sentinel marking (§3.3) — generates a warning, not an error
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES, SentinelState } from './types.js';
+
+/**
+ * Validate a parsed annotation against the spec.
+ *
+ * @param {import('./index.js').ParsedAnnotation} annotation
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+export function validate(annotation) {
+  if (!annotation || typeof annotation !== 'object') {
+    throw new TypeError('validate() expects a ParsedAnnotation object');
+  }
+
+  const errors = [];
+  const warnings = [];
+  const { type, sentinelState, inlineValue, fields, isReserved, isControl } = annotation;
+
+  // Unknown types: tolerate per §7.2.4 — no validation errors
+  if (!isReserved) {
+    return { valid: true, errors: [], warnings: [`Type "${type}" is not a reserved type; skipping field validation (§7.2.4)`] };
+  }
+
+  const typeDef = RESERVED_TYPES[type];
+
+  // Control markers: presence is the signal; no body or fields to validate
+  if (isControl) {
+    return { valid: true, errors: [], warnings: [] };
+  }
+
+  // Inline-value form (§3.4): value must be non-empty
+  if (typeDef.inlineValue) {
+    if (inlineValue === null || inlineValue === '') {
+      errors.push(`Inline-value annotation "${type}" must carry a non-empty value (§3.4)`);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+  }
+
+  // Completion sentinel check (§3.2): annotations with a defined sentinel must be complete.
+  // Both PARTIAL and INTERRUPTED states mean the annotation is not safely consumable.
+  if (typeDef.completionSentinel) {
+    if (sentinelState === SentinelState.PARTIAL) {
+      // Partial: producer was interrupted and marked it — consumer SHOULD request re-run (§3.3).
+      // Treat as invalid since consumers MUST NOT treat it as complete (§3.2).
+      errors.push(
+        `Annotation "${type}" is marked PARTIAL (${typeDef.partialSentinel ?? 'PARTIAL sentinel'}) — not safe to consume (§3.2/§3.3)`,
+      );
+      warnings.push(
+        `Annotation "${type}" is marked PARTIAL — consumer SHOULD request re-run (§3.3)`,
+      );
+    } else if (sentinelState === SentinelState.INTERRUPTED) {
+      errors.push(
+        `Annotation "${type}" is missing its completion sentinel "<!-- ${typeDef.completionSentinel} -->" (§3.2)`,
+      );
+    }
+  }
+
+  // Required field checks per type
+  for (const fieldName of typeDef.requiredFields) {
+    if (!(fieldName in fields) || fields[fieldName] === '') {
+      errors.push(`Required field "${fieldName}" is missing or empty in "${type}" annotation`);
+    }
+  }
+
+  // INVESTIGATOR-specific enum validation
+  if (type === 'INVESTIGATOR') {
+    if (fields['Verdict'] && !typeDef.verdictValues.includes(fields['Verdict'])) {
+      errors.push(
+        `Invalid Verdict "${fields['Verdict']}" — must be one of: ${typeDef.verdictValues.join(', ')}`,
+      );
+    }
+    if (fields['Confidence'] && !typeDef.confidenceValues.includes(fields['Confidence'])) {
+      errors.push(
+        `Invalid Confidence "${fields['Confidence']}" — must be one of: ${typeDef.confidenceValues.join(', ')}`,
+      );
+    }
+    if (fields['Severity'] && !typeDef.severityValues.includes(fields['Severity'])) {
+      errors.push(
+        `Invalid Severity "${fields['Severity']}" — must be one of: ${typeDef.severityValues.join(', ')}`,
+      );
+    }
+    if (fields['Task Type'] && !typeDef.taskTypeValues.includes(fields['Task Type'])) {
+      errors.push(
+        `Invalid Task Type "${fields['Task Type']}" — must be one of: ${typeDef.taskTypeValues.join(', ')}`,
+      );
+    }
+    // Decomposition Assessment must start with YES or NO
+    if (fields['Decomposition Assessment']) {
+      const da = fields['Decomposition Assessment'];
+      if (!/^(YES|NO)\b/.test(da)) {
+        errors.push(
+          `Decomposition Assessment must start with "YES" or "NO", got: "${da}"`,
+        );
+      }
+    }
+  }
+
+  // REVIEWER-specific enum validation
+  if (type === 'REVIEWER') {
+    if (fields['Verdict'] && !typeDef.verdictValues.includes(fields['Verdict'])) {
+      errors.push(
+        `Invalid Verdict "${fields['Verdict']}" — must be one of: ${typeDef.verdictValues.join(', ')}`,
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/scripts/bench-topology-cost.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * scripts/bench-topology-cost.mjs — end-to-end token-cost benchmark for pipeline topologies (#1279)
+ *
+ * Deterministic, zero-dependency aggregator for comparing per-issue token cost across
+ * ForgeDock pipeline topologies (e.g. "spawned" vs "inline-sequential").
+ *
+ * Measures the cost reduction claim from the agent topology refactor (#1254):
+ * eliminating 6-8 fresh-context establishments per standard run reduces token cost.
+ *
+ * Benchmark corpus: the 5 seeded issues in examples/forgedock-demo/
+ *   Issue 1 — Bug / security:  DELETE is missing an auth check
+ *   Issue 2 — Feature / security: Safe filtering for GET /notes
+ *   Issue 3 — Refactor: Extract the router module
+ *   Issue 4 — Performance: O(1) findById
+ *   Issue 5 — Docs: Add an API reference
+ *
+ * Input schema (runs.json):
+ * {
+ *   "runs": [
+ *     {
+ *       "topology": "spawned | inline-sequential",
+ *       "date": "ISO-8601",
+ *       "claude_model": "claude-sonnet-4-5 | ...",
+ *       "issues": [
+ *         {
+ *           "number": 1,
+ *           "title": "string",
+ *           "input_tokens": 12345,
+ *           "output_tokens": 2345,
+ *           "cache_read_tokens": 1000,
+ *           "cache_write_tokens": 500,
+ *           "quality_gate_passed": true
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ *
+ * Measurements can be populated from:
+ *   1. Session log parsing (when bin/runner.mjs emits usage metadata — see #1295)
+ *   2. Manual capture from Claude Code session summaries
+ *
+ * Usage:
+ *   node scripts/bench-topology-cost.mjs <runs.json>   # read file, print scorecard JSON
+ *   node scripts/bench-topology-cost.mjs -              # read runs JSON from stdin
+ *   cat runs.json | node scripts/bench-topology-cost.mjs  # (no arg) read from stdin
+ *
+ * Exit codes:
+ *   0 = scorecard emitted successfully
+ *   1 = invalid input (bad JSON, missing required fields, unknown topology)
+ *   2 = quality gate regression detected (scorecard still emitted to stdout)
+ */
+
+const CORPUS_ISSUES = [1, 2, 3, 4, 5];
+const KNOWN_TOPOLOGIES = new Set(["spawned", "inline-sequential"]);
+const TOKEN_FIELDS = ["input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens"];
+
+/**
+ * Total tokens billed for a single issue run.
+ * Cache reads are billed at a lower rate but still count against context budget.
+ * cache_write_tokens are not billed but indicate context establishment cost.
+ */
+export function totalTokens(issue) {
+  return (issue.input_tokens || 0) + (issue.output_tokens || 0);
+}
+
+/**
+ * Total context establishment cost: input + cache_write (fresh-context proxy).
+ * Reducing cache_write_tokens is the primary signal for the topology refactor —
+ * fewer spawned agents means fewer fresh context establishments.
+ */
+export function contextEstablishmentTokens(issue) {
+  return (issue.input_tokens || 0) + (issue.cache_write_tokens || 0);
+}
+
+/**
+ * Per-run aggregate: sum and per-issue breakdown.
+ */
+export function aggregateRun(run) {
+  const issues = run.issues || [];
+  const perIssue = issues.map((iss) => ({
+    number: iss.number,
+    title: iss.title || `Issue #${iss.number}`,
+    total_tokens: totalTokens(iss),
+    context_tokens: contextEstablishmentTokens(iss),
+    input_tokens: iss.input_tokens || 0,
+    output_tokens: iss.output_tokens || 0,
+    cache_read_tokens: iss.cache_read_tokens || 0,
+    cache_write_tokens: iss.cache_write_tokens || 0,
+    quality_gate_passed: iss.quality_gate_passed ?? null,
+  }));
+
+  const totals = perIssue.reduce(
+    (acc, iss) => {
+      acc.total_tokens += iss.total_tokens;
+      acc.context_tokens += iss.context_tokens;
+      acc.input_tokens += iss.input_tokens;
+      acc.output_tokens += iss.output_tokens;
+      acc.cache_read_tokens += iss.cache_read_tokens;
+      acc.cache_write_tokens += iss.cache_write_tokens;
+      return acc;
+    },
+    {
+      total_tokens: 0,
+      context_tokens: 0,
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_tokens: 0,
+      cache_write_tokens: 0,
+    },
+  );
+
+  const issueCount = perIssue.length;
+  const qualityGatePassed = perIssue.every((iss) => iss.quality_gate_passed !== false);
+  const qualityGateRegressions = perIssue.filter((iss) => iss.quality_gate_passed === false);
+
+  return {
+    topology: run.topology,
+    date: run.date || null,
+    claude_model: run.claude_model || null,
+    issue_count: issueCount,
+    per_issue: perIssue,
+    totals,
+    averages:
+      issueCount > 0
+        ? {
+            total_tokens: round(totals.total_tokens / issueCount),
+            context_tokens: round(totals.context_tokens / issueCount),
+            input_tokens: round(totals.input_tokens / issueCount),
+            output_tokens: round(totals.output_tokens / issueCount),
+            cache_read_tokens: round(totals.cache_read_tokens / issueCount),
+            cache_write_tokens: round(totals.cache_write_tokens / issueCount),
+          }
+        : null,
+    quality_gates: {
+      all_passed: qualityGatePassed,
+      regressions: qualityGateRegressions.map((iss) => iss.number),
+    },
+  };
+}
+
+/**
+ * Compute delta between two aggregated runs (topology comparison).
+ * Positive delta means `after` uses MORE tokens than `before` (regression).
+ * Negative delta means `after` uses FEWER tokens (improvement).
+ */
+export function computeDelta(before, after) {
+  if (!before || !after) return null;
+
+  const pct = (b, a) => (b === 0 ? null : round(((a - b) / b) * 100));
+
+  return {
+    total_tokens: {
+      before: before.totals.total_tokens,
+      after: after.totals.total_tokens,
+      delta: after.totals.total_tokens - before.totals.total_tokens,
+      delta_pct: pct(before.totals.total_tokens, after.totals.total_tokens),
+    },
+    context_tokens: {
+      before: before.totals.context_tokens,
+      after: after.totals.context_tokens,
+      delta: after.totals.context_tokens - before.totals.context_tokens,
+      delta_pct: pct(before.totals.context_tokens, after.totals.context_tokens),
+    },
+    cache_write_tokens: {
+      before: before.totals.cache_write_tokens,
+      after: after.totals.cache_write_tokens,
+      delta: after.totals.cache_write_tokens - before.totals.cache_write_tokens,
+      delta_pct: pct(before.totals.cache_write_tokens, after.totals.cache_write_tokens),
+    },
+    quality_gates_unchanged:
+      before.quality_gates.all_passed && after.quality_gates.all_passed,
+  };
+}
+
+/**
+ * Validate the runs file shape. Throws on any violation.
+ */
+export function validate(data) {
+  if (!data || typeof data !== "object") throw new Error("runs file must be a JSON object");
+  if (!Array.isArray(data.runs) || data.runs.length === 0) {
+    throw new Error("runs file must contain a non-empty `runs` array");
+  }
+
+  for (let i = 0; i < data.runs.length; i++) {
+    const run = data.runs[i];
+    if (!run.topology) {
+      throw new Error(`runs[${i}] must have a "topology" field`);
+    }
+    if (!KNOWN_TOPOLOGIES.has(run.topology)) {
+      throw new Error(
+        `runs[${i}].topology "${run.topology}" is unknown. Valid values: ${[...KNOWN_TOPOLOGIES].join(", ")}`,
+      );
+    }
+    if (!Array.isArray(run.issues) || run.issues.length === 0) {
+      throw new Error(`runs[${i}] (topology: ${run.topology}) must have a non-empty "issues" array`);
+    }
+    if (run.issues.length !== CORPUS_ISSUES.length) {
+      process.stderr.write(
+        `WARNING: runs[${i}] (topology: ${run.topology}) has ${run.issues.length} issue(s) ` +
+          `but the standard corpus is ${CORPUS_ISSUES.length} issues. ` +
+          `Partial runs produce non-comparable deltas.\n`,
+      );
+    }
+    for (let j = 0; j < run.issues.length; j++) {
+      const iss = run.issues[j];
+      if (typeof iss.number !== "number") {
+        throw new Error(`runs[${i}].issues[${j}] must have a numeric "number" field`);
+      }
+      for (const field of TOKEN_FIELDS) {
+        if (iss[field] !== undefined && typeof iss[field] !== "number") {
+          throw new Error(
+            `runs[${i}].issues[${j}].${field} must be a number (got ${typeof iss[field]})`,
+          );
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Aggregate all runs and produce the scorecard.
+ * Throws on validation failure.
+ */
+export function aggregate(data) {
+  validate(data);
+
+  const aggregated = data.runs.map(aggregateRun);
+
+  // Group by topology for comparison
+  const byTopology = {};
+  for (const run of aggregated) {
+    if (!byTopology[run.topology]) byTopology[run.topology] = [];
+    byTopology[run.topology].push(run);
+  }
+
+  // Pick the most recent run per topology for comparison
+  const latestByTopology = {};
+  for (const [topology, runs] of Object.entries(byTopology)) {
+    latestByTopology[topology] = runs[runs.length - 1];
+  }
+
+  // Compute delta: spawned (baseline) vs inline-sequential (after refactor)
+  const baseline = latestByTopology["spawned"] || null;
+  const refactored = latestByTopology["inline-sequential"] || null;
+  const delta = computeDelta(baseline, refactored);
+
+  // Quality gate regression check
+  const qualityRegressions = aggregated
+    .filter((r) => !r.quality_gates.all_passed)
+    .map((r) => ({ topology: r.topology, date: r.date, regressions: r.quality_gates.regressions }));
+
+  return {
+    corpus: {
+      description: "ForgeDock demo repo — 5 seeded issues (examples/forgedock-demo/)",
+      issue_numbers: CORPUS_ISSUES,
+    },
+    runs: aggregated,
+    topology_comparison: delta
+      ? {
+          baseline_topology: "spawned",
+          refactored_topology: "inline-sequential",
+          delta,
+          verdict:
+            delta.total_tokens.delta < 0
+              ? "IMPROVEMENT"
+              : delta.total_tokens.delta === 0
+                ? "NEUTRAL"
+                : "REGRESSION",
+          quality_gates_confirmed: delta.quality_gates_unchanged,
+        }
+      : null,
+    quality_gate_summary: {
+      all_runs_passed: qualityRegressions.length === 0,
+      regressions: qualityRegressions,
+    },
+  };
+}
+
+function round(x) {
+  return Math.round(x * 100) / 100;
+}
+
+async function readInput(arg) {
+  const { readFileSync } = await import("node:fs");
+  if (!arg || arg === "-") {
+    return readFileSync(0, "utf8"); // fd 0 = stdin
+  }
+  return readFileSync(arg, "utf8");
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      "Usage:",
+      "  node scripts/bench-topology-cost.mjs <runs.json>",
+      "  node scripts/bench-topology-cost.mjs -   (read from stdin)",
+      "",
+      "Input schema (runs.json):",
+      '  { "runs": [{ "topology": "spawned|inline-sequential", "date": "ISO-8601",',
+      '     "claude_model": "string", "issues": [{ "number": 1, "title": "string",',
+      '     "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0,',
+      '     "cache_write_tokens": 0, "quality_gate_passed": true }] }] }',
+      "",
+      "Benchmark corpus: examples/forgedock-demo/ issues #1–#5",
+      "Topologies measured: spawned (baseline) vs inline-sequential (refactored)",
+      "",
+      "Output: JSON scorecard to stdout",
+      "Exit 0 = OK, Exit 1 = invalid input, Exit 2 = quality gate regression",
+    ].join("\n") + "\n",
+  );
+}
+
+async function main() {
+  const arg = process.argv[2];
+
+  if (arg === "--help" || arg === "-h") {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!arg) {
+    // No argument and no piped input — print usage
+    const isTTY = process.stdin.isTTY;
+    if (isTTY) {
+      printUsage();
+      process.exit(0);
+    }
+  }
+
+  let raw;
+  try {
+    raw = await readInput(arg);
+  } catch (e) {
+    process.stderr.write(`ERROR: cannot read input: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`ERROR: invalid JSON: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  let scorecard;
+  try {
+    scorecard = aggregate(data);
+  } catch (e) {
+    process.stderr.write(`ERROR: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify(scorecard, null, 2) + "\n");
+
+  if (!scorecard.quality_gate_summary.all_runs_passed) {
+    const regressions = scorecard.quality_gate_summary.regressions;
+    process.stderr.write(
+      `WARNING: quality gate regressions detected in ${regressions.length} run(s). ` +
+        `Issues with failures: ${regressions.map((r) => `[${r.topology}] #${r.regressions.join(", #")}`).join("; ")}\n`,
+    );
+    process.exit(2);
+  }
+}
+
+// Run as CLI only when invoked directly, not when imported by tests.
+import { fileURLToPath } from "node:url";
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

package/scripts/check-command-docs-drift.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# check-command-docs-drift.sh
+#
+# Drift check: every installable command spec in commands/ must have a section
+# in docs/site/command-reference.md, and every command section in the reference
+# must have a corresponding spec file.
+#
+# "Installable" means: install: core (or no install: key) in YAML frontmatter.
+# Commands with install: internal or install: extras are excluded.
+#
+# Exit codes:
+#   0 — no drift
+#   1 — drift detected (missing docs or orphaned reference sections)
+#
+# Usage:
+#   bash scripts/check-command-docs-drift.sh [commands-dir] [reference-file]
+#
+# Defaults:
+#   commands-dir   = commands/
+#   reference-file = docs/site/command-reference.md
+
+set -euo pipefail
+
+# Normalise COMMANDS_DIR: strip trailing slash so path arithmetic is consistent
+# regardless of whether the caller passes "commands" or "commands/".
+COMMANDS_DIR="${1:-commands}"
+COMMANDS_DIR="${COMMANDS_DIR%/}"
+REFERENCE="${2:-docs/site/command-reference.md}"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# get_install_tier <file>
+# Reads the first `install:` key from YAML frontmatter. Echoes: core | extras | internal
+get_install_tier() {
+  local file="$1"
+  # Read up to 20 lines looking for frontmatter and the install key.
+  local in_fm=0
+  local line_no=0
+  while IFS= read -r line; do
+    line_no=$(( line_no + 1 ))
+    if [ $line_no -eq 1 ]; then
+      if [[ "$line" == "---"* ]]; then in_fm=1; continue; fi
+      # No frontmatter — default to core
+      echo "core"; return
+    fi
+    if [ $in_fm -eq 1 ]; then
+      if [[ "$line" == "---"* ]]; then
+        # End of frontmatter — key not found, default to core
+        echo "core"; return
+      fi
+      if [[ "$line" =~ ^install:[[:space:]]*(.*) ]]; then
+        local val="${BASH_REMATCH[1]}"
+        # Strip surrounding quotes
+        val="${val#\"}" ; val="${val%\"}"
+        val="${val#\'}" ; val="${val%\'}"
+        val="${val// /}"  # trim spaces
+        case "$val" in
+          internal|extras) echo "$val"; return ;;
+          core)            echo "core"; return ;;
+          *)               echo "core"; return ;;
+        esac
+      fi
+    fi
+  done < <(head -25 "$file")
+  echo "core"
+}
+
+# ---------------------------------------------------------------------------
+# 1. Collect installable command names from commands/
+# ---------------------------------------------------------------------------
+
+declare -a INSTALLABLE_COMMANDS=()
+
+while IFS= read -r -d '' spec; do
+  tier="$(get_install_tier "$spec")"
+  if [[ "$tier" == "core" ]]; then
+    # Derive command name from path relative to COMMANDS_DIR.
+    # e.g. commands/work-on.md           → /work-on
+    #      commands/work-on/build.md      → /work-on/build
+    #      commands/work-on/build/impl.md → /work-on/build/impl
+    rel="${spec#${COMMANDS_DIR}/}"
+    cmd="/${rel%.md}"
+    INSTALLABLE_COMMANDS+=("$cmd")
+  fi
+done < <(find "$COMMANDS_DIR" -name '*.md' -print0 | sort -z)
+
+# ---------------------------------------------------------------------------
+# 2. Extract documented command names from command-reference.md
+# ---------------------------------------------------------------------------
+# We look for lines of the form: ### `/some-command`
+# The reference uses backtick-wrapped command names under H3 headings.
+
+declare -a DOCUMENTED_COMMANDS=()
+
+while IFS= read -r line; do
+  # Match H3 heading: ### `/command-name` or ### `/command/sub`
+  if [[ "$line" =~ ^###[[:space:]]+\`(/[a-zA-Z0-9_/-]+)\` ]]; then
+    cmd="${BASH_REMATCH[1]}"
+    DOCUMENTED_COMMANDS+=("$cmd")
+  # Match table cell containing a bare command path: | `/command-name` | ...
+  # This covers the Sub-Phase Commands table which lists commands without H3 headings.
+  # We require the line to look like a markdown table row (starts with |) to avoid
+  # matching inline code examples in prose or fix-instruction blocks.
+  elif [[ "$line" =~ ^\| ]]; then
+    # Extract all backtick-wrapped tokens that look like command paths
+    while [[ "$line" =~ \`(/[a-zA-Z0-9_/-]+)\` ]]; do
+      cmd="${BASH_REMATCH[1]}"
+      DOCUMENTED_COMMANDS+=("$cmd")
+      # Remove the matched portion so the loop can find multiple tokens per line
+      line="${line#*\`${cmd}\`}"
+    done
+  fi
+done < "$REFERENCE"
+
+# Deduplicate DOCUMENTED_COMMANDS (table rows may repeat H3-listed commands)
+declare -a _DEDUPED=()
+declare -A _SEEN=()
+for cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+  if [[ -z "${_SEEN[$cmd]+x}" ]]; then
+    _DEDUPED+=("$cmd")
+    _SEEN[$cmd]=1
+  fi
+done
+DOCUMENTED_COMMANDS=("${_DEDUPED[@]}")
+
+# ---------------------------------------------------------------------------
+# 3. Compare
+# ---------------------------------------------------------------------------
+
+FAIL=0
+
+echo "=== ForgeDock command docs drift check ==="
+echo ""
+echo "Installable specs  : ${#INSTALLABLE_COMMANDS[@]}"
+echo "Documented commands: ${#DOCUMENTED_COMMANDS[@]}"
+echo ""
+
+# 3a. Installable commands missing from the reference
+echo "--- Installable commands not documented in command-reference.md ---"
+MISSING_DOCS=0
+for cmd in "${INSTALLABLE_COMMANDS[@]}"; do
+  found=0
+  for doc_cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+    if [[ "$doc_cmd" == "$cmd" ]]; then
+      found=1
+      break
+    fi
+  done
+  if [[ $found -eq 0 ]]; then
+    echo "  MISSING DOC: $cmd"
+    MISSING_DOCS=$(( MISSING_DOCS + 1 ))
+    FAIL=1
+  fi
+done
+if [[ $MISSING_DOCS -eq 0 ]]; then
+  echo "  OK — all installable commands are documented"
+fi
+echo ""
+
+# 3b. Reference sections whose spec no longer exists (orphaned docs)
+echo "--- Reference sections with no matching installable spec ---"
+ORPHANED=0
+for doc_cmd in "${DOCUMENTED_COMMANDS[@]}"; do
+  found=0
+  for cmd in "${INSTALLABLE_COMMANDS[@]}"; do
+    if [[ "$cmd" == "$doc_cmd" ]]; then
+      found=1
+      break
+    fi
+  done
+  if [[ $found -eq 0 ]]; then
+    echo "  ORPHANED REF: $doc_cmd  (no matching installable spec)"
+    ORPHANED=$(( ORPHANED + 1 ))
+    FAIL=1
+  fi
+done
+if [[ $ORPHANED -eq 0 ]]; then
+  echo "  OK — all reference sections have a matching spec"
+fi
+echo ""
+
+# ---------------------------------------------------------------------------
+# 4. Result
+# ---------------------------------------------------------------------------
+
+if [[ $FAIL -eq 1 ]]; then
+  echo "FAIL: command/docs drift detected."
+  echo ""
+  echo "Fix:"
+  echo "  - MISSING DOC  → add a section for the command to docs/site/command-reference.md"
+  echo "  - ORPHANED REF → remove the section or restore the spec under commands/"
+  exit 1
+else
+  echo "OK: no drift between commands/ and docs/site/command-reference.md"
+  exit 0
+fi