@lsctech/polaris 0.1.0

package/dist/cli/adopt-rules.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePolarisRules = generatePolarisRules;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function buildRepoOverview(inventory) {
+    const notes = inventory.architecture_notes.filter(Boolean);
+    const roots = inventory.source_roots.filter(Boolean);
+    const lines = [];
+    if (notes.length > 0) {
+        lines.push(notes.slice(0, 3).join(" "));
+    }
+    else if (roots.length > 0) {
+        lines.push(`Source roots: ${roots.slice(0, 4).join(", ")}.`);
+    }
+    return lines.join(" ").trim() || "Repository managed by Polaris.";
+}
+async function generatePolarisRules(repoRoot, inventory, options = {}) {
+    const { overwrite = true } = options;
+    const outputPath = (0, node_path_1.join)(repoRoot, "POLARIS_RULES.md");
+    if ((0, node_fs_1.existsSync)(outputPath) && !overwrite) {
+        return;
+    }
+    const overview = buildRepoOverview(inventory);
+    const content = [
+        "# Polaris Rules",
+        "",
+        "> This file is the single shared governance source for this Polaris-managed repository.",
+        "> Agent files (AGENTS.md, CLAUDE.md, etc.) are pointers to this file.",
+        "> This file is SmartDocs-ignored — it is bootstrap governance, not doctrine.",
+        "",
+        "## Repository Overview",
+        "",
+        overview,
+        "",
+        "---",
+        "",
+        "## Temporary Worker Doctrine",
+        "",
+        "Every model instance is a temporary occupant of a durable role. Roles persist; model",
+        "instances are disposable.",
+        "",
+        "A worker should arrive at a task knowing only:",
+        "- what job it is doing",
+        "- what files it may touch",
+        "- what route governs the work",
+        "- what validation proves completion",
+        "",
+        "If a worker requires broad repository context, the cognition structure has failed — not",
+        "the worker.",
+        "",
+        "---",
+        "",
+        "## Repository Memory Doctrine",
+        "",
+        "Polaris stores institutional memory in repository artifacts rather than model memory.",
+        "Knowledge should be discoverable through navigation, route cognition, SmartDocs,",
+        "summaries, commits, telemetry, and runtime artifacts.",
+        "",
+        "Workers should not rely on persistent model memory to perform assigned work.",
+        "",
+        "---",
+        "",
+        "## Navigation Before Retrieval",
+        "",
+        "Links are retrieval paths, not reading assignments.",
+        "",
+        "Workers should not read doctrine, charts, or supporting documents merely because they",
+        "exist.",
+        "",
+        "Expected behavior:",
+        "1. Attempt work",
+        "2. Encounter problem",
+        "3. Check local guidance",
+        "4. Match symptom",
+        "5. Retrieve relevant artifact",
+        "6. Continue",
+        "",
+        "Never preload all linked documents.",
+        "Never load all doctrine.",
+        "Never load all charts.",
+        "",
+        "Navigation precedes retrieval.",
+        "Retrieval precedes loading.",
+        "",
+        "---",
+        "",
+        "## Skill Command Routing",
+        "",
+        "When a Polaris skill command is received, load the skill packet before any other action.",
+        "Full routing table: `.polaris/skills/ROUTING.md`",
+        "",
+        "Recognized command forms use `<CLUSTER-ID>` as the work identifier:",
+        "",
+        "- `polaris-analyze <CLUSTER-ID>` / `run polaris-analyze on [issue] <CLUSTER-ID>`",
+        "- `polaris-run <CLUSTER-ID>` / `run polaris-run on [issue] <CLUSTER-ID>`",
+        "- `polaris-finalize` / `run polaris-finalize`",
+        "- `polaris-status` / `run polaris-status`",
+        "- `docs-ingest` / `run docs-ingest`",
+        "- `polaris-reconcile <CLUSTER-ID>` / `run polaris-reconcile on [issue] <CLUSTER-ID>`",
+        "- `polaris-catalog <CLUSTER-ID>` / `run polaris-catalog on [issue] <CLUSTER-ID>`",
+        "",
+        "When a recognized command is received:",
+        "1. Look up the target skill in `.polaris/skills/ROUTING.md`",
+        "2. Read `.polaris/skills/<target-skill>/SKILL.md` first — before any repo inspection",
+        "3. Run the bootloader command to obtain the runtime packet",
+        "4. Execute the skill's `chain.md` in strict step order",
+        "",
+        "---",
+        "",
+        "## Map-Query Rule",
+        "",
+        "The map is runtime infrastructure. Query results are model context.",
+        "",
+        "**Agents may query the map. Agents may not consume map artifacts.**",
+        "",
+        "Use:",
+        "```",
+        "polaris map query <path>",
+        "```",
+        "",
+        "Never read these files directly:",
+        "- `.polaris/map/file-routes.json`",
+        "- `.polaris/map/index.json`",
+        "- `.polaris/map/needs-review.json`",
+        "",
+        "These paths appear only in prohibition lists.",
+        "",
+        "---",
+        "",
+        "## Tracker-Agnostic Work Intake",
+        "",
+        "Work identifiers are opaque to the model. Polaris is tracker-agnostic.",
+        "",
+        "Work may originate from Linear, GitHub, a SmartDocs spec, a local work contract,",
+        "a manual prompt, or a future provider. The runtime resolves identifiers.",
+        "The model does not interpret or construct cluster identifiers.",
+        "",
+        "---",
+        "",
+        "## Runtime Boundaries",
+        "",
+        "- Resolve execution state before beginning work",
+        "- Follow the active cluster and child ordering",
+        "- Execute only the currently assigned child",
+        "- Do not expand scope outside the assigned child",
+        "- If blocked, stop and report the unblock condition",
+        "- Foreman orchestrates; Worker implements; Librarian reconciles",
+        "- A provider may occupy multiple roles, but role authority does not merge",
+        "",
+        "---",
+        "",
+        "## Canon Discovery",
+        "",
+        "Project canon is route-local.",
+        "",
+        "Use:",
+        "- `POLARIS.md` in the relevant route folder for operational guidance",
+        "- `SUMMARY.md` in the relevant route folder for informational context",
+        "- `polaris map query <path>` for route and ownership resolution",
+        "- Runtime state artifacts for execution state and resume handling",
+        "",
+        "Do not assume global repository context unless explicitly provided by the runtime.",
+        "",
+    ].join("\n");
+    const dir = (0, node_path_1.dirname)(outputPath);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(outputPath, content, "utf-8");
+}

