@bigknoxy/hashpilot 4.6.3

package/scripts/install.sh

@@ -0,0 +1,466 @@
+#!/bin/bash
+set -euo pipefail
+
+# shellcheck disable=SC2034
+BOLD='\033[1m'
+DIM='\033[2m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+log()  { printf "${GREEN}[hashpilot]${NC} %s\n" "$1"; }
+warn() { printf "${YELLOW}[hashpilot]${NC} %s\n" "$1"; }
+err()  { printf "${RED}[hashpilot]${NC} %s\n" "$1"; }
+detail() { printf "${DIM}  →${NC} %s\n" "$1"; }
+
+# ── Detect source directory ──────────────────────────────────────────────
+REMOTE_MODE=false
+SOURCE_DIR=""
+
+# Try to resolve from script location (local clone mode)
+if SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd 2>/dev/null)"; then
+  REPO_ROOT="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd 2>/dev/null || echo "")"
+  if [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/package.json" ]; then
+    SOURCE_DIR="$REPO_ROOT"
+  fi
+fi
+
+# No local source — download release tarball from GitHub (curl-pipe / remote mode)
+if [ -z "$SOURCE_DIR" ]; then
+  REMOTE_MODE=true
+  CLONE_DIR=$(mktemp -d)
+  
+  # Determine version to download (latest release)
+  log "Fetching latest release info from GitHub..."
+  RELEASE_INFO=$(curl -fsSL "https://api.github.com/repos/bigknoxy/HashPilot/releases/latest" 2>/dev/null || echo "")
+  TAG_NAME=$(echo "$RELEASE_INFO" | grep '"tag_name"' | head -1 | sed 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)
+  if [ -n "$TAG_NAME" ]; then
+    TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/tags/${TAG_NAME}.tar.gz"
+    log "Downloading HashPilot ${TAG_NAME} from GitHub..."
+  else
+    # Fallback to main branch if no release
+    TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/heads/main.tar.gz"
+    log "Downloading HashPilot from main branch..."
+  fi
+  
+  curl -fsSL "$TARBALL_URL" | tar -xz -C "$CLONE_DIR" --strip-components=1 2>&1 | while IFS= read -r line; do detail "$line"; done
+  SOURCE_DIR="$CLONE_DIR"
+  detail "Extracted to $CLONE_DIR"
+fi
+
+# Read the version from package.json so the installer can never drift from the
+# released version. Falls back to "unknown" rather than a stale literal. Read
+# only now that SOURCE_DIR is resolved, so this works in both local-clone mode
+# and remote (curl-pipe) mode, where $0 doesn't point at the source tree.
+HASHPILOT_VERSION="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SOURCE_DIR/package.json" 2>/dev/null | head -1)"
+HASHPILOT_VERSION="${HASHPILOT_VERSION:-unknown}"
+
+# ── Parse arguments ──────────────────────────────────────────────────────
+TARGET_DIR="${HOME}/.agentic-tools"
+KEEP_TELEMETRY=false
+FORCE=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --source) SOURCE_DIR="$2"; shift 2 ;;
+    --target) TARGET_DIR="$2"; shift 2 ;;
+    --keep-telemetry) KEEP_TELEMETRY=true; shift ;;
+    --force|-f) FORCE=true; shift ;;
+    --help|-h)
+      echo "HashPilot Installer v${HASHPILOT_VERSION}"
+      echo "Usage: $0 [options]"
+      echo "  --source <dir>     Source directory (default: repo root)."
+      echo "                     If omitted and no local source found,"
+      echo "                     auto-downloads release tarball from GitHub."
+      echo "  --target <dir>     Install target (default: ~/.agentic-tools)"
+      echo "  --keep-telemetry   Preserve existing telemetry on reinstall"
+      echo '  --force, -f        Overwrite existing install without any prompt (including the non-interactive existing-install notice)'
+      echo "  --help, -h         Show this help"
+      echo ""
+      echo "One-liner: curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash"
+      exit 0
+      ;;
+    *) err "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# ── Prerequisites ────────────────────────────────────────────────────────
+log "Checking prerequisites..."
+
+# Auto-install bun if not present
+if ! command -v bun &>/dev/null; then
+  warn "bun not found. Installing bun..."
+  curl -fsSL https://bun.sh/install | bash
+  # Source the new PATH
+  export BUN_INSTALL="${HOME}/.bun"
+  export PATH="${BUN_INSTALL}/bin:${PATH}"
+fi
+
+BUN_VER=$(bun --version 2>/dev/null || echo "0")
+detail "bun ${BUN_VER}"
+
+if ! command -v bash &>/dev/null; then
+  err "bash is required"
+  exit 1
+fi
+
+if [ "$REMOTE_MODE" = "true" ] && ! command -v curl &>/dev/null; then
+  err "curl is required to download HashPilot"
+  exit 1
+fi
+
+if [ "$REMOTE_MODE" = "true" ] && ! command -v tar &>/dev/null; then
+  err "tar is required to extract HashPilot"
+  exit 1
+fi
+
+# Check source
+if [ ! -f "$SOURCE_DIR/package.json" ]; then
+  err "Source directory '$SOURCE_DIR' does not contain package.json"
+  err "Run from the hashpilot repo root or use --source <path>"
+  exit 1
+fi
+
+# ── Detect existing install ──────────────────────────────────────────────
+MANIFEST="$TARGET_DIR/manifest.json"
+if [ -f "$MANIFEST" ]; then
+  if [ "$FORCE" != "true" ]; then
+    # Check if we're in an interactive terminal
+    if [ -t 0 ]; then
+      warn "Existing HashPilot installation detected at $TARGET_DIR"
+      echo -n "  Overwrite? [y/N] "
+      read -r CONFIRM
+      if [ "$CONFIRM" != "y" ] && [ "$CONFIRM" != "Y" ]; then
+        log "Install cancelled."
+        exit 0
+      fi
+    else
+      # Non-interactive (piped) - proceed with upgrade by default
+      # (user piped the script, so they clearly want to install/upgrade)
+      warn "Existing HashPilot installation detected at $TARGET_DIR; upgrading in non-interactive mode"
+    fi
+  fi
+  log "Upgrading existing installation..."
+else
+  log "Fresh installation..."
+fi
+
+# ── Install Core ────────────────────────────────────────────────────────
+log "Installing HashPilot Core..."
+mkdir -p "$TARGET_DIR"
+
+# If core already exists, remove node_modules first to avoid stale deps
+if [ -d "$TARGET_DIR/structured-editing" ]; then
+  rm -rf "$TARGET_DIR/structured-editing/node_modules"
+  # Preserve telemetry if requested
+  if [ "$KEEP_TELEMETRY" == "true" ] && [ -f "$TARGET_DIR/logs/telemetry.jsonl" ]; then
+    # The log can contain source diffs. A fixed path under a world-writable
+    # /tmp is readable by any local user and is a symlink-attack target, so
+    # back up beside the data itself, in a 0700 directory with an
+    # unpredictable name (#50).
+    TELEMETRY_BACKUP_DIR="$(mktemp -d "$TARGET_DIR/.telemetry-backup.XXXXXX")"
+    chmod 700 "$TELEMETRY_BACKUP_DIR"
+    cp "$TARGET_DIR/logs/telemetry.jsonl" "$TELEMETRY_BACKUP_DIR/"
+    chmod 600 "$TELEMETRY_BACKUP_DIR/telemetry.jsonl"
+    detail "Backed up telemetry to $TELEMETRY_BACKUP_DIR/"
+  fi
+fi
+
+# Copy core (exclude node_modules, .git)
+rsync -a --delete \
+  --exclude='node_modules' \
+  --exclude='.git' \
+  --exclude='logs' \
+  "$SOURCE_DIR/" "$TARGET_DIR/structured-editing/" 2>/dev/null || \
+cp -r "$SOURCE_DIR"/* "$TARGET_DIR/structured-editing/" 2>/dev/null || {
+  # Fallback: manual copy
+  mkdir -p "$TARGET_DIR/structured-editing"
+  for item in "$SOURCE_DIR"/*; do
+    [ "$(basename "$item")" == "node_modules" ] && continue
+    [ "$(basename "$item")" == ".git" ] && continue
+    cp -r "$item" "$TARGET_DIR/structured-editing/"
+  done
+}
+detail "Core source copied to $TARGET_DIR/structured-editing"
+
+# ── Install dependencies ────────────────────────────────────────────────
+log "Installing dependencies..."
+cd "$TARGET_DIR/structured-editing"
+bun install --frozen-lockfile 2>&1 | while IFS= read -r line; do detail "$line"; done
+cd "$OLDPWD"
+detail "Dependencies installed"
+
+# ── Create CLI launcher ──────────────────────────────────────────────────
+log "Creating CLI launcher..."
+mkdir -p "$TARGET_DIR/bin"
+# Remove any existing entry before writing. A development install
+# (`bun run install-cli`) leaves this path as a symlink into the checkout, and
+# `>` follows a symlink — so writing straight to it overwrites the repo's own
+# src/cli-node.cjs instead of replacing the launcher.
+rm -f "$TARGET_DIR/bin/hashpilot"
+cat > "$TARGET_DIR/bin/hashpilot" << 'LAUNCHER'
+#!/bin/bash
+exec bun run "$HOME/.agentic-tools/structured-editing/src/cli.ts" "$@"
+LAUNCHER
+chmod +x "$TARGET_DIR/bin/hashpilot"
+detail "Launcher created at $TARGET_DIR/bin/hashpilot"
+
+# Remove stale symlink from the old binary name (pre-3.1 installs).
+if [ -L "$TARGET_DIR/bin/structured-edit" ]; then
+  rm -f "$TARGET_DIR/bin/structured-edit"
+  detail "Removed stale symlink: $TARGET_DIR/bin/structured-edit"
+fi
+
+# ── Configure PATH ───────────────────────────────────────────────────────
+log "Adding PATH entry..."
+
+detect_rc() {
+  if [ -n "${HASHPILOT_SHELL_RC:-}" ]; then
+    echo "$HASHPILOT_SHELL_RC"
+    return
+  fi
+  # Prefer the rc file for the shell the user actually runs. Picking the first
+  # existing file instead puts the PATH line in ~/.bashrc on a macOS zsh box,
+  # where no interactive shell ever reads it.
+  case "${SHELL:-}" in
+    */zsh) echo "${HOME}/.zshrc"; return ;;
+    */bash) [ -f "${HOME}/.bashrc" ] && { echo "${HOME}/.bashrc"; return; } ;;
+  esac
+  for f in "${HOME}/.bashrc" "${HOME}/.zshrc" "${HOME}/.bash_profile" "${HOME}/.profile"; do
+    if [ -f "$f" ]; then
+      echo "$f"
+      return
+    fi
+  done
+  # Default
+  echo "${HOME}/.bashrc"
+}
+
+RC_FILE=$(detect_rc)
+PATH_MARKER_START="# >>> hashpilot path >>>"
+PATH_MARKER_END="# <<< hashpilot path <<<"
+PATH_LINE="export PATH=\"\$HOME/.agentic-tools/bin:\$PATH\""
+
+if [ -f "$RC_FILE" ]; then
+  if grep -q "$PATH_MARKER_START" "$RC_FILE" 2>/dev/null; then
+    detail "PATH entry already exists in $RC_FILE (skipping)"
+  else
+    {
+      echo ""
+      echo "$PATH_MARKER_START"
+      echo "$PATH_LINE"
+      echo "$PATH_MARKER_END"
+    } >> "$RC_FILE"
+    detail "Added PATH entry to $RC_FILE"
+  fi
+else
+  detail "Creating $RC_FILE with PATH entry"
+  {
+    echo "# Generated by HashPilot installer"
+    echo "$PATH_MARKER_START"
+    echo "$PATH_LINE"
+    echo "$PATH_MARKER_END"
+  } > "$RC_FILE"
+fi
+
+# ── Install templates (OpenCode, Pi, Claude) ─────────────────────────────
+TEMPLATES="$TARGET_DIR/structured-editing/templates"
+
+install_template() {
+  local src="$1"
+  local dst="$2"
+  local label="$3"
+  mkdir -p "$(dirname "$dst")"
+  if [ -f "$src" ]; then
+    cp "$src" "$dst"
+    detail "Installed ${label}: ${dst}"
+  else
+    warn "${label} template not found at ${src} (skipping)"
+  fi
+}
+
+log "Installing adapter integrations..."
+
+# OpenCode
+install_template "$TEMPLATES/opencode-skill.md" \
+  "${HOME}/.config/opencode/skills/hashpilot/SKILL.md" "OpenCode skill"
+install_template "$TEMPLATES/opencode-agent.md" \
+  "${HOME}/.config/opencode/agent/hashpilot.md" "OpenCode agent"
+
+# Pi
+install_template "$TEMPLATES/pi-extension.ts" \
+  "${HOME}/.pi/agent/extensions/hashpilot.ts" "Pi extension"
+install_template "$TEMPLATES/pi-skill.md" \
+  "${HOME}/.pi/agent/skills/hashpilot/SKILL.md" "Pi skill"
+
+# Claude
+CLAUDE_MARKER="HashPilot Claude — Structured Editing Integration"
+CLAUDE_FILE="${HOME}/.claude/CLAUDE.md"
+if [ -f "$TEMPLATES/claude-section.md" ]; then
+  mkdir -p "$(dirname "$CLAUDE_FILE")"
+  if [ -f "$CLAUDE_FILE" ] && grep -q "$CLAUDE_MARKER" "$CLAUDE_FILE" 2>/dev/null; then
+    detail "Claude integration already present in $CLAUDE_FILE (skipping)"
+  else
+    {
+      echo ""
+      cat "$TEMPLATES/claude-section.md"
+    } >> "$CLAUDE_FILE"
+    detail "Appended Claude integration to $CLAUDE_FILE"
+  fi
+else
+  warn "Claude section template not found (skipping)"
+fi
+
+# ── Bootstrap config ────────────────────────────────────────────────────
+log "Bootstrapping config..."
+CONFIG_DIR="${HOME}/.config/hashpilot"
+CONFIG_FILE="${CONFIG_DIR}/config.json"
+if [ -f "$CONFIG_FILE" ]; then
+  detail "Config already exists at $CONFIG_FILE (preserving)"
+else
+  mkdir -p "$CONFIG_DIR"
+  cat > "$CONFIG_FILE" << 'CONFIG'
+{
+  "telemetry": {
+    "enabled": true
+  },
+  "provenance": {
+    "maxContextLength": 500
+  }
+}
+CONFIG
+  detail "Created default config at $CONFIG_FILE"
+fi
+
+# ── Restore telemetry ───────────────────────────────────────────────────
+if [ "$KEEP_TELEMETRY" == "true" ] && [ -n "${TELEMETRY_BACKUP_DIR:-}" ] && [ -f "$TELEMETRY_BACKUP_DIR/telemetry.jsonl" ]; then
+  mkdir -p "$TARGET_DIR/logs"
+  cp "$TELEMETRY_BACKUP_DIR/telemetry.jsonl" "$TARGET_DIR/logs/"
+  detail "Restored telemetry from backup"
+  rm -rf "$TELEMETRY_BACKUP_DIR"
+fi
+
+# ── Write manifest ───────────────────────────────────────────────────────
+log "Writing manifest..."
+MANIFEST_FILE="$TARGET_DIR/manifest.json"
+
+# Detect shell rc path entries
+RC_ENTRIES="[]"
+if [ -f "$RC_FILE" ]; then
+  RC_ENTRIES=$(cat <<MANIFEST_RC
+    [
+      {
+        "file": "$RC_FILE",
+        "marker_start": "$PATH_MARKER_START",
+        "marker_end": "$PATH_MARKER_END"
+      }
+    ]
+MANIFEST_RC
+)
+fi
+
+cat > "$MANIFEST_FILE" << MANIFEST
+{
+  "version": "1",
+  "hashpilotVersion": "${HASHPILOT_VERSION}",
+  "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "sourceType": "$([ "$REMOTE_MODE" == "true" ] && echo "remote" || echo "clone")",
+  "hashpilotDir": "${TARGET_DIR}",
+  "components": {
+    "core": {
+      "source": "${TARGET_DIR}/structured-editing"
+    },
+    "bin": [
+      "${TARGET_DIR}/bin/hashpilot"
+    ],
+    "config": [
+      "${CONFIG_FILE}"
+    ],
+    "claude": {
+      "modified": [
+        "${CLAUDE_FILE}"
+      ]
+    },
+    "opencode": [
+      "${HOME}/.config/opencode/skills/hashpilot/SKILL.md",
+      "${HOME}/.config/opencode/agent/hashpilot.md"
+    ],
+    "pi": [
+      "${HOME}/.pi/agent/extensions/hashpilot.ts",
+      "${HOME}/.pi/agent/skills/hashpilot/SKILL.md"
+    ],
+    "telemetry": {
+      "dir": "${TARGET_DIR}/logs"
+    },
+    "pathEntries": ${RC_ENTRIES}
+  }
+}
+MANIFEST
+detail "Manifest written to $MANIFEST_FILE"
+
+# ── Cleanup ────────────────────────────────────────────────────────────────
+if [ "$REMOTE_MODE" = "true" ] && [ -n "${CLONE_DIR:-}" ]; then
+  rm -rf "$CLONE_DIR"
+  detail "Cleaned up temporary source"
+fi
+
+# ── Verify ───────────────────────────────────────────────────────────────
+log "Verifying installation..."
+if [ -f "$TARGET_DIR/bin/hashpilot" ]; then
+  detail "CLI launcher: OK"
+else
+  err "CLI launcher missing!"
+  exit 1
+fi
+
+if [ -d "$TARGET_DIR/structured-editing/node_modules" ]; then
+  detail "Dependencies: OK"
+else
+  err "Dependencies not installed!"
+  exit 1
+fi
+
+# Quick smoke test
+if command -v hashpilot &>/dev/null || [ -x "$TARGET_DIR/bin/hashpilot" ]; then
+  VER=$("$TARGET_DIR/bin/hashpilot" --version 2>/dev/null || echo "unknown")
+  detail "CLI version: ${VER}"
+fi
+
+# Final gate: doctor exits 2 on a broken install, 1 on warnings, 0 when healthy.
+# Telling the user "installed successfully" and letting them discover the
+# breakage on their first edit is the worse outcome (#46).
+if [ -x "$TARGET_DIR/bin/hashpilot" ]; then
+  # Two traps, both hit on the first real install:
+  #   1. `set -e` aborts the whole script when a command substitution exits
+  #      non-zero, so a plain assignment turned "doctor found something" into
+  #      a silent exit 2 with no message. Capture the code with `|| ...`.
+  #   2. The PATH entry was just written to the shell rc, which this process
+  #      never sourced, so `bin-on-path` fails at exactly the moment it cannot
+  #      yet succeed. Export the real PATH for the check.
+  DOCTOR_CODE=0
+  DOCTOR_OUT=$(PATH="$TARGET_DIR/bin:$PATH" "$TARGET_DIR/bin/hashpilot" --format text doctor 2>&1) || DOCTOR_CODE=$?
+  if [ "$DOCTOR_CODE" -ge 2 ]; then
+    err "Installation is not healthy:"
+    echo "$DOCTOR_OUT"
+    exit 1
+  elif [ "$DOCTOR_CODE" -eq 1 ]; then
+    detail "Doctor: healthy with warnings (run 'hashpilot doctor' for detail)"
+  else
+    detail "Doctor: healthy"
+  fi
+fi
+
+echo ""
+printf "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+printf "${GREEN} HashPilot v${HASHPILOT_VERSION} installed successfully${NC}\n"
+printf "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+echo ""
+echo "  Core:     $TARGET_DIR/structured-editing"
+echo "  CLI:      hashpilot"
+echo "  Config:   ${CONFIG_FILE}"
+echo "  Manifest: $MANIFEST_FILE"
+echo ""
+echo "  Run 'hashpilot doctor' to verify the installation."
+echo "  Restart your shell or run: source $RC_FILE"
+echo ""

