@lsctech/polaris 0.3.22 → 0.3.24

package/dist/workspace/workspace/.polaris/skills/polaris-run/chain.md

@@ -1,298 +0,0 @@
----
-name: polaris-run-chain
-description: Route map for polaris-run — step order, continuation rules, Polaris runtime integration, and artifact update requirements.
----
-
-# polaris-run chain
-
-## Authority
-
-**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
-
-Query runtime state before acting. Do not infer cluster scope or progress from conversation context.
-
-## Thin-Parent Orchestration
-
-This skill operates under a **thin-parent** model. The agent running this `chain.md` is an orchestrator, not an implementer.
-
-**Core principles:**
-- **The orchestrator does not write code.** All implementation is delegated to workers via `polaris loop dispatch`.
-- **The orchestrator does not narrate implementation details.** Its communication should be concise and focused on the orchestration state (dispatching, checkpointing, blocked, complete).
-- **The orchestrator does not reason about the repository.** All repository-level cognition belongs to the worker.
-
-### Narration Suppression
-
-To enforce the thin-parent model, the orchestrator's narration is strictly suppressed.
-
-**Allowed narration:**
-- Announcing the start of a run.
-- Announcing the dispatch of a child.
-- Announcing the completion of a child and the next step (continue, finalize, or stop).
-- Announcing a blocker.
-
-**Forbidden narration:**
-- Summarizing code changes made by a worker.
-- Explaining implementation details.
-- Speculating on architecture or design.
-- Any form of "thinking out loud" about the repository content.
-
-The `polaris loop run` command may provide terse, single-line status updates for headless/SSH execution. The agent should not add any extra narration around these.
-
-## CHECKPOINT gate
-
-**The Foreman must discard worker output except the CompactReturn JSON object.**
-
-When `loop run` exits, the only content the Foreman may retain from the worker subprocess is:
-- The final `[POLARIS] COMPLETE <child-id> (commit: <sha>)` signal
-- The CompactReturn JSON emitted as the last line of worker stdout
-
-The Foreman must NOT:
-- Read, store, or summarize raw worker output or transcripts
-- Inspect worker tool-call history
-- Ingest implementation details from worker stderr
-
-This gate enforces the thin-parent model: the Foreman is a scheduler, not a consumer of implementation content.
-
-**Preserve the existing step order.** Do not reorder, skip, or merge steps. Each step has a defined entry condition and exit artifact.
-
-## CLI
-
-Always use the repo-local Polaris CLI:
-
-```
-npm run polaris -- <command>
-```
-
-Never assume a globally linked `polaris` command exists.
-
-## Step traversal order
-
-```text
-01-orient-cluster
-02-prepare-branch
-03-select-child
-04-execute-child              ← worker/adapter-owned execution phase
-05-validate-child             ← worker-owned validation phase
-06-commit-and-update-linear   ← worker-return validation and completion recording
-07-decide-continuation   → DISPATCH boundary | CHECKPOINT after worker return | STOP (blocked/all-done) | DELIVER: go to 08
-08-medic-dispatch        ← dispatch Medic if triage required (before Librarian)
-09-closeout-librarian    ← dispatched once per cluster; PR creation blocked until result validated
-10-final-delivery        ← reached only after closeout librarian succeeds
-```
-
-## CHECKPOINT gate
-
-At each worker return boundary (step 07), apply the CHECKPOINT gate before proceeding:
-
-1. Accept and discard worker output except the CompactReturn JSON object — all other session content is discarded.
-2. Parse the CompactReturn JSON. If it is missing or malformed, treat as a blocker and stop.
-3. Pass the CompactReturn JSON to `npm run polaris -- loop continue` for state persistence.
-4. Preserve the existing step order — do not reorder, skip, or repeat steps based on worker output content.
-
-## Continuation rules
-
-After step 07 evaluates the session:
-
-- **DISPATCH (all remaining children)**: run `npm run polaris -- loop run <cluster-id>`. The runtime dispatches all eligible children serially, enforcing dispatch boundaries internally. The Foreman waits for the subprocess to exit. Progress signals are emitted as `[POLARIS] RUNNING <child-id> (N/M)` and `[POLARIS] COMPLETE <child-id> (commit: <sha>)`. No per-child CompactReturn handling or state repair is needed — the runtime owns that boundary.
-- **STOP (blocked)**: halt immediately on blocker. Report unblock condition.
-- **STOP (all-done, awaiting delivery)**: `loop run` exits when all children are done. Report branch and last commit. Provide delivery command: `Use polaris-run on <PARENT-ID>. Finalize delivery.`
-- **DELIVER**: proceed to step 08 (Closeout Librarian) only when all children are Done and the user explicitly requests delivery in this session invocation.
-
-## Closeout Librarian boundary
-
-**The Closeout Librarian runs exactly once per cluster, between all-children-done and PR creation.**
-
-Step 08 dispatches the Librarian as a bounded session (same model as worker dispatch).
-The Foreman waits for the Librarian's sealed result before proceeding to step 09.
-PR creation (step 09) is blocked until the Librarian result status is `"success"` or `"partial"`.
-
-**Librarian dispatch message template:**
-
-When dispatching the Closeout Librarian, pass this full message — NOT just the packet path. Replace `<cluster-id>`, `<packet_path>`, `<run_id>`, and `<dispatch_id>` with values from the packet file:
-
-```
-You are the Closeout Librarian for cluster <cluster-id>.
-
-Your sealed packet is at: <packet_path>
-
-Read the packet. Follow the closeout-librarian skill chain. Write your sealed result to the path in the packet's `result_path` field. Return only compact JSON: {"role":"closeout-librarian","status":"done","run_id":"<run_id>","cluster_id":"<cluster-id>","dispatch_id":"<dispatch_id>","commit":"<sha>"}.
-```
-
-Never dispatch the librarian with only the packet path as the message.
-
-The Foreman must NOT:
-- Read the Librarian's session transcript
-- Inline the Librarian's work
-- Skip step 08 because it appears slow
-- Repair the Librarian's output manually
-- Run the Librarian after individual workers (cluster-complete only)
-
-## Medic Dispatch Boundary
-
-**Medic is dispatched when a worker returns a failed result packet and triage is required.**
-
-Step 08 dispatches Medic as a bounded session (same model as worker dispatch) when:
-- A worker result packet has `status: "failure"`
-- The Foreman marks `triage_required: true` in the cluster state
-- Runnable sibling work continues in parallel with Medic dispatch
-
-**Medic dispatch message template:**
-
-When dispatching Medic, pass this full message — NOT just the packet path. Replace `<cluster-id>`, `<packet_path>`, `<run_id>`, and `<dispatch_id>` with values from the packet file:
-
-```
-You are the Medic for cluster <cluster-id>.
-
-Your sealed packet is at: <packet_path>
-
-Read the packet. Follow the polaris-medic skill chain. Write your sealed result to the path in the packet's `result_path` field. Return only compact JSON: {"role":"medic","status":"done","run_id":"<run_id>","cluster_id":"<cluster-id>","dispatch_id":"<dispatch_id>","commit":"<sha>","chart_id":"<chart_id>"}.
-```
-
-Never dispatch Medic with only the packet path as the message.
-
-The Foreman must NOT:
-- Read the Medic's session transcript
-- Inline the Medic's work
-- Skip Medic dispatch when triage is required
-- Repair the Medic's output manually
-- Dispatch Medic for successful worker results
-
-**Medic and Foreman parallelism:**
-
-When Medic is dispatched, the Foreman continues dispatching runnable sibling work in parallel. Medic does not block other children from executing. Medic runs independently and reports its result when complete. The Librarian waits for both all children and any Medic dispatches to complete before reconciliation.
-
-## Dispatch boundary enforcement (runtime-owned)
-
-**The runtime enforces dispatch boundaries. Parent/orchestrator inline implementation is forbidden.**
-
-This is not advisory. The runtime will hard-fail with `process.exit(1)` on violations.
-
-`loop run` owns the full dispatch→checkpoint loop internally. The Foreman must not call `loop dispatch` or `loop continue` individually — doing so bypasses the boundary enforcement that `loop run` manages.
-
-### Allowed transition (only legal path)
-
-```
-Foreman → npm run polaris -- loop run <cluster-id>
-  ↓ (subprocess)
-  runtime selects child
-  runtime dispatches worker externally
-  runtime receives CompactReturn → checkpoints → next child
-  runtime emits: [POLARIS] RUNNING <child> (N/M)
-  runtime emits: [POLARIS] COMPLETE <child> (commit: <sha>)
-  (repeat for each child)
-  runtime emits: [POLARIS] COMPLETE (cluster-complete)
-  subprocess exits 0
-Foreman proceeds to step 07 STOP/DELIVER
-```
-
-### Hard failures (illegal transitions)
-
-| Attempt | Runtime response |
-|---|---|
-| Parent calling `loop dispatch` manually | Bypasses `loop run` — governance violation |
-| Parent calling `loop continue` manually | Bypasses `loop run` — governance violation |
-| Parent completing child without dispatch record | `exit(1)` + `illegal-state-transition` telemetry event |
-| `selected → completed` (no dispatch in path) | Hard failure — never allowed |
-
-**When `execution.providerPolicy.worker.allowNativeSubagent: false` or `execution.providerPolicy.orchestrator.allowNativeSubagent: false`, never use any native subagent or parallel-task mechanism** (applies to all providers: Claude, Codex, Copilot, etc.). `loop run` via `terminal-cli` is the only supported dispatch path.
-
-## Polaris runtime integration
-
-polaris-run uses these Polaris CLI calls:
-
-| Step | Polaris call | Purpose |
-|---|---|---|
-| 07 | `npm run polaris -- loop run <cluster-id>` | Run all eligible children serially; emits `[POLARIS] RUNNING <child> (N/M)` per child and `[POLARIS] COMPLETE <child> (commit: <sha>)` on completion; exits when cluster-complete or blocked |
-| 08 | `npm run polaris -- medic packet <cluster-id>` | Generate Medic packet for failed worker result (if triage required) |
-| 08 | Medic subagent dispatch | Dispatch Medic; wait for sealed result; validate result before proceeding |
-| 09 | `npm run polaris -- librarian packet <cluster-id>` | Generate Closeout Librarian packet for the completed cluster |
-| 09 | Librarian subagent dispatch | Dispatch Closeout Librarian; wait for sealed result; validate result before proceeding |
-| 10 | `npm run polaris -- finalize` | Push branch (including librarian commit), open PR, append JSONL closeout events, archive run snapshot |
-
-`npm run polaris -- loop run <cluster-id>` is the standard execution command. It internally manages the dispatch→checkpoint loop for all children, emitting terse progress signals the Foreman can monitor. The Foreman does not call `loop dispatch` or `loop continue` — those boundaries are owned by `loop run`.
-
-## Context budget
-
-Track in `.taskchain_artifacts/polaris-run/current-state.json` under `context_budget`. Update after each child.
-
-| Counter | Meaning | Stop threshold |
-|---------|---------|----------------|
-| `children_completed` | Children fully Done this session | `fixed-cap` mode only: ≥ `budget.max_children` from `polaris.config.json` (default 6) → STOP (budget exhausted); no count cap in `run-until-done`/`stop-on-fail` modes; the CLI runtime enforces this |
-| `files_touched_total` | Total files changed this session | > 50 → STOP (safety) |
-| `last_child_files_touched` | Files changed by last child | > 20 → STOP (safety) |
-
-## Run ID format
-
-Format: `polaris-run-<slug>-<date>-<seq>`
-- `<slug>`: 2–4 lowercase hyphenated words from the cluster title. No Linear IDs.
-- `<date>`: `YYYY-MM-DD`
-- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
-
-Example: `polaris-run-loop-boundary-2026-05-23-001`
-
-Resumed sessions generate a new `run_id`. Record the prior in `related_run_id`.
-
-## Telemetry enforcement
-
-Telemetry file: `.taskchain_artifacts/polaris-run/runs/<run-id>/telemetry.jsonl` (append-only).
-
-| Event | Emitted by | Step |
-|---|---|---|
-| `run-start` | agent | 01 — before any Linear access |
-| `child-dispatched` | `npm run polaris -- loop dispatch` | 07 — when one child is accepted by the execution adapter |
-| `child-complete` | parent runtime | 07 — after worker return validation and completion recording |
-| `loop-checkpoint` | `npm run polaris -- loop continue` | 07 — after each child |
-| `analyze-impl-boundary-enforced` | `npm run polaris -- loop continue` | 07 — blocker/state-repair boundary event only |
-| `loop-aborted` | `npm run polaris -- loop abort` | any blocker halt |
-| `medic-dispatched` | parent runtime | 08 — when Medic is dispatched for failed worker |
-| `medic-complete` | parent runtime | 08 — after Medic returns sealed result |
-| `pr-opened` | `npm run polaris -- finalize` | 10 |
-| `run-complete` | `npm run polaris -- finalize` | 10 |
-
-Required fields on every event: `event`, `run_id`, `timestamp`.
-
-## Artifact authority
-
-`.taskchain_artifacts/polaris-run/current-state.json` is the sole authoritative live state surface.
-
-- Update only at explicit checkpoint boundaries via `npm run polaris -- loop continue` after worker returns, or when DISPATCH boundaries mandate bootstrapping.
-- Parent agents must not update state inline between steps.
-- If the checkpoint fails: stop and report the persistence failure.
-
-## Machine snapshot
-
-- **Path**: `.taskchain_artifacts/polaris-run/current-state.json`
-- **Update requirement**: only at checkpoint boundaries (via `npm run polaris -- loop continue`)
-- **Purpose**: fast agent resume without replaying JSONL or markdown history
-
-## Completion rule
-
-Do not report workflow completion until `.taskchain_artifacts/polaris-run/current-state.json` has `status: complete`.
-
-## Linked-skill invocation boundaries
-
-| Skill | Allowed steps | Condition |
-|---|---|---|
-| repo-analysis | 01, 02, 03, 04 | targeted lookup only; conditional on provider availability |
-| execution-adapter | 07 | required when a completed child has a next open child |
-| polaris-medic | 08 | required when a worker returns a failed result packet and triage is required |
-
-## Execution reporting
-
-At checkpoint boundaries (worker returns), emit a checkpoint report:
-
-```text
-**[step-name]** done | blocked | needs-input
-Changed: <files / artifacts / branches / issues> or none
-Validated: <commands / checks passed> or none
-Blockers: none | <explicit blocker>
-```
-
-### Never compressed
-
-Always write in full:
-- Generated code
-- Safety warnings
-- Blocker descriptions
-- Acceptance-criteria gap explanations
-- Irreversible-action confirmations

