novahiz 0.3.2 → 0.3.4

package/dist/complexity.js

@@ -0,0 +1,265 @@
+/**
+ * Task complexity scorer — multi-dimension analysis.
+ *
+ * Uses 6 weighted dimensions inspired by NVIDIA's Prompt Task & Complexity
+ * Classifier and MICE (Multiple Independent Classifiers Ensemble):
+ *
+ *   1. Technical Depth (0.25) — code/domain terms, API references
+ *   2. Reasoning Depth (0.25) — analysis, comparison, evaluation, proof
+ *   3. Scope & Scale (0.20) — multi-file, codebase-wide, cross-cutting
+ *   4. Constraints (0.15) — requirements, dependencies, constraints count
+ *   5. Domain Specificity (0.10) — security, payments, database, design
+ *   6. Action Verb Intensity (0.05) — implement vs fix vs rename
+ *
+ * Three tiers:
+ *   - trivial: typo fixes, comments, config changes → no pipeline
+ *   - lite: bug fixes, minor additions → implement + converge only
+ *   - full: features, refactors, audits → complete 6-step pipeline
+ */
+// ── Signal banks by dimension ──────────────────────────────────────────────
+const SIGNALS = {
+    technicalDepth: [
+        // Architecture & patterns
+        /\b(refactor|architecture|design\s*system|restructure|migrate|migration)\b/i,
+        /\b(microservice|monolith|scaling|horizontal|vertical\s*scal)\b/i,
+        /\b(ci\/cd|pipeline|deployment|infrastructure|terraform|kubernetes|docker)\b/i,
+        // API & protocols
+        /\b(api\s*design|rest\s*api|graphql|grpc|openapi|swagger|webhook|endpoint)\b/i,
+        /\b(websocket|socket\.io|server[\s-]?sent|event[\s-]?source|long[\s-]?polling)\b/i,
+        // Real-time & streaming
+        /\b(real[\s-]?time|streaming|live[\s-]?data|push[\s-]?notif|event[\s-]?driven)\b/i,
+        // Data structures & algorithms
+        /\b(algorithm|data\s*structure|tree|graph|hash|queue|stack|linked\s*list)\b/i,
+        // State management & patterns
+        /\b(state\s*management|redux|vuex|zustand|recoil|signal|observable|stream)\b/i,
+        // Build & tooling
+        /\b(webpack|vite|rollup|esbuild|babel|typescript\s*config|tsconfig)\b/i,
+        /\b(package[\s-]?json|dependency|dependency[\s-]?tree|transitive)\b/i,
+        // Memory & performance
+        /\b(memory\s*leak|performance|optimization|profiling|latency|throughput|bottleneck)\b/i,
+        // Concurrency
+        /\b(concurrent|parallel|race[\s-]?condition|deadlock|thread|async|await|mutex|semaphore)\b/i,
+        // Caching
+        /\b(cache|caching|redis|memcached|invalidation|ttl|eviction)\b/i,
+    ],
+    reasoningDepth: [
+        // Analysis verbs
+        /\b(analyze|analyse|investigate|explore|audit|review|inspect|examine|diagnose)\b/i,
+        // Comparison & evaluation
+        /\b(compare|evaluate|assess|benchmark|trade[\s-]?offs?|pros?\s*(and|&)\s*cons?)\b/i,
+        // Proof & verification
+        /\b(prove|verify|validate|confirm|demonstrate|show\s*that|argue)\b/i,
+        // Logical reasoning
+        /\b(deduce|infer|conclude|reason|logic|therefore|thus|hence)\b/i,
+        // Synthesis
+        /\b(synthesize|integrate|combine|merge|consolidate|unify)\b/i,
+        // Design thinking
+        /\b(design|architect|plan|strategize|prioritize|decompose|break\s*down)\b/i,
+        // Optimization reasoning
+        /\b(optimize|simplify|streamline|refactor|improve|enhance|elevate)\b/i,
+        // Multi-step reasoning
+        /\b(step[\s-]?by[\s-]?step|progressive|iterative|incremental|gradual)\b/i,
+    ],
+    scopeScale: [
+        // Cross-file scope
+        /\b(across|entire|all\s*files|multiple\s*files|codebase|project[\s-]?wide)\b/i,
+        /\b(full[\s-]?stack|end[\s-]?to[\s-]?end|e2e|top[\s-]?to[\s-]?bottom)\b/i,
+        // Setup & scaffolding
+        /\b(setup|scaffold|initialize|bootstrap|new\s*project|from\s*scratch)\b/i,
+        // Multi-component
+        /\b(components?|modules?|services?|layers?|tiers?|packages?)\s*(and|&|\+)\s*(components?|modules?|services?|layers?|tiers?|packages?)/i,
+        // Migration scope
+        /\b(migrate|upgrade|transition|convert|transform)\s+(all|every|entire|the\s*whole|from\s*\w+\s*to)\b/i,
+        // System-wide
+        /\b(system[\s-]?wide|globally|throughout|everywhere|universally)\b/i,
+        // Multi-step tasks
+        /\b(implement\s+a\s+(full|complete|comprehensive|new)|build\s+a\s+(full|complete|new))\b/i,
+    ],
+    constraints: [
+        // Explicit requirements
+        /\b(must|shall|required|mandatory|obligatory|necessary|essential)\b/i,
+        // Compatibility
+        /\b(compatible|backward|forward|cross[\s-]?browser|cross[\s-]?platform|support\s+(for|all|both|multiple))\b/i,
+        // Dependencies
+        /\b(depend|prerequisite|require|depends?\s*on|rely\s*on|reliance)\b/i,
+        // Security constraints
+        /\b(secure|security|encrypt|decrypt|auth|permission|access[\s-]?control|role[\s-]?based)\b/i,
+        // Performance constraints
+        /\b(performance|fast|slow|latency|timeout|throttle|rate[\s-]?limit|budget)\b/i,
+        // Compliance
+        /\b(compliant|compliance|regulate|gdpr|hipaa|soc\s*2|pci[\s-]?dss|owasp)\b/i,
+        // Time constraints
+        /\b(deadline|urgent|asap|quickly|immediate|soon|today|now)\b/i,
+        // Quality constraints
+        /\b(test|coverage|lint|clean|robust|resilient|fault[\s-]?tolerant|graceful)\b/i,
+    ],
+    domainSpecificity: [
+        // Security domain
+        /\b(security|vulnerability|owasp|cwe|xss|csrf|injection|sqli|penetration)\b/i,
+        // Payments domain
+        /\b(payment|stripe|checkout|subscription|billing|invoice|payment[\s-]?gateway)\b/i,
+        // Database domain
+        /\b(schema|table|column|index|foreign[\s-]?key|constraint|trigger|migration|supabase|postgres)\b/i,
+        // Auth domain
+        /\b(auth|authentication|authorization|oauth|jwt|session|token|login|signup)\b/i,
+        // Real-time domain
+        /\b(real[\s-]?time|streaming|queue|worker|cron|scheduled|pub[\s-]?sub)\b/i,
+        // Design domain
+        /\b(ui|ux|interface|landing[\s-]?page|mockup|wireframe|layout|responsive|a11y|animation)\b/i,
+        // Infrastructure domain
+        /\b(ci\/cd|pipeline|deployment|infrastructure|terraform|kubernetes|docker|cloud)\b/i,
+        // AI/ML domain
+        /\b(machine[\s-]?learning|ml|ai|neural|model|training|inference|embedding|vector)\b/i,
+        // Testing domain
+        /\b(test[\s-]?suite|integration[\s-]?test|e2e|end[\s-]?to[\s-]?end|coverage|mock|stub)\b/i,
+    ],
+    actionIntensity: [
+        // Full-tier actions (complex verbs)
+        { pattern: /\b(implement|build|create|design|architect|scaffold|bootstrap)\b/i, lite: 0, full: 3 },
+        { pattern: /\b(refactor|rewrite|restructure|reorganize|migrate|convert)\b/i, lite: 0, full: 3 },
+        { pattern: /\b(audit|security\s*review|pentest|penetration\s*test)\b/i, lite: 0, full: 3 },
+        { pattern: /\b(deploy|release|ship|launch|publish)\b/i, lite: 1, full: 1 },
+        // Lite-tier actions (repair verbs)
+        { pattern: /\b(fix|repair|patch|resolve|debug|diagnose)\b/i, lite: 2, full: 0 },
+        { pattern: /\b(update|upgrade|bump|change|modify|edit|adjust)\b/i, lite: 2, full: 0 },
+        { pattern: /\b(add|remove|delete|write|rename|relabel|reword|rephrase|optimize|simplify)\b/i, lite: 2, full: 0 },
+        // Trivial-tier actions (simple verbs)
+        { pattern: /\b(comment|document|annotate|explain)\b/i, lite: 0, full: 0 },
+        { pattern: /\b(typo|spelling|misspell|correct\s*the)\b/i, lite: 0, full: 0 },
+    ],
+};
+// ── Trivial signals (override to trivial) ──────────────────────────────────
+const TRIVIAL_OVERRIDE = [
+    // Explicit typo/fix commands
+    /\b(fix\s+the\s+typo|correct\s+the\s+spelling|change\s+\w+\s+to\s+\w+)\b/i,
+    // Single-word commands
+    /^(rename|set|update|add|remove|delete|toggle|enable|disable)\s+\S+(\s+\S+){0,2}$/i,
+    // Config-only changes — NOT trivial: changing config is a real action
+    // /\b(update\s+the\s+config|change\s+the\s+setting|bump\s+the\s+version)\b/i,
+    // Comment-only — NOT trivial: "add a comment" is a real action
+    // /\b(add\s+a\s+comment|document\s+the|add\s+docstring)\b/i,
+];
+// ── Scoring functions ──────────────────────────────────────────────────────
+function countMatches(text, patterns) {
+    let count = 0;
+    for (const p of patterns) {
+        if (p.test(text))
+            count++;
+    }
+    return count;
+}
+function scoreActionIntensity(text) {
+    let lite = 0;
+    let full = 0;
+    for (const { pattern, lite: l, full: f } of SIGNALS.actionIntensity) {
+        if (pattern.test(text)) {
+            lite += l;
+            full += f;
+        }
+    }
+    return { lite, full };
+}
+function countConstraints(text) {
+    let count = 0;
+    for (const p of SIGNALS.constraints) {
+        if (p.test(text))
+            count++;
+    }
+    return count;
+}
+// ── Main scoring ───────────────────────────────────────────────────────────
+export function scoreDimensions(prompt) {
+    const text = prompt.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+    const technicalDepth = countMatches(text, SIGNALS.technicalDepth);
+    const reasoningDepth = countMatches(text, SIGNALS.reasoningDepth);
+    const scopeScale = countMatches(text, SIGNALS.scopeScale);
+    const constraints = countConstraints(text);
+    const domainSpecificity = countMatches(text, SIGNALS.domainSpecificity);
+    const action = scoreActionIntensity(text);
+    // Normalize constraint count (cap at 5 for scoring purposes)
+    const normalizedConstraints = Math.min(constraints, 5);
+    return {
+        technicalDepth,
+        reasoningDepth,
+        scopeScale,
+        constraints: normalizedConstraints,
+        domainSpecificity,
+        actionIntensity: { lite: action.lite, full: action.full },
+    };
+}
+/**
+ * Compute complexity scores using additive model.
+ * Each dimension match adds points. Higher total = more complex.
+ */
+function computeScores(dims, wordCount) {
+    // Full-tier score: sum of all dimension matches (each match = 1 point)
+    // Plus action intensity bonus for creation/implementation verbs
+    const full = dims.technicalDepth +
+        dims.reasoningDepth +
+        dims.scopeScale +
+        dims.constraints +
+        dims.domainSpecificity +
+        dims.actionIntensity.full;
+    // Lite-tier score: repair actions + low-complexity signals
+    const lite = dims.actionIntensity.lite +
+        dims.technicalDepth +
+        dims.reasoningDepth +
+        dims.domainSpecificity;
+    // Trivial bonus: short prompts with no complexity signals
+    const trivial = wordCount <= 5 ? 3 : wordCount <= 8 ? 1 : 0;
+    return { full, lite, trivial };
+}
+/**
+ * Score a prompt and determine its complexity tier.
+ */
+export function scoreComplexity(prompt) {
+    // Check trivial override first
+    const normalized = prompt.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+    for (const pattern of TRIVIAL_OVERRIDE) {
+        if (pattern.test(normalized))
+            return "trivial";
+    }
+    const dims = scoreDimensions(prompt);
+    const wordCount = normalized.trim().split(/\s+/).length;
+    const { full, lite, trivial } = computeScores(dims, wordCount);
+    // Decision logic:
+    //   full >= 3 → definitely full
+    //   full >= 2 → full (2+ dimension matches is substantial)
+    //   dims.actionIntensity.full >= 2 && wordCount >= 5 → full (creation verb in a non-trivial prompt)
+    //   full >= 1 && wordCount >= 12 → full (long prompt with at least 1 signal)
+    //   dims.actionIntensity.lite >= 2 && wordCount >= 3 → lite (repair verb in a non-trivial prompt)
+    //   trivial >= 3 && full < 2 → trivial (short, no complexity, no repair verb)
+    //   lite >= 2 && full < 2 → lite
+    //   default: use length heuristic
+    if (full >= 3)
+        return "full";
+    if (full >= 2)
+        return "full";
+    if (dims.actionIntensity.full >= 2 && wordCount >= 5)
+        return "full";
+    if (full >= 1 && wordCount >= 12)
+        return "full";
+    if (dims.actionIntensity.lite >= 2 && wordCount >= 3)
+        return "lite";
+    if (trivial >= 3 && full < 2)
+        return "trivial";
+    if (lite >= 2 && full < 2)
+        return "lite";
+    // Default by length — H5: only trigger "full" if technical signals are present
+    if (wordCount <= 8)
+        return "trivial";
+    if (wordCount <= 40)
+        return "lite";
+    const hasDomainSignal = dims.technicalDepth > 0 || dims.domainSpecificity > 0;
+    return hasDomainSignal ? "full" : "lite";
+}
+/**
+ * Determine the complexity tier based on prompt analysis.
+ * Main entry point for the complexity system.
+ */
+export function determineTier(prompt) {
+    // C2: guard against null/undefined — treat as trivial instead of crashing
+    if (!prompt || typeof prompt !== "string")
+        return "trivial";
+    return scoreComplexity(prompt);
+}

