@lsctech/polaris 0.1.0

package/dist/docs/doctrine.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANDIDATE_MARKER = void 0;
+exports.doctrineDraft = doctrineDraft;
+exports.doctrinePromote = doctrinePromote;
+exports.doctrineDeprecate = doctrineDeprecate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.CANDIDATE_MARKER = "<!-- polaris:doctrine-candidate -->";
+function generateRunId() {
+    return `polaris-doctrine-${new Date().toISOString().slice(0, 10)}-001`;
+}
+function lifecycleFilePath(repoRoot, runId) {
+    return (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-doctrine", runId, "lifecycle.jsonl");
+}
+function appendLifecycle(lifecyclePath, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(lifecyclePath), { recursive: true });
+    (0, node_fs_1.appendFileSync)(lifecyclePath, JSON.stringify(event) + "\n", "utf-8");
+}
+function resolvePath(path, repoRoot) {
+    if (path.startsWith("/"))
+        return path;
+    return (0, node_path_1.join)((0, node_path_1.resolve)(repoRoot), path);
+}
+/** Move a doc from docs/raw/ or docs/doctrine/raw/ to docs/doctrine/candidate/ */
+function doctrineDraft(path, options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const runId = options.runId ?? generateRunId();
+    const source = resolvePath(path, repoRoot);
+    if (!(0, node_fs_1.existsSync)(source)) {
+        throw new Error(`Source file not found: ${source}`);
+    }
+    const rawDir = (0, node_path_1.resolve)(repoRoot, "docs", "raw");
+    const doctrineRawDir = (0, node_path_1.resolve)(repoRoot, "docs", "doctrine", "raw");
+    const relToRaw = (0, node_path_1.relative)(rawDir, source);
+    const relToDoctrineRaw = (0, node_path_1.relative)(doctrineRawDir, source);
+    const isInRaw = !relToRaw.startsWith("..") && !relToRaw.startsWith("/");
+    const isInDoctrineRaw = !relToDoctrineRaw.startsWith("..") && !relToDoctrineRaw.startsWith("/");
+    if (!isInRaw && !isInDoctrineRaw) {
+        throw new Error(`doctrineDraft source must be in docs/raw/ or docs/doctrine/raw/ — got: ${source}`);
+    }
+    const candidateDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate");
+    (0, node_fs_1.mkdirSync)(candidateDir, { recursive: true });
+    const destination = (0, node_path_1.join)(candidateDir, (0, node_path_1.basename)(source));
+    if ((0, node_fs_1.existsSync)(destination)) {
+        throw new Error(`Destination already exists: ${destination}`);
+    }
+    const content = (0, node_fs_1.readFileSync)(source, "utf-8");
+    (0, node_fs_1.writeFileSync)(destination, `${exports.CANDIDATE_MARKER}\n${content}`, "utf-8");
+    (0, node_fs_1.unlinkSync)(source);
+    const lifecyclePath = lifecycleFilePath(repoRoot, runId);
+    appendLifecycle(lifecyclePath, {
+        event: "doctrine-draft",
+        run_id: runId,
+        source,
+        destination,
+        timestamp: new Date().toISOString(),
+    });
+    return { source, destination, runId, lifecyclePath };
+}
+/** Move a doc from docs/doctrine/candidate/ to docs/doctrine/active/ */
+function doctrinePromote(path, options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const runId = options.runId ?? generateRunId();
+    const source = resolvePath(path, repoRoot);
+    if (!(0, node_fs_1.existsSync)(source)) {
+        throw new Error(`Source file not found: ${source}`);
+    }
+    const candidateDir = (0, node_path_1.resolve)(repoRoot, "docs", "doctrine", "candidate");
+    const relToCandidate = (0, node_path_1.relative)(candidateDir, source);
+    const isInCandidate = !relToCandidate.startsWith("..") && !relToCandidate.startsWith("/");
+    if (!isInCandidate) {
+        throw new Error(`doctrinePromote source must be in docs/doctrine/candidate/ — got: ${source}`);
+    }
+    const content = (0, node_fs_1.readFileSync)(source, "utf-8");
+    if (!content.includes(exports.CANDIDATE_MARKER)) {
+        throw new Error(`File is not in candidate state (missing ${exports.CANDIDATE_MARKER}): ${source}`);
+    }
+    const activeDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active");
+    (0, node_fs_1.mkdirSync)(activeDir, { recursive: true });
+    const destination = (0, node_path_1.join)(activeDir, (0, node_path_1.basename)(source));
+    if ((0, node_fs_1.existsSync)(destination)) {
+        throw new Error(`Destination already exists: ${destination}`);
+    }
+    const activeContent = content.replace(`${exports.CANDIDATE_MARKER}\n`, "").replace(exports.CANDIDATE_MARKER, "");
+    (0, node_fs_1.writeFileSync)(destination, activeContent, "utf-8");
+    (0, node_fs_1.unlinkSync)(source);
+    const lifecyclePath = lifecycleFilePath(repoRoot, runId);
+    appendLifecycle(lifecyclePath, {
+        event: "doctrine-promote",
+        run_id: runId,
+        source,
+        destination,
+        timestamp: new Date().toISOString(),
+    });
+    return { source, destination, runId, lifecyclePath };
+}
+/** Move a doc from docs/doctrine/active/ to docs/doctrine/deprecated/ */
+function doctrineDeprecate(path, options) {
+    const repoRoot = (0, node_path_1.resolve)(options.repoRoot);
+    const runId = options.runId ?? generateRunId();
+    const source = resolvePath(path, repoRoot);
+    if (!(0, node_fs_1.existsSync)(source)) {
+        throw new Error(`Source file not found: ${source}`);
+    }
+    const activeDir = (0, node_path_1.resolve)(repoRoot, "docs", "doctrine", "active");
+    const relToActive = (0, node_path_1.relative)(activeDir, source);
+    const isInActive = !relToActive.startsWith("..") && !relToActive.startsWith("/");
+    if (!isInActive) {
+        throw new Error(`doctrineDeprecate source must be in docs/doctrine/active/ — got: ${source}`);
+    }
+    const deprecatedDir = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "deprecated");
+    (0, node_fs_1.mkdirSync)(deprecatedDir, { recursive: true });
+    const destination = (0, node_path_1.join)(deprecatedDir, (0, node_path_1.basename)(source));
+    if ((0, node_fs_1.existsSync)(destination)) {
+        throw new Error(`Destination already exists: ${destination}`);
+    }
+    const content = (0, node_fs_1.readFileSync)(source, "utf-8");
+    const deprecatedAt = new Date().toISOString();
+    const deprecatedContent = `<!-- polaris:doctrine-deprecated deprecatedAt="${deprecatedAt}" runId="${runId}" -->\n${content}`;
+    (0, node_fs_1.writeFileSync)(destination, deprecatedContent, "utf-8");
+    (0, node_fs_1.unlinkSync)(source);
+    const lifecyclePath = lifecycleFilePath(repoRoot, runId);
+    appendLifecycle(lifecyclePath, {
+        event: "doctrine-deprecate",
+        run_id: runId,
+        source,
+        destination,
+        deprecated_at: deprecatedAt,
+        timestamp: deprecatedAt,
+    });
+    return { source, destination, runId, lifecyclePath };
+}