package/dist/workspace/workspace/.polaris/skills/polaris-run/execution-adapter.md

@@ -1,34 +0,0 @@
----
-name: polaris-run-execution-adapter
-description: Adapter boundary for dispatching Polaris child worker sessions without coupling orchestration to a specific agent runtime.
----
-
-# Execution Adapter Boundary
-
-Polaris orchestration is adapter-agnostic. The parent session selects the next child and uses `polaris loop dispatch` as the dispatch trigger for the configured adapter. The worker session performs implementation and returns only compact state: child ID, status, commit hash, validation summary, and next action. After that return, the parent may run `polaris loop continue` as the post-child checkpoint.
-
-The adapter boundary is the token boundary. Parent/orchestrator context must not accumulate child implementation transcripts.
-
-## Adapter Modes
-
-| Mode | Use | Dispatch |
-|---|---|---|
-| `agent-subtask` | Interactive agent sessions (requires `allowNativeSubagent: true`) | Use the host agent's subtask/agent dispatch capability. |
-| `terminal-cli` | Terminal, cron, CI wrapper; **required when the active polaris-run dispatch role sets `allowNativeSubagent: false`** | Use `scripts/polaris-run.sh` or equivalent shell subprocess with an explicitly configured CLI worker. |
-
-> **Prohibition (polaris-run worker and orchestrator dispatch only)**
->
-> - When the active polaris-run dispatch role sets `execution.providerPolicy.worker.allowNativeSubagent: false` or `execution.providerPolicy.orchestrator.allowNativeSubagent: false`, the `agent-subtask` mode is forbidden for that role.
-> - This applies across host CLIs and providers: Claude, Codex, Copilot, and other agent runtimes all expose native subagent or parallel-task mechanisms that are disallowed under this flag for worker/orchestrator dispatch.
-> - Other roles (e.g., `analyst`) may independently permit native subagents via their own `allowNativeSubagent` setting.
-> - The Foreman must not search for, load, or invoke any native subagent mechanism when dispatching workers.
-> - The current runtime adapter registry supports only `terminal-cli` and `agent-subtask`, so when the active role disallows native subagents the legal dispatch path is `terminal-cli`.
-
-## Contract
-
-1. Parent reads `.taskchain_artifacts/polaris-run/current-state.json`.
-2. Parent runs `polaris loop dispatch`, which dispatches the next child through the selected adapter.
-3. Worker updates current-state and telemetry.
-4. Parent reads current-state after worker completion.
-5. Parent does not ingest worker transcript content.
-6. Parent runs `polaris loop continue` only after the worker has returned.