package/dist/content.js

@@ -0,0 +1,99 @@
+export function changeText(tool, args) {
+    const record = (args && typeof args === "object" ? args : {});
+    const parts = [];
+    for (const key of ["newString", "new_string", "content", "patchText", "patch", "newText"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.length > 0)
+            parts.push(value);
+    }
+    const edits = record.edits;
+    if (Array.isArray(edits)) {
+        for (const edit of edits) {
+            if (!edit || typeof edit !== "object")
+                continue;
+            const entry = edit;
+            for (const key of ["newString", "new_string", "content", "newText"]) {
+                const value = entry[key];
+                if (typeof value === "string" && value.length > 0)
+                    parts.push(value);
+            }
+        }
+    }
+    return parts.join("\n");
+}
+const STYLE_SIGNALS = [
+    /(^|\n)\s*[.#][\w-]+(\s*[:>+~]\s*[.#\w:-]+)*\s*[,{]/,
+    /className\s*=/i,
+    /style\s*[=:]\s*[{"]/i,
+    /styled\./,
+    /\bcss`/,
+    /\b(gap-\d|p[xy]?-\d|m[xy]?-\d|text-\w+-\d|bg-\w+-\d)\b/i
+];
+const PROSE_SIGNALS = [
+    /\/\*\*?[\s\S]*?[A-Za-z][A-Za-z ,.'()-]{12,}[\s\S]*?\*\//,
+    /"[^"\n]{15,}[ ][^"\n]{10,}"/,
+    /'[^'\n]{15,}[ ][^'\n]{10,}'/,
+    /`[^`\n]{15,}[ ][^`\n]{10,}`/,
+    /(^|\n)\s{0,3}\S[^\n]*\s\S+\s[^\n]*[.!?](\s|$)/
+];
+// H6: the old single-line rule — any `//`/`#` comment with 12+ alpha chars —
+// flagged license headers ("Copyright 2024 ..."), TODOs and linter directives
+// as prose. A comment is prose only when it reads like a sentence: no code
+// tokens, no directive prefix, and either ending punctuation or a long
+// multi-word description.
+const COMMENT_DIRECTIVE = /^\s*(\/\/|#|\*)\s*(TODO|FIXME|XXX|HACK|eslint|tslint|prettier|stylelint|c8|istanbul|@ts-|@vite-|node:|deno-lint)/i;
+const CODE_TOKENS = /[=;{}()[\]=>]/;
+function isProseCommentLine(line) {
+    const match = line.match(/^\s*(\/\/|#|\*)\s+(.+)$/);
+    if (!match)
+        return false;
+    const body = match[2].trim();
+    if (body.length === 0)
+        return false;
+    if (COMMENT_DIRECTIVE.test(line))
+        return false;
+    if (CODE_TOKENS.test(body))
+        return false;
+    // Complete sentence: uppercase start, ending punctuation.
+    if (/^[A-Z].{15,}[.!?]$/.test(body))
+        return true;
+    // Long multi-word description: 40+ chars, 4+ plain words.
+    if (body.length >= 40) {
+        const words = body.split(/\s+/).filter((word) => /^[A-Za-z][A-Za-z,.'()-]*$/.test(word));
+        return words.length >= 4;
+    }
+    return false;
+}
+export function hasStyle(text) {
+    if (text.length === 0)
+        return false;
+    return STYLE_SIGNALS.some((pattern) => pattern.test(text));
+}
+export function hasProse(text) {
+    if (text.length === 0)
+        return false;
+    if (PROSE_SIGNALS.some((pattern) => pattern.test(text)))
+        return true;
+    return text.split(/\r?\n/).some(isProseCommentLine);
+}
+export function isTrivial(text, minChange = 0) {
+    if (minChange <= 0)
+        return text.trim().length === 0;
+    return text.replace(/\s+/g, " ").trim().length < minChange;
+}
+const PLACEHOLDER_PATTERNS = [
+    /\b(TODO|FIXME|XXX|HACK)\b/,
+    /\bnot implemented\b/i,
+    /\bcoming soon\b/i,
+    /<placeholder/i,
+    /<your[_ ]code/i,
+    /\blorem ipsum\b/i,
+    /\.\.\.\s*rest of\b/i,
+    /\bimplement me\b/i,
+    /\.\.\.\s*existing\b/i
+];
+export function hasPlaceholder(text) {
+    if (text.length === 0)
+        return false;
+    return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}

package/dist/db.js

@@ -0,0 +1,176 @@
+import { DatabaseSync } from "node:sqlite";
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pruneSessions } from "./ledger.js";
+import { autoCommit } from "./graft.js";
+export { DatabaseSync };
+export function openDb(dbPath) {
+    const absolute = resolve(dbPath);
+    mkdirSync(dirname(absolute), { recursive: true });
+    const db = new DatabaseSync(absolute);
+    if (process.platform !== "win32") {
+        try {
+            chmodSync(absolute, 0o600);
+        }
+        catch {
+            // best effort, the umask may forbid it
+        }
+    }
+    db.exec("PRAGMA journal_mode = WAL;");
+    db.exec("PRAGMA busy_timeout = 5000;");
+    db.exec("PRAGMA foreign_keys = ON;");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    );
+    CREATE TABLE IF NOT EXISTS skills (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      source_path TEXT,
+      power INTEGER NOT NULL DEFAULT 3,
+      stars INTEGER,
+      tags TEXT NOT NULL DEFAULT '[]',
+      categories TEXT NOT NULL DEFAULT '[]',
+      scanned_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS categories (
+      id TEXT PRIMARY KEY,
+      label TEXT,
+      priority INTEGER NOT NULL DEFAULT 0,
+      keywords TEXT NOT NULL DEFAULT '[]',
+      default_skills TEXT NOT NULL DEFAULT '[]'
+    );
+    CREATE TABLE IF NOT EXISTS rules (
+      id TEXT PRIMARY KEY,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      agent TEXT,
+      categories TEXT NOT NULL DEFAULT '[]',
+      required_skills TEXT NOT NULL DEFAULT '[]',
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS skill_invocations (
+      session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+      skill TEXT NOT NULL,
+      invoked_at TEXT NOT NULL,
+      PRIMARY KEY (session_id, skill)
+    );
+    CREATE TABLE IF NOT EXISTS roadmap_progress (
+      session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+      step_id TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'done',
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (session_id, step_id)
+    );
+    CREATE TABLE IF NOT EXISTS enforcement_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT,
+      tool TEXT,
+      file_path TEXT,
+      file_class TEXT,
+      decision TEXT,
+      missing TEXT NOT NULL DEFAULT '[]',
+      matched_rules TEXT NOT NULL DEFAULT '[]',
+      logged_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS tasks (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      revision INTEGER NOT NULL DEFAULT 0,
+      reviewed_at TEXT,
+      edits_since_review INTEGER NOT NULL DEFAULT 0,
+      todos_since_review INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE TABLE IF NOT EXISTS todos (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      seq INTEGER NOT NULL DEFAULT 0,
+      label TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'edit',
+      status TEXT NOT NULL DEFAULT 'pending',
+      acceptance TEXT,
+      proof TEXT,
+      owner TEXT,
+      depends_on TEXT NOT NULL DEFAULT '[]',
+      iterations INTEGER NOT NULL DEFAULT 0,
+      max_iterations INTEGER,
+      updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS enforcement_log_logged_at ON enforcement_log(logged_at);
+    CREATE INDEX IF NOT EXISTS enforcement_log_session ON enforcement_log(session_id);
+    CREATE INDEX IF NOT EXISTS todos_task_id ON todos(task_id);
+    CREATE INDEX IF NOT EXISTS tasks_status_session ON tasks(status, session_id);
+    CREATE INDEX IF NOT EXISTS skill_invocations_session ON skill_invocations(session_id);
+    CREATE INDEX IF NOT EXISTS roadmap_progress_session ON roadmap_progress(session_id);
+  `);
+    migrate(db);
+    // H4: enforce the session TTL on every open — best effort, prune failures
+    // must never break startup.
+    try {
+        pruneSessions(db);
+        // Auto-commit after session pruning
+        autoCommit("prune-sessions");
+    }
+    catch {
+        // sessions table may predate updated_at on very old installs; migrate covers it
+    }
+    return db;
+}
+// Table and column names are interpolated here, unlike every other query in the
+// project, because SQLite does not parameterize identifiers. H8: the allowlist
+// below makes the "fixed strings only" invariant structural — any future caller
+// passing a non-listed identifier throws instead of injecting SQL.
+const SAFE_TABLES = new Set([
+    "meta",
+    "skills",
+    "categories",
+    "rules",
+    "sessions",
+    "skill_invocations",
+    "roadmap_progress",
+    "enforcement_log",
+    "tasks",
+    "todos"
+]);
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSafeIdentifier(kind, value) {
+    if (!SAFE_IDENTIFIER.test(value))
+        throw new Error(`unsafe SQL ${kind}: ${value}`);
+}
+function tableColumns(db, table) {
+    if (!SAFE_TABLES.has(table))
+        throw new Error(`unexpected table name: ${table}`);
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return new Set(rows.map((row) => row.name));
+}
+function ensureColumn(db, table, column, definition) {
+    if (!SAFE_TABLES.has(table))
+        throw new Error(`unexpected table name: ${table}`);
+    assertSafeIdentifier("column", column);
+    if (tableColumns(db, table).has(column))
+        return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition};`);
+}
+export const SCHEMA_VERSION = 1;
+function migrate(db) {
+    ensureColumn(db, "tasks", "revision", "INTEGER NOT NULL DEFAULT 0");
+    ensureColumn(db, "tasks", "reviewed_at", "TEXT");
+    ensureColumn(db, "tasks", "edits_since_review", "INTEGER NOT NULL DEFAULT 0");
+    ensureColumn(db, "tasks", "todos_since_review", "INTEGER NOT NULL DEFAULT 0");
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+}
+export function setMeta(db, key, value) {
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+export function getMeta(db, key) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value ?? null;
+}

package/dist/deps.js

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+export function commandExists(command) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(probe, [command], { encoding: "utf8", shell: false });
+    return result.status === 0;
+}
+export function checkDependencies(spec) {
+    return spec.providers.map((provider) => {
+        const requires = provider.requires ?? [];
+        const missing = requires.filter((command) => !commandExists(command));
+        return { id: provider.id, kind: provider.kind, requires, missing, ok: missing.length === 0 };
+    });
+}
+export function bootstrapFor(provider, platform = process.platform) {
+    const bootstrap = provider.bootstrap;
+    if (!bootstrap)
+        return null;
+    return bootstrap[platform] ?? bootstrap.default ?? null;
+}
+export function missingPrerequisites(spec) {
+    return spec.providers
+        .map((provider) => ({ provider, missing: (provider.requires ?? []).filter((command) => !commandExists(command)) }))
+        .filter((entry) => entry.missing.length > 0);
+}

package/dist/exec.js

@@ -0,0 +1,108 @@
+import { spawnSync } from "node:child_process";
+// Allowed characters for a single argument. It excludes every character a shell
+// can reinterpret: whitespace, & | < > ^ % ! ( ) " ' ` ; $ * ? and newlines.
+// The Windows branch below joins tokens with spaces and hands the result to
+// cmd.exe, so widening this set would re-open command injection on that path.
+const SAFE_TOKEN = /^[A-Za-z0-9@._+,/:=~-]+$/;
+function resultFrom(status, stdout, stderr, error) {
+    return { ok: status === 0, status, stdout, stderr, error };
+}
+function refused(token) {
+    return { ok: false, status: null, stdout: "", stderr: "", error: `refused unsafe token: ${token}` };
+}
+export function unsafeToken(tokens) {
+    for (const token of tokens) {
+        if (token.length === 0)
+            return "";
+        if (!SAFE_TOKEN.test(token))
+            return token;
+    }
+    return null;
+}
+export function runCommand(bin, args) {
+    const bad = unsafeToken([bin, ...args]);
+    if (bad !== null)
+        return refused(bad);
+    const [command, spawnArgs] = resolveSpawn(bin, args);
+    const result = spawnSync(command, spawnArgs, { encoding: "utf8", windowsHide: true, shell: false });
+    return resultFrom(result.status, result.stdout ?? "", result.stderr ?? "", result.error?.message);
+}
+function resolveSpawn(bin, args) {
+    if (process.platform !== "win32")
+        return [bin, args];
+    // The shell is taken from the environment. Whoever can set ComSpec can already
+    // run code locally, so the token allowlist above is what actually contains the
+    // arguments; this is noted for completeness, not treated as a boundary.
+    const shell = process.env.ComSpec ?? "cmd.exe";
+    return [shell, ["/d", "/s", "/c", [bin, ...args].join(" ")]];
+}
+// Bootstrap may only start a known interpreter or packager. Shell binaries
+// (sh, bash, pwsh, powershell, cmd) are deliberately absent: arguments are
+// parsed by the executable itself, so a shell would turn this allowlist into
+// a formality by reinterpreting anything it is handed.
+const SAFE_BOOTSTRAP_BINS = new Set([
+    "node", "npm", "npx", "uv", "uvx", "python", "py"
+]);
+function normalizeBin(bin) {
+    const base = bin.replace(/\\/g, "/").split("/").pop() ?? bin;
+    return base.toLowerCase();
+}
+function bootstrapBinAllowed(bin) {
+    const name = normalizeBin(bin);
+    const withoutExt = name.replace(/\.(exe|cmd|bat)$/i, "");
+    return SAFE_BOOTSTRAP_BINS.has(name) || SAFE_BOOTSTRAP_BINS.has(withoutExt);
+}
+function refusedBootstrap(bin) {
+    return { ok: false, status: null, stdout: "", stderr: "", error: `refused disallowed bootstrap binary: ${bin}` };
+}
+// Bootstrap argv comes from catalog/providers.json. Every token is bounded:
+// the bin must be in SAFE_BOOTSTRAP_BINS, each argument must pass SAFE_TOKEN
+// (no whitespace, no shell metacharacter), and interpreters that execute an
+// inline string must not receive one — `python -c` and `node -e` are the
+// shell -c equivalents that would otherwise nullify the allowlist.
+const CODE_RUNNER_FLAGS = {
+    python: ["-c", "--command"],
+    py: ["-c", "--command"],
+    node: ["-e", "--eval", "-p", "--print", "--repl"]
+};
+export function isCodeRunnerFlag(bin, token) {
+    const name = normalizeBin(bin).replace(/\.(exe|cmd|bat)$/i, "");
+    const flags = CODE_RUNNER_FLAGS[name];
+    if (!flags)
+        return false;
+    if (token.startsWith("--")) {
+        const eq = token.indexOf("=");
+        return flags.includes(eq > 0 ? token.slice(0, eq) : token);
+    }
+    // A short option may carry its value attached: -ccode, -ecode.
+    if (token.startsWith("-") && token.length > 2)
+        return flags.includes(token.slice(0, 2));
+    return flags.includes(token);
+}
+function refusedCodeRunner(token) {
+    return { ok: false, status: null, stdout: "", stderr: "", error: `refused code-runner flag: ${token}` };
+}
+export function runScript(argv) {
+    if (argv.length === 0)
+        return refused("");
+    const [bin, ...args] = argv;
+    if (!SAFE_TOKEN.test(bin))
+        return refused(bin);
+    if (!bootstrapBinAllowed(bin))
+        return refusedBootstrap(bin);
+    for (const arg of args) {
+        if (arg.length === 0)
+            return refused("");
+        if (isCodeRunnerFlag(bin, arg))
+            return refusedCodeRunner(arg);
+        if (!SAFE_TOKEN.test(arg))
+            return refused(arg);
+    }
+    // Tokens are already bounded (SAFE_TOKEN: no whitespace, no metacharacter),
+    // so handing the joined string to cmd.exe on Windows is safe and is the only
+    // way npm/npx (.cmd shims) can run at all — direct CreateProcess throws
+    // ENOENT since the Node CVE-2024-* .cmd hardening.
+    const [command, spawnArgs] = resolveSpawn(bin, args);
+    const result = spawnSync(command, spawnArgs, { encoding: "utf8", windowsHide: true, shell: false });
+    return resultFrom(result.status, result.stdout ?? "", result.stderr ?? "", result.error?.message);
+}