package/dist/docs/doctrine.test.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const vitest_1 = require("vitest");
+const doctrine_js_1 = require("./doctrine.js");
+function makeTempDir() {
+    const root = (0, node_fs_2.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-doctrine-"));
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, "docs", "raw"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, "docs", "doctrine", "raw"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, "docs", "doctrine", "candidate"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, "docs", "doctrine", "active"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, "docs", "doctrine", "deprecated"), { recursive: true });
+    return root;
+}
+(0, vitest_1.describe)("doctrineDraft", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeTempDir();
+    });
+    (0, vitest_1.it)("moves a file from docs/raw/ to docs/doctrine/candidate/ with candidate marker", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "raw", "some-doc.md");
+        (0, node_fs_1.writeFileSync)(source, "# Some Doc\n\nContent here.");
+        const result = (0, doctrine_js_1.doctrineDraft)(source, { repoRoot, runId: "test-run-001" });
+        (0, vitest_1.expect)(result.destination).toBe((0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "some-doc.md"));
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(result.destination)).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(source)).toBe(false);
+        const content = (0, node_fs_1.readFileSync)(result.destination, "utf-8");
+        (0, vitest_1.expect)(content.startsWith(doctrine_js_1.CANDIDATE_MARKER)).toBe(true);
+        (0, vitest_1.expect)(content).toContain("# Some Doc");
+    });
+    (0, vitest_1.it)("moves a file from docs/doctrine/raw/ to docs/doctrine/candidate/", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "raw", "draft-doc.md");
+        (0, node_fs_1.writeFileSync)(source, "# Draft");
+        const result = (0, doctrine_js_1.doctrineDraft)(source, { repoRoot, runId: "test-run-001" });
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(result.destination)).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(source)).toBe(false);
+    });
+    (0, vitest_1.it)("emits a doctrine-draft event to lifecycle.jsonl", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "raw", "event-doc.md");
+        (0, node_fs_1.writeFileSync)(source, "# Event Doc");
+        const result = (0, doctrine_js_1.doctrineDraft)(source, { repoRoot, runId: "test-run-001" });
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(result.lifecyclePath)).toBe(true);
+        const event = JSON.parse((0, node_fs_1.readFileSync)(result.lifecyclePath, "utf-8").trim().split("\n")[0]);
+        (0, vitest_1.expect)(event.event).toBe("doctrine-draft");
+        (0, vitest_1.expect)(event.run_id).toBe("test-run-001");
+        (0, vitest_1.expect)(event.source).toBe(source);
+        (0, vitest_1.expect)(event.destination).toBe(result.destination);
+    });
+    (0, vitest_1.it)("throws if source does not exist", () => {
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrineDraft)((0, node_path_1.join)(repoRoot, "docs", "raw", "nonexistent.md"), { repoRoot })).toThrow("Source file not found");
+    });
+    (0, vitest_1.it)("throws if source is not in docs/raw/ or docs/doctrine/raw/", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active", "wrong.md");
+        (0, node_fs_1.writeFileSync)(source, "# Wrong location");
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrineDraft)(source, { repoRoot })).toThrow("doctrineDraft source must be in docs/raw/ or docs/doctrine/raw/");
+    });
+    (0, vitest_1.it)("throws if destination already exists", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "raw", "dupe.md");
+        (0, node_fs_1.writeFileSync)(source, "# Dupe");
+        const dest = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "dupe.md");
+        (0, node_fs_1.writeFileSync)(dest, "# Already there");
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrineDraft)(source, { repoRoot })).toThrow("Destination already exists");
+    });
+});
+(0, vitest_1.describe)("doctrinePromote", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeTempDir();
+    });
+    (0, vitest_1.it)("moves a file from candidate/ to active/ and strips the candidate marker", () => {
+        const candidatePath = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "my-doctrine.md");
+        (0, node_fs_1.writeFileSync)(candidatePath, `${doctrine_js_1.CANDIDATE_MARKER}\n# My Doctrine\n\nContent.`);
+        const result = (0, doctrine_js_1.doctrinePromote)(candidatePath, { repoRoot, runId: "test-run-002" });
+        (0, vitest_1.expect)(result.destination).toBe((0, node_path_1.join)(repoRoot, "docs", "doctrine", "active", "my-doctrine.md"));
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(result.destination)).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(candidatePath)).toBe(false);
+        const content = (0, node_fs_1.readFileSync)(result.destination, "utf-8");
+        (0, vitest_1.expect)(content).not.toContain(doctrine_js_1.CANDIDATE_MARKER);
+        (0, vitest_1.expect)(content).toContain("# My Doctrine");
+    });
+    (0, vitest_1.it)("emits a doctrine-promote event to lifecycle.jsonl", () => {
+        const candidatePath = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "promoted.md");
+        (0, node_fs_1.writeFileSync)(candidatePath, `${doctrine_js_1.CANDIDATE_MARKER}\n# Promoted`);
+        const result = (0, doctrine_js_1.doctrinePromote)(candidatePath, { repoRoot, runId: "test-run-002" });
+        const event = JSON.parse((0, node_fs_1.readFileSync)(result.lifecyclePath, "utf-8").trim().split("\n")[0]);
+        (0, vitest_1.expect)(event.event).toBe("doctrine-promote");
+        (0, vitest_1.expect)(event.run_id).toBe("test-run-002");
+    });
+    (0, vitest_1.it)("throws if source is not in docs/doctrine/candidate/", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "raw", "wrong.md");
+        (0, node_fs_1.writeFileSync)(source, `${doctrine_js_1.CANDIDATE_MARKER}\n# Wrong`);
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrinePromote)(source, { repoRoot })).toThrow("doctrinePromote source must be in docs/doctrine/candidate/");
+    });
+    (0, vitest_1.it)("throws if file is missing the candidate marker", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "unmarked.md");
+        (0, node_fs_1.writeFileSync)(source, "# No marker");
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrinePromote)(source, { repoRoot })).toThrow("not in candidate state");
+    });
+    (0, vitest_1.it)("throws if source does not exist", () => {
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrinePromote)((0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "ghost.md"), { repoRoot })).toThrow("Source file not found");
+    });
+});
+(0, vitest_1.describe)("doctrineDeprecate", () => {
+    let repoRoot;
+    (0, vitest_1.beforeEach)(() => {
+        repoRoot = makeTempDir();
+    });
+    (0, vitest_1.it)("moves a file from active/ to deprecated/ with deprecation provenance header", () => {
+        const activePath = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active", "old-doctrine.md");
+        (0, node_fs_1.writeFileSync)(activePath, "# Old Doctrine\n\nOriginal content.");
+        const result = (0, doctrine_js_1.doctrineDeprecate)(activePath, { repoRoot, runId: "test-run-003" });
+        (0, vitest_1.expect)(result.destination).toBe((0, node_path_1.join)(repoRoot, "docs", "doctrine", "deprecated", "old-doctrine.md"));
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(result.destination)).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(activePath)).toBe(false);
+        const content = (0, node_fs_1.readFileSync)(result.destination, "utf-8");
+        (0, vitest_1.expect)(content).toContain("polaris:doctrine-deprecated");
+        (0, vitest_1.expect)(content).toContain("# Old Doctrine");
+    });
+    (0, vitest_1.it)("emits a doctrine-deprecate event to lifecycle.jsonl", () => {
+        const activePath = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "active", "deprecated.md");
+        (0, node_fs_1.writeFileSync)(activePath, "# Deprecated");
+        const result = (0, doctrine_js_1.doctrineDeprecate)(activePath, { repoRoot, runId: "test-run-003" });
+        const event = JSON.parse((0, node_fs_1.readFileSync)(result.lifecyclePath, "utf-8").trim().split("\n")[0]);
+        (0, vitest_1.expect)(event.event).toBe("doctrine-deprecate");
+        (0, vitest_1.expect)(event.run_id).toBe("test-run-003");
+        (0, vitest_1.expect)(event.deprecated_at).toBeDefined();
+    });
+    (0, vitest_1.it)("throws if source is not in docs/doctrine/active/", () => {
+        const source = (0, node_path_1.join)(repoRoot, "docs", "doctrine", "candidate", "wrong.md");
+        (0, node_fs_1.writeFileSync)(source, `${doctrine_js_1.CANDIDATE_MARKER}\n# Wrong`);
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrineDeprecate)(source, { repoRoot })).toThrow("doctrineDeprecate source must be in docs/doctrine/active/");
+    });
+    (0, vitest_1.it)("throws if source does not exist", () => {
+        (0, vitest_1.expect)(() => (0, doctrine_js_1.doctrineDeprecate)((0, node_path_1.join)(repoRoot, "docs", "doctrine", "active", "ghost.md"), { repoRoot })).toThrow("Source file not found");
+    });
+});