package/dist/workspace/workspace/.polaris/skills/polaris-run/linked-skills/repo-analysis.md

@@ -1,58 +0,0 @@
----
-title: repo-analysis provider linkage
-description: Provide targeted code intelligence and impact checks when a repo-analysis provider is configured and available in the session environment.
-version: "1.0"
----
-
-# repo-analysis provider linkage
-
----
-
-## Allowed steps
-
-- 01-orient-cluster
-- 02-prepare-branch
-- 03-select-child
-- 04-execute-child
-
----
-
-## Purpose
-
-Provide targeted code intelligence and impact checks when polaris-run needs repository graph context.
-
-This linked-skill governs use of the configured repo-analysis provider (e.g., GitNexus). If no provider is available, the fallback path (polaris map query + ripgrep + direct file inspection) is authoritative. See `docs/Polaris/spec/provider-capabilities.md` for the full provider model.
-
----
-
-## Allowed scope
-
-- Check configured provider availability at session start
-- Query specific files, symbols, or concepts relevant to the current child
-- Run impact analysis before modifying significant symbols
-- Run targeted context checks to locate implementation surfaces
-- Report stale-index warnings and pair them with direct inspection
-
----
-
-## Forbidden scope
-
-- Do not perform broad graph dumps or full-repo reports
-- Do not replace direct repository inspection
-- Do not expand implementation beyond the selected child
-- Do not invoke outside allowed steps
-- Do not assume a specific provider product is present — check availability first
-
----
-
-## Provider detection
-
-At step 01, check `polaris.config.json` for `providers.repoAnalysis.preferred`.
-If a provider is configured and available in the session environment: use it.
-If unavailable or not configured: note `repo_analysis_status: not-configured` in artifact and proceed with fallback.
-
----
-
-## Invocation note
-
-Conditional. Invoke only when a child requires code intelligence, symbol impact, or change-scope verification. When the provider is unavailable, the fallback path runs instead — execution continues.

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/01-orient-cluster.md

