@lsctech/polaris 0.4.5 → 0.4.7

package/dist/cli/adopt-command.js

@@ -140,8 +140,9 @@ async function runAdoptPhase(phase, repoRoot, options = {}) {
             if (!options.inventory || !options.plan) {
                 throw new Error("consolidate requires inventory and plan");
             }
+            const dryRun = options.plan.dry_run ?? options.dryRun ?? false;
             await (0, adopt_smartdocs_js_1.migrateSmartDocs)(options.plan, repoRoot);
-            await (0, adopt_genesis_js_1.reconcileAgentFiles)(repoRoot);
+            await (0, adopt_genesis_js_1.reconcileAgentFiles)(repoRoot, { dryRun });
             break;
         }
         case "map": {

package/dist/cli/adopt-genesis.js

@@ -25,7 +25,9 @@ function isAlreadyPointer(content) {
     });
     return meaningfulLines.length <= 3 && meaningfulLines.some((line) => line.includes("POLARIS_RULES.md"));
 }
-function appendGenesisProvenance(repoRoot, records) {
+function appendGenesisProvenance(repoRoot, records, dryRun = false) {
+    if (dryRun)
+        return;
     if (records.length === 0)
         return;
     const provenancePath = (0, node_path_1.join)(repoRoot, ".polaris", "adoption-provenance.json");
@@ -57,6 +59,7 @@ async function reconcileAgentFiles(repoRoot, options) {
     const provenanceRecords = [];
     const now = options?.now ?? new Date();
     const timestamp = now.toISOString();
+    const dryRun = options?.dryRun ?? false;
     for (const file of AGENT_FILES) {
         const filePath = (0, node_path_1.join)(repoRoot, file);
         if (!(0, node_fs_1.existsSync)(filePath)) {
@@ -74,6 +77,11 @@ async function reconcileAgentFiles(repoRoot, options) {
             });
             continue;
         }
+        if (dryRun) {
+            process.stdout.write(`[dry-run] would prompt to compress and archive ${file} as genesis doctrine\n`);
+            results.push({ file, outcome: "skipped" });
+            continue;
+        }
         const rl = (0, promises_1.createInterface)({ input: process.stdin, output: process.stdout });
         let answer;
         try {
@@ -146,11 +154,13 @@ async function reconcileAgentFiles(repoRoot, options) {
         const dateStr = formatDate(now);
         const genesisPath = `smartdocs/doctrine/active/${dateStr}-genesis-agent-doctrine.md`;
         const genesisFullPath = (0, node_path_1.join)(repoRoot, genesisPath);
-        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "smartdocs/doctrine/active"), { recursive: true });
-        (0, node_fs_1.writeFileSync)(genesisFullPath, distilled, "utf8");
-        const thinPointer = `# Agent Instructions\n\nRead [POLARIS_RULES.md](POLARIS_RULES.md) before beginning any work.\n\n` +
-            `<!-- genesis doctrine archived: ${genesisPath} -->\n`;
-        (0, node_fs_1.writeFileSync)(filePath, thinPointer, "utf8");
+        if (!dryRun) {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(repoRoot, "smartdocs/doctrine/active"), { recursive: true });
+            (0, node_fs_1.writeFileSync)(genesisFullPath, distilled, "utf8");
+            const thinPointer = `# Agent Instructions\n\nRead [POLARIS_RULES.md](POLARIS_RULES.md) before beginning any work.\n\n` +
+                `<!-- genesis doctrine archived: ${genesisPath} -->\n`;
+            (0, node_fs_1.writeFileSync)(filePath, thinPointer, "utf8");
+        }
         results.push({ file, outcome: "compressed", genesisPath });
         provenanceRecords.push({
             source_path: file,
@@ -160,6 +170,6 @@ async function reconcileAgentFiles(repoRoot, options) {
             migration_outcome: "compressed",
         });
     }
-    appendGenesisProvenance(repoRoot, provenanceRecords);
+    appendGenesisProvenance(repoRoot, provenanceRecords, dryRun);
     return results;
 }

package/dist/cli/adopt-smartdocs.js

@@ -113,8 +113,17 @@ function normalizeStatus(step, status, completedAt) {
 }
 const SMARTDOCS_BUNDLE_INDEX_CONTENT = `---\nokf_version: "0.1"\n---\n\n# SmartDocs — Polaris Cognition Bundle\n\n# Governance\n\n- [Docs authority model](specs/active/docs-authority-model.md)\n- [Doctrine](doctrine/active/)\n\n# Routes\n\n<!-- Routes placeholder: dynamic file-routes.json generation deferred. -->\n`;
 const SMARTDOCS_BUNDLE_LOG_CONTENT = "# SmartDocs — Change Log\n";
-function scaffoldBundleRoot(repoRoot) {
+function scaffoldBundleRoot(repoRoot, dryRun = false) {
     const smartdocsDir = (0, node_path_1.join)(repoRoot, "smartdocs");
+    if (dryRun) {
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(smartdocsDir, "index.md"))) {
+            process.stdout.write(`[dry-run] would create smartdocs/index.md\n`);
+        }
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(smartdocsDir, "log.md"))) {
+            process.stdout.write(`[dry-run] would create smartdocs/log.md\n`);
+        }
+        return;
+    }
     (0, node_fs_1.mkdirSync)(smartdocsDir, { recursive: true });
     const indexPath = (0, node_path_1.join)(smartdocsDir, "index.md");
     if (!(0, node_fs_1.existsSync)(indexPath)) {
@@ -130,59 +139,72 @@ function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd(
     const provenanceRecords = [];
     const seenRecords = existingRecordKeys(repoRoot);
     const now = new Date().toISOString();
+    const dryRun = effectivePlan.dry_run ?? false;
     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;
         }
         if (step.routing !== undefined && step.routing !== "candidate") {
-            effectivePlan.steps[index] = {
-                ...step,
-                status: "skipped",
-                completed_at: now,
-                error: `routing not candidate: ${step.routing}`,
-            };
+            if (!dryRun) {
+                effectivePlan.steps[index] = {
+                    ...step,
+                    status: "skipped",
+                    completed_at: now,
+                    error: `routing not candidate: ${step.routing}`,
+                };
+            }
             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);
+            if (!dryRun)
+                effectivePlan.steps[index] = normalizeStatus(step, "skipped", now);
             continue;
         }
         if (isExcludedSourcePath(sourcePath)) {
-            effectivePlan.steps[index] = normalizeStatus(step, "skipped", now);
+            if (!dryRun)
+                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));
+                if (!dryRun) {
+                    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}`,
-                };
+                if (!dryRun) {
+                    effectivePlan.steps[index] = {
+                        ...step,
+                        status: "skipped",
+                        completed_at: now,
+                        error: `source missing: ${sourcePath}`,
+                    };
+                }
             }
             continue;
         }
+        if (dryRun) {
+            process.stdout.write(`[dry-run] would move ${sourcePath} → ${destPath}\n`);
+            continue;
+        }
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(destAbs), { recursive: true });
         let transport = "git mv";
         try {
             (0, node_child_process_1.execFileSync)("git", ["mv", "--", sourcePath, destPath], {
@@ -209,9 +231,11 @@ function migrateSmartDocs(plan, repoRoot = (0, node_path_1.resolve)(process.cwd(
             seenRecords.add(recordKey(record));
         }
     }
-    scaffoldBundleRoot(repoRoot);
-    savePlan(repoRoot, effectivePlan);
-    saveProvenance(repoRoot, provenanceRecords);
-    Object.assign(plan, effectivePlan);
+    scaffoldBundleRoot(repoRoot, dryRun);
+    if (!dryRun) {
+        savePlan(repoRoot, effectivePlan);
+        saveProvenance(repoRoot, provenanceRecords);
+        Object.assign(plan, effectivePlan);
+    }
     return Promise.resolve();
 }

package/dist/cognition/librarian-packet.js

@@ -144,11 +144,11 @@ function generateLibrarianPacket(options) {
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function resolveStateFile(repoRoot, clusterId) {
-    // Check current convention: cluster-state.json
-    const clusterState = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "cluster-state.json");
-    if (node_fs_1.default.existsSync(clusterState))
-        return clusterState;
-    // Check legacy convention: state.json
+    // Note: .polaris/clusters/<id>/cluster-state.json is intentionally not a candidate here.
+    // It holds the ClusterState schema (child_states, packet_pointers, ...), not the LoopState
+    // schema (completed_children, run_id, open_children_meta, ...) that readState()/this
+    // function require.
+    // Check per-cluster run-state convention: state.json
     const legacyState = node_path_1.default.join(repoRoot, ".polaris", "clusters", clusterId, "state.json");
     if (node_fs_1.default.existsSync(legacyState))
         return legacyState;
@@ -160,8 +160,8 @@ function resolveStateFile(repoRoot, clusterId) {
     const legacyRuns = node_path_1.default.join(repoRoot, ".polaris", "runs", "current-state.json");
     if (node_fs_1.default.existsSync(legacyRuns))
         return legacyRuns;
-    // Return current convention path as default
-    return clusterState;
+    // Return per-cluster state path as default
+    return legacyState;
 }
 function findResultFile(resultsDir, childId) {
     try {

package/dist/loop/continue.js

@@ -14,6 +14,8 @@ const canon_check_js_1 = require("../smartdocs-engine/canon-check.js");
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
 const ledger_js_1 = require("./ledger.js");
 const librarian_dispatch_js_1 = require("../cognition/librarian-dispatch.js");
+const index_js_1 = require("../tracker/index.js");
+const lifecycle_transition_js_1 = require("../tracker/lifecycle-transition.js");
 /** Resolves the expected sealed result file path for a child from its dispatch metadata. */
 function resolveResultFileForChild(state, childId) {
     const meta = state.open_children_meta?.[childId];
@@ -206,6 +208,10 @@ function countLoopAbortedEvents(telemetryFile, runId) {
         .filter((event) => event.event === "loop-aborted" && event.run_id === runId)
         .length;
 }
+function appendTelemetryEvent(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
+}
 function resolveTelemetryFilePath(state, repoRoot) {
     const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
     return (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
@@ -430,6 +436,71 @@ function runLoopContinue(options) {
                 process.exit(1);
             }
         }
+        // ── Apply lifecycle transition for child-validation-passed event ───────
+        // Fire-and-forget: tracker mutations must not block state checkpointing.
+        // Policy default targets "in_review" (not "done") — "done" is reserved for
+        // the child-merged event, applied once the delivering PR actually merges.
+        let transitionAdapter;
+        let transitionConfig;
+        const transitionTelemetryFile = resolveTelemetryFilePath(state, repoRoot);
+        try {
+            transitionConfig = (0, loader_js_1.loadConfig)(repoRoot);
+            transitionAdapter = (0, index_js_1.loadTrackerAdapter)(transitionConfig);
+        }
+        catch (err) {
+            appendTelemetryEvent(transitionTelemetryFile, {
+                event: "lifecycle-transition-error",
+                run_id: state.run_id,
+                child_id: completedChild,
+                transition_event: "child-validation-passed",
+                error: `Failed to load config or tracker adapter: ${err instanceof Error ? err.message : String(err)}`,
+                timestamp: new Date().toISOString(),
+            });
+            transitionAdapter = null;
+            transitionConfig = null;
+        }
+        // Note: transitionAdapter may legitimately be null (no tracker adapter configured) —
+        // that's not an error, and applyTransitionSafe/applyTransition handle a null adapter
+        // by returning a skip result. Only skip the attempt entirely when config loading itself
+        // failed (transitionConfig is null).
+        if (transitionConfig) {
+            new lifecycle_transition_js_1.LifecycleTransitionService()
+                .applyTransitionSafe({
+                adapter: transitionAdapter,
+                policy: transitionConfig.tracker?.lifecyclePolicy,
+                taskId: completedChild,
+                event: "child-validation-passed",
+                evidence: {
+                    commit: completionCommit,
+                    validationResults: completionValidation,
+                },
+                timestamp: new Date().toISOString(),
+            })
+                .then((result) => {
+                appendTelemetryEvent(transitionTelemetryFile, {
+                    event: "lifecycle-transition-attempt",
+                    run_id: state.run_id,
+                    child_id: completedChild,
+                    transition_event: result.event,
+                    target_state: result.targetState,
+                    applied: result.applied,
+                    skipped: result.skipped,
+                    skip_reason: result.skipReason,
+                    error: result.error,
+                    timestamp: result.timestamp,
+                });
+            })
+                .catch((err) => {
+                appendTelemetryEvent(transitionTelemetryFile, {
+                    event: "lifecycle-transition-error",
+                    run_id: state.run_id,
+                    child_id: completedChild,
+                    transition_event: "child-validation-passed",
+                    error: err instanceof Error ? err.message : String(err),
+                    timestamp: new Date().toISOString(),
+                });
+            });
+        }
     }
     if (completedChild && completionResultFile) {
         const telemetryFile = resolveTelemetryFilePath(state, repoRoot);

package/dist/smartdocs-engine/index.js

@@ -15,6 +15,29 @@ const audit_js_1 = require("./audit.js");
 const triage_js_1 = require("./triage.js");
 const adapter_js_1 = require("../graph/store/adapter.js");
 const index_js_1 = require("../graph/query/index.js");
+/**
+ * Prints the shared written/skipped-exists/skipped-draft report and summary line used by
+ * every `seed-*-all` command (seed-index, seed-instructions, seed-summary, reformat-okf).
+ *
+ * @param filename - The generated filename (e.g. "index.md") to report against each directory.
+ * @param dryRun - Whether this was a dry-run pass (controls the "would write" vs "written" label).
+ * @param result - The written/skippedExists/skippedDraft arrays from a seed-*-all call.
+ * @param options.leadingBlankLine - Whether to prefix the summary line with a blank line (default true).
+ * @param options.extraSummary - Extra summary text appended after "skipped (draft)" (e.g. root/ineligible counts).
+ */
+function printSeedAllResult(filename, dryRun, { written, skippedExists, skippedDraft }, options = {}) {
+    const { leadingBlankLine = true, extraSummary = "" } = options;
+    for (const dir of written) {
+        console.log(`${dryRun ? "[dry-run] would write" : "written"}: ${dir}/${filename}`);
+    }
+    for (const dir of skippedExists) {
+        console.log(`skipped (human-edited): ${dir}/${filename}`);
+    }
+    for (const dir of skippedDraft) {
+        console.log(`skipped (draft exists): ${dir}/${filename}`);
+    }
+    console.log(`${leadingBlankLine ? "\n" : ""}Done. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft)${extraSummary}.`);
+}
 /**
  * Build and return the top-level "docs" Commander command group for Polaris docs lifecycle workflows.
  *
@@ -283,15 +306,6 @@ function createDocsCommand(options = {}) {
                 includeHidden: options.includeHidden,
                 includeRoot: options.includeRoot,
             });
-            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`);
-            }
             if (options.dryRun) {
                 if (skippedRoot) {
                     console.log(`\nSkipped (root):`);
@@ -315,7 +329,7 @@ function createDocsCommand(options = {}) {
                 }
             }
             const rootCount = skippedRoot ? 1 : 0;
-            console.log(`\nDone. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft), ${rootCount} skipped (root), ${skippedIneligible.length} skipped (ineligible).`);
+            printSeedAllResult("POLARIS.md", options.dryRun, { written, skippedExists, skippedDraft }, { extraSummary: `, ${rootCount} skipped (root), ${skippedIneligible.length} skipped (ineligible)` });
             return;
         }
         if (!pathArg) {
@@ -351,15 +365,6 @@ function createDocsCommand(options = {}) {
                 includeHidden: options.includeHidden,
                 includeRoot: options.includeRoot,
             });
