@lsctech/polaris 0.1.0

package/dist/loop/body-parser.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Issue body section parser.
+ *
+ * Parses a markdown issue body into structured fields used by the packet
+ * generator. Sections are identified by `## Header` lines (case-insensitive).
+ * List items are lines starting with `- ` or `* `.
+ *
+ * ## Canonical section format
+ *
+ * All implementation issues (parents and children) must use this exact format:
+ *
+ *   ## Objective          — one-sentence statement of what this issue accomplishes
+ *   ## Context            — why this issue exists
+ *   ## Goal               — specific implementation outcome
+ *   ## Scope              — machine-readable list of allowed paths/globs (REQUIRED)
+ *   ## Acceptance Criteria — checklist of observable completion requirements
+ *   ## Validation         — commands that must be run (REQUIRED)
+ *   ## Ordering           — dependencies or sequencing relative to siblings
+ *   ## Non-goals          — what this issue must not change
+ *
+ * Use `## Scope` exactly — not "Implementation scope", "Expected code areas",
+ * or other variants. Aliases are supported for backward compatibility only.
+ *
+ * If scope cannot be determined, write:
+ *   ## Scope
+ *   - TBD — BLOCKED: scope missing
+ * and mark the Linear issue as Blocked. Do NOT invent paths.
+ *
+ * ## Scope inheritance precedence
+ *
+ * When `buildPacket` resolves `allowed_scope` for a worker packet, it applies
+ * the following rules in order (first non-empty result wins):
+ *
+ *   1. Explicit `allowedScope` passed to `compileImplPacket` by the caller.
+ *   2. Child issue body `## Scope` section.
+ *   3. Cluster-root (parent) body `## Scope` section — fallback only when the
+ *      child body has no scope section at all.
+ *   4. Empty or TBD-blocked → preflight gate halts dispatch with
+ *      `preflight-scope-missing`.
+ *
+ * Rule 3 means a parent implementation plan can declare a cluster-wide scope
+ * that all child issues inherit when they omit their own scope section.
+ * A child that DOES declare its own scope section always overrides the parent —
+ * the parent scope is never merged with or appended to the child scope.
+ *
+ * Analyze children are exempt from scope preflight (they don't produce impl
+ * packets and don't need code-area constraints).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseIssueBody = parseIssueBody;
+exports.validateCanonicalSections = validateCanonicalSections;
+/**
+ * Canonical scope header. Aliases kept for backward compatibility only.
+ * New issues must use `## Scope` exactly.
+ */
+const SCOPE_HEADERS = new Set([
+    'scope',
+    'expected code areas',
+    'code areas',
+    'files to change',
+    'files',
+]);
+const VALIDATION_HEADERS = new Set([
+    'validation',
+    'validation commands',
+    'test commands',
+    'verify',
+]);
+const REQUIREMENTS_HEADERS = new Set([
+    'acceptance criteria',
+    'requirements',
+    'criteria',
+]);
+const ORDERING_HEADERS = new Set([
+    'ordering',
+    'dependencies / blockers',
+    'dependencies',
+    'order',
+]);
+const NON_GOALS_HEADERS = new Set([
+    'non-goals',
+    'non goals',
+    'out of scope',
+]);
+const OBJECTIVE_HEADERS = new Set(['objective']);
+const CONTEXT_HEADERS = new Set(['context']);
+const GOAL_HEADERS = new Set(['goal', 'goals']);
+/** Pattern that identifies a TBD-BLOCKED scope marker. */
+const TBD_BLOCKED_RE = /^tbd\b/i;
+/**
+ * Canonical sections required on every implementation issue.
+ * Used by `validateCanonicalSections` to report missing sections.
+ */
+const CANONICAL_SECTION_CHECKS = [
+    { name: 'Objective', headers: OBJECTIVE_HEADERS },
+    { name: 'Context', headers: CONTEXT_HEADERS },
+    { name: 'Goal', headers: GOAL_HEADERS },
+    { name: 'Scope', headers: SCOPE_HEADERS },
+    { name: 'Acceptance Criteria', headers: REQUIREMENTS_HEADERS },
+    { name: 'Validation', headers: VALIDATION_HEADERS },
+    { name: 'Ordering', headers: ORDERING_HEADERS },
+    { name: 'Non-goals', headers: NON_GOALS_HEADERS },
+];
+/**
+ * Split a markdown text into sections keyed by their normalized `##` header lines.
+ *
+ * @returns A Map where each key is a section header normalized by trimming and lowercasing, and each value is the raw content following that header (excluding the header line).
+ */
+function parseSections(body) {
+    const sections = new Map();
+    const parts = body.split(/^##\s+/m);
+    for (const part of parts) {
+        const nl = part.indexOf('\n');
+        if (nl === -1)
+            continue;
+        const header = part.slice(0, nl).trim().toLowerCase();
+        const content = part.slice(nl + 1);
+        sections.set(header, content);
+    }
+    return sections;
+}
+/**
+ * Extracts bullet list items from the given text and returns them as trimmed strings.
+ *
+ * @param text - Section content to scan for bullet list lines (lines starting with `- ` or `* `)
+ * @returns The extracted list item strings, trimmed of whitespace; empty items are omitted.
+ */
+function parseListItems(text) {
+    return text
+        .split('\n')
+        .filter((line) => /^\s*[-*]\s/.test(line))
+        .map((line) => line.replace(/^\s*[-*]\s+/, '').trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Extracts list items from the first section whose header matches a provided set.
+ *
+ * @param sections - Map of normalized header names to their section content; iteration follows the map's order
+ * @param headers - Set of normalized header names to match against section headers
+ * @returns An array of parsed list-item strings from the first matching section, or an empty array if no match is found
+ */
+function findSection(sections, headers) {
+    for (const [header, content] of sections) {
+        if (headers.has(header)) {
+            return parseListItems(content);
+        }
+    }
+    return [];
+}
+/**
+ * Returns trimmed prose text from the first section matching a header set.
+ * Used for single-paragraph sections (Objective, Context, Goal).
+ */
+function findSectionText(sections, headers) {
+    for (const [header, content] of sections) {
+        if (headers.has(header)) {
+            return content.trim();
+        }
+    }
+    return '';
+}
+/**
+ * Parse a markdown issue body into structured fields.
+ *
+ * Recognizes `##` sections and extracts bullet list items (`-` or `*`) from the first matching header for each field.
+ * Prose sections (Objective, Context, Goal) are returned as trimmed text.
+ *
+ * TBD-blocked scope: if every item in the `## Scope` section begins with "TBD"
+ * the scope is treated as empty (`scope: []`) and `scopeBlocked` is set to `true`.
+ * This ensures the preflight gate fires instead of dispatching a worker with an
+ * unusable scope list.
+ *
+ * @param body - The markdown issue body to parse.
+ * @returns Structured fields; each array/string is empty when the input is empty/whitespace or no matching section is found.
+ */
+function parseIssueBody(body) {
+    if (!body || !body.trim()) {
+        return {
+            scope: [],
+            scopeBlocked: false,
+            validationCommands: [],
+            requirements: [],
+            objective: '',
+            context: '',
+            goal: '',
+            ordering: [],
+            nonGoals: [],
+        };
+    }
+    const sections = parseSections(body);
+    const rawScope = findSection(sections, SCOPE_HEADERS);
+    const scopeBlocked = rawScope.length > 0 && rawScope.every((item) => TBD_BLOCKED_RE.test(item));
+    const filteredScope = rawScope.filter((item) => !TBD_BLOCKED_RE.test(item));
+    return {
+        scope: scopeBlocked ? [] : filteredScope,
+        scopeBlocked,
+        validationCommands: findSection(sections, VALIDATION_HEADERS),
+        requirements: findSection(sections, REQUIREMENTS_HEADERS),
+        objective: findSectionText(sections, OBJECTIVE_HEADERS),
+        context: findSectionText(sections, CONTEXT_HEADERS),
+        goal: findSectionText(sections, GOAL_HEADERS),
+        ordering: findSection(sections, ORDERING_HEADERS),
+        nonGoals: findSection(sections, NON_GOALS_HEADERS),
+    };
+}
+/**
+ * Checks a markdown issue body for the presence of all 8 required canonical sections.
+ *
+ * @param body - The markdown issue body to validate.
+ * @returns Names of any canonical sections that are absent. Empty array means the body is fully canonical.
+ */
+function validateCanonicalSections(body) {
+    if (!body || !body.trim()) {
+        return CANONICAL_SECTION_CHECKS.map((c) => c.name);
+    }
+    const sections = parseSections(body);
+    const sectionKeys = [...sections.keys()];
+    const missing = [];
+    for (const { name, headers } of CANONICAL_SECTION_CHECKS) {
+        if (!sectionKeys.some((key) => headers.has(key))) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}

package/dist/loop/bootstrap-packet.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBootstrapPacket = buildBootstrapPacket;
+exports.writeBootstrapPacket = writeBootstrapPacket;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const execution_adapter_js_1 = require("./execution-adapter.js");
+function getCurrentBranch(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["branch", "--show-current"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function getHeadSha(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function buildBootstrapPacket(state, stateFile, currentStateSha, repoRoot, completedChild, adapterMode, executionConfig, compactConfig) {
+    const branch = getCurrentBranch(repoRoot);
+    const nextChild = state.open_children[0] ?? null;
+    const maxChildren = state.context_budget.max_children_per_session ?? 3;
+    const filesTouched = state.context_budget.files_touched_total ?? 0;
+    const stopThresholdRemaining = maxChildren - state.context_budget.children_completed;
+    const artifactDir = state.artifact_dir ?? (0, node_path_1.join)(repoRoot, ".taskchain_artifacts", "polaris-run");
+    const telemetryFile = (0, node_path_1.join)(artifactDir, "runs", state.run_id, "telemetry.jsonl");
+    // Resolve compact_mode: explicit level wins, then orchestratorMode, then default "standard"
+    const compactMode = compactConfig?.level ?? compactConfig?.orchestratorMode ?? "standard";
+    const resumeInstructions = nextChild
+        ? `Run \`polaris loop resume ${state.run_id}\` on branch \`${branch}\` to continue with ${nextChild}.`
+        : `All children complete. Run \`polaris loop status\` to verify cluster state.`;
+    const adapterSelection = (0, execution_adapter_js_1.selectExecutionAdapter)({
+        configuredAdapter: adapterMode,
+        insideAgentSession: process.env.POLARIS_AGENT_SESSION === "1",
+        nativeSubtaskAvailable: process.env.POLARIS_NATIVE_SUBTASK === "1",
+        crossAgentConfigured: executionConfig?.allowCrossAgentFallback === true ||
+            process.env.POLARIS_ALLOW_CROSS_AGENT === "1",
+        tokenBudgetLow: process.env.POLARIS_TOKEN_BUDGET_LOW === "1",
+    });
+    const compactBootstrapState = (0, execution_adapter_js_1.buildCompactBootstrapState)({
+        runId: state.run_id,
+        clusterId: state.cluster_id,
+        childId: nextChild,
+        stateFile,
+        telemetryFile,
+        currentStateSha,
+        branch,
+        allowAnalyzeChildren: executionConfig?.allow_analyze_children,
+        compactMode,
+    });
+    // Normalize artifact_pointers to repo-relative paths
+    const relStateFile = stateFile.startsWith("/") ? (0, node_path_1.relative)(repoRoot, stateFile) : stateFile;
+    const relTelemetryFile = telemetryFile.startsWith("/") ? (0, node_path_1.relative)(repoRoot, telemetryFile) : telemetryFile;
+    return {
+        run_id: state.run_id,
+        skill: state.skill ?? "polaris-run",
+        branch,
+        base_commit_sha: getHeadSha(repoRoot),
+        last_completed_step: state.step_cursor,
+        last_completed_child: completedChild,
+        next_step: nextChild ? "03-execute-child" : "CLUSTER-COMPLETE",
+        open_children: state.open_children,
+        artifact_pointers: {
+            current_state: relStateFile,
+            telemetry: relTelemetryFile,
+        },
+        context_budget: {
+            children_completed: state.context_budget.children_completed,
+            files_touched_total: filesTouched,
+            stop_threshold_remaining: stopThresholdRemaining,
+        },
+        current_state_sha: currentStateSha,
+        resume_instructions: resumeInstructions,
+        compact_mode: compactMode,
+        execution_adapter: (0, execution_adapter_js_1.buildExecutionAdapterContract)(adapterSelection, compactBootstrapState),
+    };
+}
+function writeBootstrapPacket(packet, bootstrapDir) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const filename = `${packet.run_id}-${timestamp}.json`;
+    const outPath = (0, node_path_1.join)(bootstrapDir, filename);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(outPath, JSON.stringify(packet, null, 2), "utf-8");
+    return outPath;
+}

package/dist/loop/bootstrap-packet.test.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Unit tests for src/loop/bootstrap-packet.ts
+ *
+ * Covers:
+ *   - compact_mode propagation from compact config (all three levels)
+ *   - compact_mode default (no config) → "standard"
+ *   - level shorthand wins over orchestratorMode when level is set
+ *   - packet shape sanity checks
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const child_process = __importStar(require("node:child_process"));
+const node_path_1 = require("node:path");
+const bootstrap_packet_js_1 = require("./bootstrap-packet.js");
+vitest_1.vi.mock("node:child_process", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, execFileSync: vitest_1.vi.fn() };
+});
+const mockedExecFileSync = vitest_1.vi.mocked(child_process.execFileSync);
+(0, vitest_1.beforeEach)(() => {
+    vitest_1.vi.resetAllMocks();
+    // Default git mocks: branch + HEAD sha
+    mockedExecFileSync.mockImplementation((_cmd, args) => {
+        const argsArr = args;
+        if (argsArr && argsArr[0] === "branch") {
+            return Buffer.from("feature/pol-120\n");
+        }
+        if (argsArr && argsArr[0] === "rev-parse") {
+            return Buffer.from("abc1234567890\n");
+        }
+        return Buffer.from("");
+    });
+});
+const BASE_STATE = {
+    schema_version: "1.0",
+    run_id: "run-test-001",
+    cluster_id: "POL-114",
+    skill: "polaris-run",
+    active_child: "",
+    completed_children: ["POL-115"],
+    open_children: ["POL-120"],
+    step_cursor: "checkpoint",
+    context_budget: {
+        children_completed: 5,
+        files_touched_total: 20,
+        max_children_per_session: 6,
+    },
+    status: "running",
+    next_open_child: "POL-120",
+    artifact_dir: "/repo/.taskchain_artifacts/polaris-run",
+};
+(0, vitest_1.describe)("buildBootstrapPacket — compact_mode propagation", () => {
+    (0, vitest_1.it)("defaults compact_mode to 'standard' when no compactConfig is provided", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119");
+        (0, vitest_1.expect)(packet.compact_mode).toBe("standard");
+    });
+    (0, vitest_1.it)("defaults compact_mode to 'standard' when compactConfig is empty object", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, {});
+        (0, vitest_1.expect)(packet.compact_mode).toBe("standard");
+    });
+    (0, vitest_1.it)("sets compact_mode to 'standard' when level is 'standard'", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "standard" });
+        (0, vitest_1.expect)(packet.compact_mode).toBe("standard");
+    });
+    (0, vitest_1.it)("sets compact_mode to 'strict' when level is 'strict'", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "strict" });
+        (0, vitest_1.expect)(packet.compact_mode).toBe("strict");
+    });
+    (0, vitest_1.it)("sets compact_mode to 'minimal' when level is 'minimal'", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "minimal" });
+        (0, vitest_1.expect)(packet.compact_mode).toBe("minimal");
+    });
+    (0, vitest_1.it)("uses orchestratorMode when level is not set", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { orchestratorMode: "strict" });
+        (0, vitest_1.expect)(packet.compact_mode).toBe("strict");
+    });
+    (0, vitest_1.it)("level wins over orchestratorMode when both are set", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "minimal", orchestratorMode: "strict" });
+        // level takes priority per bootstrap-packet.ts implementation
+        (0, vitest_1.expect)(packet.compact_mode).toBe("minimal");
+    });
+});
+(0, vitest_1.describe)("buildBootstrapPacket — execution_adapter carries compact_mode", () => {
+    (0, vitest_1.it)("execution_adapter.compact_bootstrap_state.compact_mode matches packet compact_mode (standard)", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "standard" });
+        (0, vitest_1.expect)(packet.execution_adapter?.compact_bootstrap_state.compact_mode).toBe("standard");
+        (0, vitest_1.expect)(packet.compact_mode).toBe("standard");
+    });
+    (0, vitest_1.it)("execution_adapter.compact_bootstrap_state.compact_mode matches packet compact_mode (strict)", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "strict" });
+        (0, vitest_1.expect)(packet.execution_adapter?.compact_bootstrap_state.compact_mode).toBe("strict");
+        (0, vitest_1.expect)(packet.compact_mode).toBe("strict");
+    });
+    (0, vitest_1.it)("execution_adapter.compact_bootstrap_state.compact_mode matches packet compact_mode (minimal)", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119", undefined, undefined, { level: "minimal" });
+        (0, vitest_1.expect)(packet.execution_adapter?.compact_bootstrap_state.compact_mode).toBe("minimal");
+        (0, vitest_1.expect)(packet.compact_mode).toBe("minimal");
+    });
+    (0, vitest_1.it)("compact_bootstrap_state and packet compact_mode are in sync for default case", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119");
+        (0, vitest_1.expect)(packet.compact_mode).toBe("standard");
+        (0, vitest_1.expect)(packet.execution_adapter?.compact_bootstrap_state.compact_mode).toBe("standard");
+    });
+});
+(0, vitest_1.describe)("buildBootstrapPacket — packet shape", () => {
+    (0, vitest_1.it)("sets run_id, skill, and open_children from state", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119");
+        (0, vitest_1.expect)(packet.run_id).toBe("run-test-001");
+        (0, vitest_1.expect)(packet.skill).toBe("polaris-run");
+        (0, vitest_1.expect)(packet.open_children).toEqual(["POL-120"]);
+        (0, vitest_1.expect)(packet.last_completed_child).toBe("POL-119");
+    });
+    (0, vitest_1.it)("sets next_step to CLUSTER-COMPLETE when no open children remain", () => {
+        const state = {
+            ...BASE_STATE,
+            open_children: [],
+            next_open_child: null,
+        };
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(state, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-120");
+        (0, vitest_1.expect)(packet.next_step).toBe("CLUSTER-COMPLETE");
+    });
+    (0, vitest_1.it)("sets next_step to '03-execute-child' when open children remain", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119");
+        (0, vitest_1.expect)(packet.next_step).toBe("03-execute-child");
+    });
+    (0, vitest_1.it)("includes artifact_pointers with relative paths", () => {
+        const packet = (0, bootstrap_packet_js_1.buildBootstrapPacket)(BASE_STATE, "/repo/.taskchain_artifacts/polaris-run/current-state.json", "sha256abc", "/repo", "POL-119");
+        (0, vitest_1.expect)(packet.artifact_pointers.current_state).toMatch(/\.taskchain_artifacts/);
+        (0, vitest_1.expect)(packet.artifact_pointers.telemetry).toMatch(/telemetry\.jsonl$/);
+        // Ensure paths are not absolute
+        (0, vitest_1.expect)((0, node_path_1.isAbsolute)(packet.artifact_pointers.current_state)).toBe(false);
+        (0, vitest_1.expect)((0, node_path_1.isAbsolute)(packet.artifact_pointers.telemetry)).toBe(false);
+        // Ensure paths do not start with /repo/ prefix
+        (0, vitest_1.expect)(packet.artifact_pointers.current_state).not.toMatch(/^\/repo\//);
+        (0, vitest_1.expect)(packet.artifact_pointers.telemetry).not.toMatch(/^\/repo\//);
+    });
+});

package/dist/loop/branch-governance.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProtectedBranch = isProtectedBranch;
+exports.deriveClusterBranch = deriveClusterBranch;
+exports.getCurrentBranch = getCurrentBranch;
+exports.ensureClusterBranch = ensureClusterBranch;
+const node_child_process_1 = require("node:child_process");
+const PROTECTED_BRANCHES = new Set(["", "HEAD", "main", "master"]);
+function isProtectedBranch(branch) {
+    return PROTECTED_BRANCHES.has((branch ?? "").trim());
+}
+function deriveClusterBranch(clusterId) {
+    return `polaris/${clusterId}`;
+}
+function getCurrentBranch(repoRoot) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["branch", "--show-current"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function branchExists(repoRoot, branch) {
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+            cwd: repoRoot,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ensureClusterBranch(repoRoot, clusterId, preferredBranch) {
+    const targetBranch = !isProtectedBranch(preferredBranch)
+        ? preferredBranch.trim()
+        : deriveClusterBranch(clusterId);
+    const currentBranch = getCurrentBranch(repoRoot);
+    if (currentBranch === targetBranch) {
+        return targetBranch;
+    }
+    const args = branchExists(repoRoot, targetBranch)
+        ? ["switch", targetBranch]
+        : ["switch", "-c", targetBranch];
+    (0, node_child_process_1.execFileSync)("git", args, {
+        cwd: repoRoot,
+        stdio: "ignore",
+    });
+    return targetBranch;
+}

package/dist/loop/budget.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Budget policy for the parent scheduler loop.
+ *
+ * The parent checks budget after each worker dispatch. If the budget is
+ * exhausted, the parent halts and writes a checkpoint to current-state.json.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkBudget = checkBudget;
+exports.policyFromConfig = policyFromConfig;
+exports.policyFromState = policyFromState;
+/**
+ * Check whether the context budget allows continuing to the next child.
+ *
+ * Returns `{ status: 'ok' }` if the loop should continue, or
+ * `{ status: 'exhausted', reason }` if the loop must halt.
+ */
+function checkBudget(input) {
+    const { childrenCompleted, lastChildStatus, policy } = input;
+    // stop-on-fail: halt immediately when any child fails
+    if (policy.stopOnFail && lastChildStatus === 'failed') {
+        return {
+            status: 'exhausted',
+            reason: `Budget halted: stop_on_fail is enabled and a child returned status "failed".`,
+        };
+    }
+    switch (policy.mode) {
+        case 'run-until-done':
+            // No cap — always continue until open_children is empty
+            return { status: 'ok' };
+        case 'stop-on-fail':
+            // The stop-on-fail mode implies run-until-done cap-wise;
+            // actual fail detection is handled above via stopOnFail flag.
+            return { status: 'ok' };
+        case 'fixed-cap':
+        default:
+            if (childrenCompleted >= policy.maxChildrenPerSession) {
+                return {
+                    status: 'exhausted',
+                    reason: `Budget exhausted: ${childrenCompleted} of ${policy.maxChildrenPerSession} ` +
+                        `children completed this session.`,
+                };
+            }
+            return { status: 'ok' };
+    }
+}
+/**
+ * Derive a BudgetPolicy from the state's context_budget field and the loaded config.
+ * Config takes precedence over state fields; falls back to a default of 3-child fixed-cap.
+ */
+function policyFromConfig(contextBudget, budgetConfig) {
+    const mode = budgetConfig?.mode ?? 'fixed-cap';
+    const maxChildrenPerSession = budgetConfig?.max_children ?? contextBudget.max_children_per_session ?? 3;
+    const stopOnFail = budgetConfig?.stop_on_fail ?? (mode === 'stop-on-fail');
+    return { mode, maxChildrenPerSession, stopOnFail };
+}
+/**
+ * @deprecated Use policyFromConfig instead.
+ * Kept for backwards compatibility with callers that only have state context_budget.
+ */
+function policyFromState(contextBudget) {
+    return policyFromConfig(contextBudget, undefined);
+}