@@ -1,96 +0,0 @@
----
-name: polaris-run-step-01-orient-cluster
-description: Query runtime state, generate run_id if needed, emit run-start telemetry, fetch the parent cluster from Linear, and restate bounded session context.
----
-
-# Step 01 — Orient cluster
-
-## Purpose
-
-Establish the bounded working context for this session before touching any code. Runtime state is authoritative — query it first, do not reconstruct it from chat reasoning.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .polaris/skills/polaris-run/SKILL.md
-  - .polaris/skills/polaris-run/chain.md
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .polaris/clusters/<cluster-id>/clusters.json
-allowed_routes:
-  - CLAUDE.md
-  - docs/Polaris/spec/polaris-implementation-plan.md
-  - .polaris/skills/polaris-run/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - runtime state queried via npm run polaris -- loop status
-  - run_id generated or read from prior state
-  - run-start telemetry emitted
-  - Linear parent and children fetched
-  - cluster is valid and executable
-  - bounded session context restated
-stop_rules:
-  - run-start telemetry write fails
-  - parent issue missing or inaccessible
-  - parent or selected child is blocked
-  - cluster has no children and issue is not standalone
-```
-
-## Actions
-
-0. **Query runtime state**:
-   Run `npm run polaris -- loop status` to check for existing session state.
-   - **Follow-up run** (state exists and is active for this cluster): read `cluster_id` and step context from runtime output. Mint a new `run_id` in `polaris-run-<slug>-<date>-<seq>` format (see `chain.md` for format rules) — do not reuse the prior `run_id`. Set `related_run_id` to the prior `run_id` read from runtime output. Runtime state is authoritative — do not infer session context from chat history.
-   - **Fresh run** (no state file, or state belongs to a different cluster): generate new `run_id` in format `polaris-run-<slug>-<date>-<seq>` (see `chain.md` for format rules). `related_run_id` is `null`.
-
-1. **Emit `run-start` telemetry** — first write action, before any Linear access or branch work:
-   ```bash
-   mkdir -p .taskchain_artifacts/polaris-run/runs/<run-id>
-   echo '{"event":"run-start","run_id":"<run-id>","prior_run_id":"<prior or null>","timestamp":"<ISO>"}' \
-     >> .taskchain_artifacts/polaris-run/runs/<run-id>/telemetry.jsonl
-   ```
-   No runtime CLI command exists for run-start telemetry; direct file append is the standard path.
-   If this write fails: halt. Do not continue.
-
-2. Fetch the **parent issue AND all child issues** from Linear in two sequential calls (get parent, then list children by parent ID).
-
-3. Confirm the cluster is valid and executable:
-   - Has children (or is a standalone issue).
-   - Not blocked at the parent level.
-   - Not Done or Cancelled.
-   - Parent is an IMPLEMENT root, not an ANALYZE root. If the parent title starts with `ANALYZE:` or has the `analyze` label, halt before branch work or child dispatch with exactly:
-     `polaris-run targets IMPLEMENT parents, not ANALYZE issues. Run polaris-analyze first to create an IMPLEMENT parent.`
-   - If ambiguous or not executable: stop and recommend running polaris-analyze first.
-
-4. Check `.polaris/clusters/<cluster-id>/clusters.json` if it exists — it provides execution ordering and dependency metadata produced by polaris-analyze. If absent, use the child issue ordering from Linear as the fallback (see step 03).
-
-5. Restate the working context in under 10 bullets:
-   - `run_id` and whether this is fresh or resumed
-   - Parent issue ID and title
-   - Branch name (create or reuse)
-   - Total children count
-   - Open children (IDs and titles, dependency order)
-   - Any blockers visible at this stage
-   - Execution boundary (one parent cluster, this session)
-
-6. Invoke `npm run polaris -- loop status` to confirm runtime state is consistent before advancing to the next step.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-
-- `run_id: <generated>`
-- `related_run_id: <prior run_id or null>`
-- `cluster_id: <parent issue ID>`
-- `skill: polaris-run`
-- `artifact_dir: ".taskchain_artifacts/polaris-run"`
-- `status: orienting`
-- `current_step_id: 01-orient-cluster`
-- `updated_at: <timestamp>`
-
-Do not emit per-step `step-complete` telemetry. Telemetry is checkpoint-only (`run-start`, `child-dispatched`, child completion/checkpoint events, session end, and blocker/state-repair events).
-
-## Next step
-
-02-prepare-branch

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/02-prepare-branch.md

@@ -1,53 +0,0 @@
----
-name: polaris-run-step-02-prepare-branch
-description: Create or reuse the parent-scoped git branch from the Linear issue's gitBranchName and verify a clean execution state.
----
-
-# Step 02 — Prepare branch
-
-## Purpose
-
-Establish a clean, parent-scoped git branch before child execution begins.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - git branch and worktree metadata only
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - target branch identified or created from main
-  - dirty checkout policy applied
-  - Linear issue branch name used
-stop_rules:
-  - unrelated dirty checkout cannot be isolated
-  - target branch conflicts with existing delivery branch
-  - branch cannot be created from main
-```
-
-## Actions
-
-1. Use the branch name from the Linear parent issue's `gitBranchName` field as the authoritative branch name. This field provides the exact branch name to use (typically formatted like `philmeaux/<pol-id>-<slug>`, though format may vary). Do not invent or modify the branch name.
-2. If the branch already exists: check it out and verify the working tree is clean. If dirty: halt and instruct the user to commit or stash changes before continuing.
-3. If the branch does not exist: create it from `main`.
-4. Confirm no uncommitted changes from a different parent cluster exist. If `.taskchain_artifacts/polaris-run/current-state.json` records a different `cluster_id`, halt and report.
-5. Do not commit anything at this step.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `status: ready`
-- `branch: <branch-name>`
-- `current_step_id: 02-prepare-branch`
-- `updated_at: <timestamp>`
-
-Do not emit per-step `step-complete` telemetry. Telemetry is checkpoint-only (`run-start`, `child-dispatched`, child completion/checkpoint events, session end, and blocker/state-repair events).
-
-## Next step
-
-03-select-child

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/03-select-child.md