package/dist/docs/index.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDocsCommand = createDocsCommand;
+exports.createDoctrineCommand = createDoctrineCommand;
+const commander_1 = require("commander");
+const ingest_js_1 = require("./ingest.js");
+const migrate_js_1 = require("./migrate.js");
+const seed_instructions_js_1 = require("./seed-instructions.js");
+const validate_instructions_js_1 = require("./validate-instructions.js");
+const doctrine_js_1 = require("./doctrine.js");
+function createDocsCommand() {
+    const docs = new commander_1.Command("docs").description("Polaris docs lifecycle commands");
+    docs
+        .command("ingest [path]")
+        .description("Classify and place docs into the Polaris docs authority structure")
+        .option("--file <path>", "Single file to ingest")
+        .option("--cluster <id>", "Cluster ID for bounded batch provenance")
+        .option("--files <paths...>", "Bounded batch file list")
+        .option("--dry-run", "Classify and report without moving files")
+        .option("--approve-authority", "Allow placement in high-authority docs areas")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .action((pathArg, options) => {
+        const files = options.files ?? (options.file ? [options.file] : pathArg ? [pathArg] : []);
+        try {
+            const results = (0, ingest_js_1.ingestDocs)(files, {
+                repoRoot: options.repoRoot,
+                dryRun: options.dryRun,
+                clusterId: options.cluster,
+                approveAuthority: options.approveAuthority,
+            });
+            (0, ingest_js_1.printIngestResults)(results);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    docs
+        .command("migrate")
+        .description("Find scattered markdown files, move them to docs/raw/, and produce an ingest cluster list")
+        .option("--dry-run", "Show plan without moving files")
+        .option("--migration-run-id <id>", "Override the generated migration run ID")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .action((options) => {
+        try {
+            const result = (0, migrate_js_1.migrateDocs)({
+                repoRoot: options.repoRoot,
+                dryRun: options.dryRun,
+                migrationRunId: options.migrationRunId,
+            });
+            (0, migrate_js_1.printMigrateResults)(result);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    docs
+        .command("seed-instructions [path]")
+        .description("Generate a draft POLARIS.md for a directory using atlas signals")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .option("--all", "Generate drafts for all directories lacking a POLARIS.md")
+        .option("--dry-run", "Print what would be written without writing files")
+        .action((pathArg, options) => {
+        if (options.all) {
+            const { written, skippedExists, skippedDraft } = (0, seed_instructions_js_1.seedInstructionsAll)(options.repoRoot, { dryRun: options.dryRun });
+            for (const dir of written) {
+                console.log(`${options.dryRun ? "[dry-run] would write" : "written"}: ${dir}/POLARIS.md`);
+            }
+            for (const dir of skippedExists) {
+                console.log(`skipped (human-edited): ${dir}/POLARIS.md`);
+            }
+            for (const dir of skippedDraft) {
+                console.log(`skipped (draft exists): ${dir}/POLARIS.md`);
+            }
+            console.log(`\nDone. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft).`);
+            return;
+        }
+        if (!pathArg) {
+            console.error("Error: provide a <path> argument or use --all");
+            process.exit(1);
+        }
+        const result = (0, seed_instructions_js_1.seedInstructions)(pathArg, options.repoRoot, { dryRun: options.dryRun });
+        if (result === "written") {
+            const label = options.dryRun ? "[dry-run] would write" : "written";
+            console.log(`${label}: ${pathArg}/POLARIS.md`);
+        }
+        else if (result === "skipped-exists") {
+            console.warn(`warning: ${pathArg}/POLARIS.md already exists (no draft marker) — skipped`);
+        }
+        else {
+            console.log(`skipped (draft exists): ${pathArg}/POLARIS.md`);
+        }
+    });
+    docs
+        .command("validate-instructions")
+        .description("Check all POLARIS.md files for staleness, broken links, and missing coverage")
+        .option("--path <dir>", "Validate only the given directory")
+        .option("--fix", "Write POLARIS.draft.md for stale or missing files")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .action((options) => {
+        const report = (0, validate_instructions_js_1.validateInstructions)({
+            path: options.path,
+            fix: options.fix,
+            repoRoot: options.repoRoot,
+        });
+        (0, validate_instructions_js_1.printReport)(report);
+        if (report.hasErrors) {
+            process.exit(1);
+        }
+    });
+    return docs;
+}
+function createDoctrineCommand() {
+    const doctrine = new commander_1.Command("doctrine").description("Polaris doctrine lifecycle commands");
+    doctrine
+        .command("draft <path>")
+        .description("Move a doc from docs/raw/ or docs/doctrine/raw/ to docs/doctrine/candidate/")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .option("--run-id <id>", "Override the generated doctrine run ID")
+        .action((path, options) => {
+        try {
+            const result = (0, doctrine_js_1.doctrineDraft)(path, { repoRoot: options.repoRoot, runId: options.runId });
+            console.log(`drafted: ${result.destination}`);
+            console.log(`provenance: ${result.lifecyclePath}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    doctrine
+        .command("promote <path>")
+        .description("Move a doc from docs/doctrine/candidate/ to docs/doctrine/active/")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .option("--run-id <id>", "Override the generated doctrine run ID")
+        .action((path, options) => {
+        try {
+            const result = (0, doctrine_js_1.doctrinePromote)(path, { repoRoot: options.repoRoot, runId: options.runId });
+            console.log(`promoted: ${result.destination}`);
+            console.log(`provenance: ${result.lifecyclePath}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    doctrine
+        .command("deprecate <path>")
+        .description("Move a doc from docs/doctrine/active/ to docs/doctrine/deprecated/")
+        .option("-r, --repo-root <path>", "Repository root", process.cwd())
+        .option("--run-id <id>", "Override the generated doctrine run ID")
+        .action((path, options) => {
+        try {
+            const result = (0, doctrine_js_1.doctrineDeprecate)(path, {
+                repoRoot: options.repoRoot,
+                runId: options.runId,
+            });
+            console.log(`deprecated: ${result.destination}`);
+            console.log(`provenance: ${result.lifecyclePath}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return doctrine;
+}

package/dist/docs/index.test.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_fs_2 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const vitest_1 = require("vitest");
+const ingest_js_1 = require("./ingest.js");
+const index_js_1 = require("./index.js");
+function makeRepo() {
+    const repoRoot = (0, node_fs_2.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "polaris-docs-init-"));
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, ".polaris", "map"), { recursive: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "docs", "raw"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "polaris.config.json"), JSON.stringify({ repo: { sidecarOutputPath: ".polaris/map" } }), "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".polaris", "map", "file-routes.json"), "{}\n", "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, ".polaris", "map", "needs-review.json"), "{}\n", "utf-8");
+    return repoRoot;
+}
+function configureForTest(command, output) {
+    command.exitOverride();
+    command.configureOutput({
+        writeOut: (value) => {
+            output.stdout += value;
+        },
+        writeErr: (value) => {
+            output.stderr += value;
+        },
+    });
+    for (const subcommand of command.commands) {
+        configureForTest(subcommand, output);
+    }
+}
+async function runDocsCommand(repoRoot, argv) {
+    const output = { stdout: "", stderr: "" };
+    const command = (0, index_js_1.createDocsCommand)({ repoRoot });
+    configureForTest(command, output);
+    const log = vitest_1.vi.spyOn(console, "log").mockImplementation((value = "") => {
+        output.stdout += `${String(value)}\n`;
+    });
+    const warn = vitest_1.vi.spyOn(console, "warn").mockImplementation((value = "") => {
+        output.stderr += `${String(value)}\n`;
+    });
+    const error = vitest_1.vi.spyOn(console, "error").mockImplementation((value = "") => {
+        output.stderr += `${String(value)}\n`;
+    });
+    try {
+        await command.parseAsync(["node", "polaris", ...argv], { from: "node" });
+    }
+    finally {
+        log.mockRestore();
+        warn.mockRestore();
+        error.mockRestore();
+    }
+    return output;
+}
+(0, vitest_1.describe)("docs init command", () => {
+    (0, vitest_1.it)("dry-runs the Smart Docs scaffold without creating directories", async () => {
+        const repoRoot = makeRepo();
+        const output = await runDocsCommand(repoRoot, ["init", "--dry-run"]);
+        (0, vitest_1.expect)(output.stdout).toContain("[dry-run] would create");
+        (0, vitest_1.expect)(output.stdout).toContain(`${ingest_js_1.CANONICAL_TARGET}/specs/raw`);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ingest_js_1.CANONICAL_TARGET))).toBe(false);
+    });
+    (0, vitest_1.it)("creates the Smart Docs scaffold and is idempotent", async () => {
+        const repoRoot = makeRepo();
+        const first = await runDocsCommand(repoRoot, ["init"]);
+        const second = await runDocsCommand(repoRoot, ["init"]);
+        (0, vitest_1.expect)(first.stdout).toContain("created");
+        (0, vitest_1.expect)(first.stdout).toContain(`${ingest_js_1.CANONICAL_TARGET}/doctrine/active`);
+        (0, vitest_1.expect)(second.stdout).toContain("already exists");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ingest_js_1.CANONICAL_TARGET, "runtime", "summaries"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ingest_js_1.CANONICAL_TARGET, "specs", "raw"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ingest_js_1.CANONICAL_TARGET, "doctrine", "active"))).toBe(true);
+    });
+    (0, vitest_1.it)("unblocks docs ingest after initialization", async () => {
+        const repoRoot = makeRepo();
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(repoRoot, "docs", "raw", "smart-docs.md"), "# Smart Docs Spec\n\nAcceptance Criteria\n", "utf-8");
+        await runDocsCommand(repoRoot, ["init"]);
+        const output = await runDocsCommand(repoRoot, ["ingest", "--file", "docs/raw/smart-docs.md"]);
+        (0, vitest_1.expect)(output.stdout).toContain(`${ingest_js_1.CANONICAL_TARGET}/specs/raw/smart-docs.md`);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(repoRoot, ingest_js_1.CANONICAL_TARGET, "specs", "raw", "smart-docs.md"))).toBe(true);
+    });
+});