-            for (const dir of written) {
-                console.log(`${options.dryRun ? "[dry-run] would write" : "written"}: ${dir}/SUMMARY.md`);
-            }
-            for (const dir of skippedExists) {
-                console.log(`skipped (human-edited): ${dir}/SUMMARY.md`);
-            }
-            for (const dir of skippedDraft) {
-                console.log(`skipped (draft exists): ${dir}/SUMMARY.md`);
-            }
             if (options.dryRun) {
                 if (skippedRoot) {
                     console.log(`\nSkipped (root):`);
@@ -383,7 +388,7 @@ function createDocsCommand(options = {}) {
                 }
             }
             const rootCount = skippedRoot ? 1 : 0;
-            console.log(`\nDone. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft), ${rootCount} skipped (root), ${skippedIneligible.length} skipped (ineligible).`);
+            printSeedAllResult("SUMMARY.md", options.dryRun, { written, skippedExists, skippedDraft }, { extraSummary: `, ${rootCount} skipped (root), ${skippedIneligible.length} skipped (ineligible)` });
             return;
         }
         if (!pathArg) {
@@ -413,16 +418,7 @@ function createDocsCommand(options = {}) {
             const { written, skippedExists, skippedDraft, } = (0, seed_instructions_js_1.seedIndexAll)(options.repoRoot, {
                 dryRun: options.dryRun,
             });
-            for (const dir of written) {
-                console.log(`${options.dryRun ? "[dry-run] would write" : "written"}: ${dir}/index.md`);
-            }
-            for (const dir of skippedExists) {
-                console.log(`skipped (human-edited): ${dir}/index.md`);
-            }
-            for (const dir of skippedDraft) {
-                console.log(`skipped (draft exists): ${dir}/index.md`);
-            }
-            console.log(`\nDone. ${written.length} written, ${skippedExists.length} skipped (exists), ${skippedDraft.length} skipped (draft).`);
+            printSeedAllResult("index.md", options.dryRun, { written, skippedExists, skippedDraft });
             return;
         }
         const targetPath = pathArg || "smartdocs";
@@ -438,6 +434,50 @@ function createDocsCommand(options = {}) {
             console.log(`skipped (draft exists): ${targetPath}/index.md`);
         }
     });