@@ -1,63 +0,0 @@
----
-name: polaris-run-step-03-select-child
-description: Re-fetch the child list from Linear, identify the next unblocked child, and halt on blockers or all-done.
----
-
-# Step 03 — Select child
-
-## Purpose
-
-Identify the correct next child to execute without skipping or misordering.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .polaris/clusters/<cluster-id>/clusters.json
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - fresh child list fetched from Linear
-  - lowest-ordered open child selected
-  - blocked child state checked
-stop_rules:
-  - next child is blocked
-  - child ordering is ambiguous
-  - all children are Done (route to DELIVER)
-```
-
-## Actions
-
-1. **First child of the session**: use the child list fetched in step 01 — do not re-fetch.
-2. **Second child and beyond**: re-fetch the full child list from Linear to catch state changes from the prior child.
-3. Filter to open children only (exclude Done and Cancelled).
-4. If no open children remain:
-   - Update artifact: `status: all-children-complete`.
-   - End the session. Report: all children Done. Provide the delivery command: `Use polaris-run on <PARENT-ID>. Finalize delivery.`
-   - Do not push. Do not create a PR.
-5. If clusters.json exists, use it to determine execution order and dependencies. If absent, use the child issue ordering from Linear (lowest-numbered first) as a last-resort fallback — do not improvise ordering from chat reasoning or assumptions.
-6. Verify the selected child is not blocked in Linear. If blocked:
-   - Run `npm run polaris -- loop abort "<reason>"`.
-   - Report blocked state and halt. Do not skip to a later child.
-7. Set the selected child as `active_child`.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `current_step_id: 03-select-child`
-- `active_child: <ID>`
-- `updated_at: <timestamp>`
-
-If all children complete:
-- `status: all-children-complete`
-- `current_step_id: awaiting-delivery-request`
-
-Do not emit per-step `step-complete` telemetry. Telemetry is checkpoint-only (`run-start`, `child-dispatched`, child completion/checkpoint events, session end, and blocker/state-repair events).
-
-## Next step
-
-04-execute-child (or halt if all children complete or blocked)