package/dist/cli/adopt-scan.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanRepo = scanRepo;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const adoption_inventory_js_1 = require("./adoption-inventory.js");
+function readExistingInventory(repoRoot) {
+    const inventoryPath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-inventory.json");
+    if (!(0, node_fs_1.existsSync)(inventoryPath)) {
+        return null;
+    }
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(inventoryPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function scanRepo(repoRoot, options = {}) {
+    const existingInventory = options.rescan ? null : readExistingInventory(repoRoot);
+    if (existingInventory) {
+        return existingInventory;
+    }
+    return (0, adoption_inventory_js_1.scanAdoptionInventory)(repoRoot, { now: options.now, writeArtifact: true });
+}

package/dist/cli/adopt-smartdocs.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateSmartDocs = migrateSmartDocs;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const COMPLETE_STATUSES = new Set(["completed", "skipped"]);
+function isExcludedSourcePath(sourcePath) {
+    const normalized = sourcePath.replaceAll("\\", "/");
+    const basenameOnly = (0, node_path_1.basename)(normalized);
+    if (["README.md", "CHANGELOG.md", "LICENSE", "CONTRIBUTING.md"].includes(basenameOnly)) {
+        return true;
+    }
+    if (normalized === "smartdocs" ||
+        normalized.startsWith("smartdocs/") ||
+        normalized.startsWith("test/") ||
+        normalized.includes("/test/") ||
+        normalized.startsWith("fixtures/") ||
+        normalized.includes("/fixtures/") ||
+        normalized.startsWith("__mocks__/") ||
+        normalized.includes("/__mocks__/") ||
+        normalized.startsWith("generated/") ||
+        normalized.includes("/generated/") ||
+        normalized.startsWith("dist/") ||
+        normalized.includes("/dist/") ||
+        normalized.startsWith("build/") ||
+        normalized.includes("/build/") ||
+        normalized.startsWith("coverage/") ||
+        normalized.includes("/coverage/")) {
+        return true;
+    }
+    return false;
+}
+function loadPlan(repoRoot, fallback) {
+    const planPath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-plan.json");
+    if (!(0, node_fs_1.existsSync)(planPath)) {
+        return fallback;
+    }
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(planPath, "utf-8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+function savePlan(repoRoot, plan) {
+    const planPath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-plan.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(planPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(planPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
+}
+function loadExistingProvenance(repoRoot) {
+    const provenancePath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-provenance.json");
+    if (!(0, node_fs_1.existsSync)(provenancePath)) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(provenancePath, "utf-8"));
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through and rewrite a clean provenance file.
+    }
+    return {};
+}
+function saveProvenance(repoRoot, records) {
+    if (records.length === 0) {
+        return;
+    }
+    const provenancePath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-provenance.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(provenancePath), { recursive: true });
+    const existing = loadExistingProvenance(repoRoot);
+    const prior = Array.isArray(existing.smartdocs_migrations) ? existing.smartdocs_migrations : [];
+    const updated = {
+        ...existing,
+        updated_at: new Date().toISOString(),
+        smartdocs_migrations: [...prior, ...records],
+    };
+    (0, node_fs_1.writeFileSync)(provenancePath, `${JSON.stringify(updated, null, 2)}\n`, "utf-8");
+}
+function recordKey(record) {
+    return `${record.step_id}:${record.source_path}:${record.dest_path}`;
+}
+function existingRecordKeys(repoRoot) {
+    const provenance = loadExistingProvenance(repoRoot);
+    const records = Array.isArray(provenance.smartdocs_migrations) ? provenance.smartdocs_migrations : [];
+    const keys = new Set();
+    for (const record of records) {
+        if (typeof record === "object" &&
+            record !== null &&
+            !Array.isArray(record) &&
+            typeof record.step_id === "string" &&
+            typeof record.source_path === "string" &&
+            typeof record.dest_path === "string") {
+            keys.add(recordKey({
+                step_id: record.step_id,
+                source_path: record.source_path,
+                dest_path: record.dest_path,
+            }));
+        }
+    }
+    return keys;
+}
+function normalizeStatus(step, status, completedAt) {
+    return {
+        ...step,
+        status,
+        completed_at: completedAt ?? step.completed_at,
+        error: status === "completed" || status === "skipped" ? undefined : step.error,
+    };
+}
+function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd())) {
+    const effectivePlan = loadPlan(repoRoot, plan);
+    const provenanceRecords = [];
+    const seenRecords = existingRecordKeys(repoRoot);
+    const now = new Date().toISOString();
+    for (let index = 0; index < effectivePlan.steps.length; index += 1) {
+        const step = effectivePlan.steps[index];
+        if (step.category !== "smartdocs-migrate" || COMPLETE_STATUSES.has(step.status)) {
+            continue;
+        }
+        const sourcePath = step.source_path ?? "";
+        const destPath = step.dest_path ?? `smartdocs/raw/${(0, node_path_1.basename)(sourcePath || `step-${step.order}.md`)}`;
+        if (!sourcePath) {
+            effectivePlan.steps[index] = normalizeStatus(step, "skipped", now);
+            continue;
+        }
+        if (isExcludedSourcePath(sourcePath)) {
+            effectivePlan.steps[index] = normalizeStatus(step, "skipped", now);
+            continue;
+        }
+        const sourceAbs = (0, node_path_1.join)(repoRoot, sourcePath);
+        const destAbs = (0, node_path_1.join)(repoRoot, destPath);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(destAbs), { recursive: true });
+        if (!(0, node_fs_1.existsSync)(sourceAbs)) {
+            if ((0, node_fs_1.existsSync)(destAbs)) {
+                effectivePlan.steps[index] = normalizeStatus(step, "completed", step.completed_at ?? now);
+                const record = {
+                    step_id: step.step_id,
+                    source_path: sourcePath,
+                    dest_path: destPath,
+                    migrated_at: step.completed_at ?? now,
+                    migration_run_id: effectivePlan.plan_id,
+                    transport: "reconciled",
+                };
+                if (!seenRecords.has(recordKey(record))) {
+                    provenanceRecords.push(record);
+                    seenRecords.add(recordKey(record));
+                }
+            }
+            else {
+                effectivePlan.steps[index] = {
+                    ...step,
+                    status: "skipped",
+                    completed_at: now,
+                    error: `source missing: ${sourcePath}`,
+                };
+            }
+            continue;
+        }
+        let transport = "git mv";
+        try {
+            (0, node_child_process_1.execFileSync)("git", ["mv", "--", sourcePath, destPath], {
+                cwd: repoRoot,
+                stdio: "pipe",
+            });
+        }
+        catch {
+            process.stdout.write(`SmartDocs git mv failed for ${sourcePath}; falling back to fs.rename().\n`);
+            (0, node_fs_1.renameSync)(sourceAbs, destAbs);
+            transport = "fs.rename";
+        }
+        const record = {
+            step_id: step.step_id,
+            source_path: sourcePath,
+            dest_path: destPath,
+            migrated_at: now,
+            migration_run_id: effectivePlan.plan_id,
+            transport,
+        };
+        effectivePlan.steps[index] = normalizeStatus(step, "completed", now);
+        if (!seenRecords.has(recordKey(record))) {
+            provenanceRecords.push(record);
+            seenRecords.add(recordKey(record));
+        }
+    }
+    savePlan(repoRoot, effectivePlan);
+    saveProvenance(repoRoot, provenanceRecords);
+    Object.assign(plan, effectivePlan);
+    return Promise.resolve();
+}