package/scripts/roadmap-lint.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env bun
+/**
+ * Structural lint for ROADMAP.md.
+ *
+ * The roadmap is hand-edited every time an issue is filed or closed, and it has
+ * already shipped two defects of exactly this shape: an issue row duplicated into
+ * two sprints, and a row inserted out of score order. Both are mechanical and both
+ * are cheap to detect, so they are detected here instead of in review.
+ *
+ *   bun run scripts/roadmap-lint.ts            # lint ROADMAP.md
+ *   bun run scripts/roadmap-lint.ts <file>...  # lint specific files
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface LintIssue {
+  line: number;
+  rule: string;
+  message: string;
+}
+
+export interface Row {
+  line: number;
+  issue: number;
+  item: string;
+  score: number;
+  priority: string;
+  table: string;
+}
+
+const PRIORITIES = new Set(["P0", "P1", "P2", "P3"]);
+/** Accepted spellings of the priority column header, lowercased. */
+const PRIORITY_HEADERS = new Set(["pri", "priority"]);
+/** `| [#12](../../issues/12) | …` — display number and link target must agree. */
+const ISSUE_CELL = /^\[#(\d+)\]\((?:\.\.\/)*(?:\.\.\/)?issues\/(\d+)\)$/;
+
+function cells(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((c) => c.trim());
+}
+
+const isDivider = (line: string) => /^\|[\s:|-]+\|$/.test(line.trim());
+const isRow = (line: string) => line.trim().startsWith("|");
+
+/**
+ * Parses every scored issue table. A table qualifies when its header carries both
+ * a `#` column and a `Score` column, which excludes prose tables like the
+ * "Existing work already in the repo" listing.
+ */
+export function parseTables(text: string): { rows: Row[]; issues: LintIssue[] } {
+  const lines = text.split("\n");
+  const rows: Row[] = [];
+  const issues: LintIssue[] = [];
+  let table: string | null = null;
+  let heading = "(top of file)";
+  let columns: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.startsWith("#")) {
+      heading = line.replace(/^#+\s*/, "").trim();
+      table = null;
+      continue;
+    }
+    if (!isRow(line)) {
+      table = null;
+      continue;
+    }
+    if (isDivider(line)) continue;
+
+    const c = cells(line);
+    // Header row: opens a table if it is a scored issue table.
+    if (c[0] === "#" && isDivider(lines[i + 1] ?? "")) {
+      const scored = c.some((h) => h.toLowerCase() === "score");
+      table = scored ? heading : null;
+      columns = c;
+      // Every per-row rule below is keyed off a header name, so a renamed or
+      // dropped header turns its rule into a silent no-op — the table still
+      // lints clean while nothing about it is actually checked. Require the
+      // headers the rules depend on.
+      if (scored && !columns.some((h) => PRIORITY_HEADERS.has(h.toLowerCase()))) {
+        issues.push({
+          line: i + 1,
+          rule: "missing-column",
+          message: `scored table '${heading}' has no priority column (expected one of: ${[...PRIORITY_HEADERS].join(", ")}) — priority validation would be skipped`,
+        });
+      }
+      continue;
+    }
+    if (table === null) continue;
+
+    const link = ISSUE_CELL.exec(c[0] ?? "");
+    if (!link) {
+      issues.push({
+        line: i + 1,
+        rule: "issue-link",
+        message: `first cell is not an issue link: ${c[0]}`,
+      });
+      continue;
+    }
+    if (link[1] !== link[2]) {
+      issues.push({
+        line: i + 1,
+        rule: "issue-link",
+        message: `link text #${link[1]} points at issue ${link[2]}`,
+      });
+    }
+    if (c.length !== columns.length) {
+      issues.push({
+        line: i + 1,
+        rule: "column-count",
+        message: `row has ${c.length} cells, header has ${columns.length}`,
+      });
+    }
+
+    const scoreIdx = columns.findIndex((h) => h.toLowerCase() === "score");
+    const priIdx = columns.findIndex((h) => PRIORITY_HEADERS.has(h.toLowerCase()));
+    const raw = c[scoreIdx] ?? "";
+    const score = Number(raw);
+    if (!/^\d+$/.test(raw)) {
+      issues.push({ line: i + 1, rule: "score", message: `score is not an integer: ${raw}` });
+    }
+    const priority = c[priIdx] ?? "";
+    if (priIdx !== -1 && !PRIORITIES.has(priority)) {
+      issues.push({ line: i + 1, rule: "priority", message: `unknown priority: ${priority}` });
+    }
+
+    rows.push({
+      line: i + 1,
+      issue: Number(link[1]),
+      item: c[1] ?? "",
+      score: Number.isNaN(score) ? -1 : score,
+      priority,
+      table,
+    });
+  }
+  return { rows, issues };
+}
+
+export function lintRoadmap(text: string): LintIssue[] {
+  const { rows, issues } = parseTables(text);
+
+  // An issue belongs to exactly one table. A duplicate means a row was copied
+  // during a re-prioritization and the original never removed.
+  const seen = new Map<number, Row>();
+  for (const row of rows) {
+    const prior = seen.get(row.issue);
+    if (prior) {
+      issues.push({
+        line: row.line,
+        rule: "duplicate-issue",
+        message: `#${row.issue} already listed at line ${prior.line} (${prior.table})`,
+      });
+      continue;
+    }
+    seen.set(row.issue, row);
+  }
+
+  // Score orders work within a table, so a table that is not descending is
+  // telling a reader the wrong thing about what to pick up next.
+  const byTable = new Map<string, Row[]>();
+  for (const row of rows) {
+    if (!byTable.has(row.table)) byTable.set(row.table, []);
+    byTable.get(row.table)!.push(row);
+  }
+  for (const [table, group] of byTable) {
+    for (let i = 1; i < group.length; i++) {
+      const prev = group[i - 1]!;
+      const curr = group[i]!;
+      if (curr.score > prev.score) {
+        issues.push({
+          line: curr.line,
+          rule: "score-order",
+          message: `${table}: #${curr.issue} (${curr.score}) is listed after #${prev.issue} (${prev.score}) — tables sort by descending score`,
+        });
+      }
+    }
+  }
+
+  return issues.sort((a, b) => a.line - b.line);
+}
+
+if (import.meta.main) {
+  const files = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+  const targets = files.length ? files : [join(import.meta.dir, "..", "ROADMAP.md")];
+  let failed = false;
+  for (const file of targets) {
+    const found = lintRoadmap(readFileSync(file, "utf8"));
+    for (const issue of found) {
+      failed = true;
+      console.error(`${file}:${issue.line}  [${issue.rule}] ${issue.message}`);
+    }
+    if (!found.length) console.log(`✓ ${file}`);
+  }
+  process.exit(failed ? 1 : 0);
+}