+    docs
+        .command("reformat-okf")
+        .description("Migrate existing smartdocs to OKF structure in one step: runs migrate → seed-index --all → seed-instructions --all. " +
+        "Agent instruction files (CLAUDE.md, AGENTS.md, etc.) are never touched. " +
+        "Use --dry-run to preview changes before writing.")
+        .option("--dry-run", "Preview what would change without writing any files")
+        .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .action((options) => {
+        const dryRun = options.dryRun;
+        const repoRoot = options.repoRoot;
+        const label = dryRun ? "[dry-run]" : "";
+        // Step 1: migrate (moves scattered markdown to smartdocs/raw/)
+        console.log(`${label ? label + " " : ""}Step 1/3: migrate`);
+        try {
+            const migrateResult = (0, migrate_js_1.migrateDocs)({ repoRoot, dryRun });
+            (0, migrate_js_1.printMigrateResults)(migrateResult);
+        }
+        catch (err) {
+            console.error(`reformat-okf: migrate failed — ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        // Step 2: seed-index --all (ensures index.md with okf_version frontmatter in every smartdocs dir)
+        console.log(`\n${label ? label + " " : ""}Step 2/3: seed-index --all`);
+        try {
+            const { written, skippedExists, skippedDraft } = (0, seed_instructions_js_1.seedIndexAll)(repoRoot, { dryRun });
+            printSeedAllResult("index.md", dryRun, { written, skippedExists, skippedDraft }, { leadingBlankLine: false });
+        }
+        catch (err) {
+            console.error(`reformat-okf: seed-index failed — ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        // Step 3: seed-instructions --all (ensures POLARIS.md drafts; never touches CLAUDE.md/AGENTS.md)
+        console.log(`\n${label ? label + " " : ""}Step 3/3: seed-instructions --all`);
+        try {
+            const { written, skippedExists, skippedDraft, skippedIneligible, skippedRoot } = (0, seed_instructions_js_1.seedInstructionsAll)(repoRoot, { dryRun });
+            const rootCount = skippedRoot ? 1 : 0;
+            printSeedAllResult("POLARIS.md", dryRun, { written, skippedExists, skippedDraft }, { leadingBlankLine: false, extraSummary: `, ${rootCount} skipped (root), ${skippedIneligible.length} skipped (ineligible)` });
+        }
+        catch (err) {
+            console.error(`reformat-okf: seed-instructions failed — ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        console.log(`\nreformat-okf complete.${dryRun ? " (dry-run — no files written)" : ""}`);
+    });
     docs
         .command("audit")
         .description("Scan repo for files at risk of recursive ingestion")

package/dist/smartdocs-engine/seed-instructions.js

@@ -287,6 +287,10 @@ function generateDirectoryIndex(targetDir, repoRoot) {
     const dirLabel = (0, node_path_1.basename)(absDir) || "SmartDocs";
     const files = listConceptFiles(absDir);
     const lines = [
+        "---",
+        "okf_version: \"0.1\"",
+        "---",
+        "",
         exports.DRAFT_MARKER,
         `# ${dirLabel}`,
         "",

package/dist/tracker/adapters/linear/index.js

@@ -190,6 +190,36 @@ class LinearGraphqlClient {
       `, { id });
         return data.issue;
     }
+    async getIssueStateOptions(id) {
+        const data = await this.graphql(`
+        query PolarisLinearIssueStateOptions($id: String!) {
+          issue(id: $id) {
+            state { id }
+            team {
+              states(first: 250) {
+                nodes { id name type }
+              }
+            }
+          }
+        }
+      `, { id });
+        if (!data.issue)
+            return null;
+        return {
+            currentStateId: data.issue.state?.id ?? null,
+            states: data.issue.team?.states?.nodes ?? [],
+        };
+    }
+    async updateIssueState(id, stateId) {
+        const data = await this.graphql(`
+        mutation PolarisLinearIssueUpdateState($id: String!, $stateId: String!) {
+          issueUpdate(id: $id, input: { stateId: $stateId }) {
+            success
+          }
+        }
+      `, { id, stateId });
+        return data.issueUpdate.success;
+    }
 }
 /**
  * Implements the Linear direct adapter for synchronizing issues.
@@ -530,7 +560,7 @@ class LinearAdapter {
      * @param evidence - Optional evidence for the transition (e.g., commit hash).
      * @returns A lifecycle transition result indicating success, skip, or failure.
      */
-    async transitionLifecycleState(taskId, lifecycleState, evidence) {
+    async transitionLifecycleState(taskId, lifecycleState, _evidence) {
         if (lifecycleState === "no_status_change") {
             return {
                 applied: false,
@@ -538,17 +568,82 @@ class LinearAdapter {
                 skipReason: "Lifecycle state is 'no_status_change', skipping transition",
             };
         }
-        // Linear requires team-specific state IDs for state transitions.
-        // This implementation is a placeholder - full implementation would need:
-        // 1. Fetch available states for the issue's team
-        // 2. Map normalized lifecycle state to a specific Linear state ID
-        // 3. Use GraphQL mutation to update the issue state
-        console.warn(`LinearAdapter: transitionLifecycleState not fully implemented. Would transition ${taskId} to ${lifecycleState}.`);
-        return {
-            applied: false,
-            skipped: true,
-            skipReason: "Lifecycle state transitions are not yet implemented for Linear adapter",
+        let stateOptions;
+        try {
+            stateOptions = await this.linearClient.getIssueStateOptions(taskId);
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: `Failed to fetch Linear workflow states for ${taskId}: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!stateOptions) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `Linear issue '${taskId}' not found`,
+            };
+        }
+        const targetState = this.resolveWorkflowState(stateOptions.states, lifecycleState);
+        if (!targetState) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `No Linear workflow state on this issue's team maps to lifecycle state '${lifecycleState}'`,
+            };
+        }
+        if (targetState.id === stateOptions.currentStateId) {
+            return {
+                applied: false,
+                skipped: true,
+                skipReason: `Issue is already in target state '${targetState.name}'`,
+            };
+        }
+        try {
+            const success = await this.linearClient.updateIssueState(taskId, targetState.id);
+            if (!success) {
+                return {
+                    applied: false,
+                    skipped: false,
+                    error: `Linear issueUpdate mutation for ${taskId} returned success: false`,
+                };
+            }
+            return { applied: true, skipped: false };
+        }
+        catch (err) {
+            return {
+                applied: false,
+                skipped: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    /**
+     * Picks the Linear workflow state that best matches a normalized lifecycle state.
+     *
+     * Prefers exact `type` alignment (Linear's own backlog/unstarted/started/completed/canceled
+     * classification) so custom state names don't need to match `mapNativeStatus`'s heuristics;
+     * falls back to the first state whose name heuristically maps to the target state.
+     */
+    resolveWorkflowState(states, lifecycleState) {
+        const typeCandidates = {
+            backlog: ["backlog", "unstarted"],
+            in_progress: ["started"],
+            in_review: ["started"],
+            done: ["completed"],
+            blocked: ["started"],
+            cancelled: ["canceled", "cancelled"],
         };
+        const byHeuristic = states.filter((s) => this.mapNativeStatus(s.name).lifecycleState === lifecycleState);
+        if (byHeuristic.length === 1)
+            return byHeuristic[0];
+        const wantedTypes = typeCandidates[lifecycleState] ?? [];
+        const byType = (byHeuristic.length > 0 ? byHeuristic : states).filter((s) => wantedTypes.includes(s.type));
+        if (byType.length > 0)
+            return byType[0];
+        return byHeuristic[0] ?? null;
     }
     /**
      * Adds a comment to a Linear issue.

package/dist/workspace/POLARIS.md

@@ -0,0 +1,40 @@
+<!-- polaris:draft -->
+# workspace
+
+> Polaris draft — review and remove the `<!-- polaris:draft -->` marker to promote.
+
+## Purpose
+
+<!-- One paragraph describing what this folder does. -->
+
+**Domain:** workspace
+**Route:** src/workspace
+**Taskchain:** polaris-workspace
+
+## What belongs here
+
+- `POLARIS_RULES.md` — src/workspace (workspace)
+
+## What does not belong here
+
+<!-- Explicit exclusions of files or responsibilities. -->
+
+## Editing rules
+
+<!-- Behavioral constraints for agents and humans. -->
+
+## Architecture assumptions
+
+<!-- What the code assumes about the world. -->
+
+## Read before editing
+
+- [analyst.md](src/workspace/.polaris/roles/analyst.md)
+- [closeout-librarian.md](src/workspace/.polaris/roles/closeout-librarian.md)
+- [cognition-librarian.md](src/workspace/.polaris/roles/cognition-librarian.md)
+- [finalizer.md](src/workspace/.polaris/roles/finalizer.md)
+- [foreman.md](src/workspace/.polaris/roles/foreman.md)
+
+## Related routes
+
+<!-- Atlas route pointer to sibling or parent folders. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",