@lsctech/polaris 0.3.22 → 0.3.23

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/04-execute-child.md

@@ -1,75 +0,0 @@
----
-name: polaris-run-step-04-execute-child
-description: Implement the current child issue with the smallest scoped change possible.
----
-
-# Step 04 — Execute child
-
-## Purpose
-
-Execute only the selected child worker scope. In interactive-agent mode this step belongs inside the worker session dispatched by the execution adapter; the parent/orchestrator must not perform child implementation inline.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - files explicitly named by selected Linear child
-  - nearest POLARIS.md or INSTRUCTIONS.md for each edited path
-  - source files required by child acceptance criteria
-  - .taskchain_artifacts/polaris-run/current-state.json
-allowed_routes:
-  - CLAUDE.md
-  - docs/Polaris/spec/polaris-implementation-plan.md
-  - .polaris/skills/polaris-run/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - child acceptance criteria implemented
-  - touched paths match child scope
-  - no files outside child scope modified
-stop_rules:
-  - requested edit conflicts with existing architecture or doctrine
-  - implementation requires cross-cluster work
-  - same approach failed twice — stop and ask
-  - no edit made within 10 minutes — stop and ask
-```
-
-## Actions
-
-1. Confirm this is a worker execution context for the selected child. If this is a parent/orchestrator context with another open child to dispatch, return to step 07 and use the execution adapter instead of implementing inline.
-2. Re-fetch the current child issue from the issue tracker to confirm latest state, requirements, and any new blocking relationships.
-3. Identify the files relevant to this child. Inspect only those files.
-4. If a repo-analysis provider is configured and available: use it for targeted file or symbol lookup only. Otherwise use `polaris map query` and direct file inspection. Do not perform broad repo analysis regardless of which path is used.
-5. Make the smallest scoped change that satisfies the child's acceptance criteria.
-6. Do not touch files outside the child's scope.
-7. Do not perform unrelated cleanup.
-8. If a discovery falls outside the child's scope: note it as a follow-up — do not silently expand scope.
-
-### Failed Result Packet Detection
-
-If the worker returns a failed result packet (status: "failure"):
-1. Mark `triage_required: true` in the cluster state
-2. Record the failed result packet for Medic dispatch
-3. The Foreman will dispatch Medic in step 08 before Librarian
-4. Runnable sibling work continues in parallel with Medic dispatch
-
-## Blocker protocol
-
-If the child cannot proceed:
-
-```
-polaris loop abort "<reason>"
-```
-
-Halt. Report the unblock condition. Do not skip to later children.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `current_step_id: 04-execute-child`
-- `status: executing`
-- `updated_at: <timestamp>`
-
-## Next step
-
-05-validate-child

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/05-validate-child.md

@@ -1,57 +0,0 @@
----
-name: polaris-run-step-05-validate-child
-description: Validate the worker-returned child evidence and validation summary without re-implementing child work in the parent.
----
-
-# Step 05 — Validate child
-
-## Purpose
-
-Confirm the worker's returned child evidence is correct without re-implementing child work in the parent.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - changed files from current child
-  - test, lint, or build config needed for narrow validation
-  - .taskchain_artifacts/polaris-run/current-state.json
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-expected_evidence:
-  - narrowest useful validation command recorded
-  - validation result tied to current child scope
-  - unvalidated items explicitly listed
-stop_rules:
-  - validation command cannot run for environment reasons
-  - validation failure is outside child scope
-```
-
-## Actions
-
-1. Validate the worker return packet for the active child (child ID, status, commit hash when applicable, and validation summary).
-2. Do not implement fixes inline in the parent session. If changes are needed, dispatch a worker for the child scope.
-3. Do not run broad test suites — those belong in step 08.
-4. If validation fails and is within child scope: return to dispatch flow for worker remediation.
-5. If the failure is outside child scope: note it as a follow-up and proceed.
-6. Record the validation result:
-   - **Status**: `passed` | `failed` | `skipped`
-   - **Commands run**: names only (e.g., `npm run lint`, `npm test -- <file>`)
-   - **Count**: N passed / M failed
-   - **First error**: first failing check name only, if failed
-   - **Maximum**: 5–10 lines total — no raw stdout/stderr
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `validation_status: <passed | failed | skipped>`
-- `current_step_id: 05-validate-child`
-- `status: validating`
-- `updated_at: <timestamp>`
-
-Telemetry remains checkpoint-only. Do not emit per-step `step-complete` events.
-
-## Next step
-
-06-commit-and-update-linear

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/06-commit-and-update-linear.md

@@ -1,74 +0,0 @@
----
-name: polaris-run-step-06-commit-and-update-linear
-description: Record worker return outcomes for the active child and update Linear completion state without inline parent implementation.
----
-
-# Step 06 — Record completion and update Linear
-
-## Purpose
-
-Record worker-returned completion state, update Linear, and prepare for continuation decisions.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - changed files from current child
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .taskchain_artifacts/polaris-run/runs/*.jsonl
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-expected_evidence:
-  - worker return includes commit hash or explicit no-commit status
-  - parent completion record written only after return validation
-  - Linear evidence comment added with run_id
-  - child marked Done only after criteria pass
-stop_rules:
-  - unexpected files appear in diff
-  - Linear update or commit fails
-  - child acceptance criteria not met
-```
-
-## Actions
-
-1. Read the worker return for the active child and verify completion evidence (status, commit hash when applicable, and validation summary).
-2. Re-fetch the current child issue from Linear to get latest acceptance criteria.
-3. Add a concise evidence comment to the Linear child issue. The comment must open with:
-   ```yaml
-   run_id: <run_id>
-   skill: polaris-run
-   ```
-   Followed by: what was done, commit hash, validation result from step 05.
-4. Mark the child Done in Linear **only if** its acceptance criteria are satisfied.
-   - If criteria are not met: leave the child open, add a comment with the gap, treat as blocked.
-5. Do not run `npm run polaris -- map update --changed` per child. Map update belongs at final delivery/session end unless runtime requirements explicitly override this.
-
-## Blocker escalation
-
-If the child cannot be marked Done:
-- Run `npm run polaris -- loop abort "<reason>"`.
-- Add a comment with the unblock condition.
-- Halt. Do not continue to the next child.
-
-## Artifact update
-
-If no blocker:
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `current_step_id: 06-commit-and-update-linear`
-- `last_commit: <hash>`
-- `active_child` moved to `completed_children`
-- `context_budget.children_completed` incremented
-- `updated_at: <timestamp>`
-
-Telemetry remains checkpoint-only. Do not emit per-step `step-complete` events.
-
-If blocker escalation:
-- `status: blocked`
-- `current_step_id: halted`
-- `updated_at: <timestamp>`
-
-## Next step
-
-07-decide-continuation (or halted if blocker escalation triggered)

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/07-decide-continuation.md

@@ -1,89 +0,0 @@
----
-name: polaris-run-step-07-decide-continuation
-description: Run all eligible children via loop run, then decide continuation (DISPATCH / STOP / DELIVER).
----
-
-# Step 07 — Decide continuation
-
-## Purpose
-
-Execute the cluster's remaining children via the runtime's batch dispatch loop, then determine
-whether to continue, halt, or proceed to delivery.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .taskchain_artifacts/polaris-run/runs/*.jsonl
-  - .polaris/runs/current-state.json
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-expected_evidence:
-  - npm run polaris -- loop run executed
-  - RUNNING <child-id> (N/M) signal emitted per child
-  - COMPLETE <child-id> (commit: <sha>) signal emitted per child
-  - COMPLETE (cluster-complete) or blocked exit recorded
-stop_rules:
-  - loop run exits non-zero (blocked or error)
-  - budget exhausted in fixed-cap mode (children_completed >= budget.max_children from polaris.config.json)
-  - all children Done but delivery not yet requested
-```
-
-## Actions
-
-Run the batch dispatch loop:
-
-```bash
-npm run polaris -- loop run <cluster-id>
-```
-
-The runtime manages everything internally: child selection, packet compilation, provider dispatch
-(with automatic fallback through `providerPolicy.worker.providers`), CompactReturn validation,
-and state checkpointing. The Foreman must not call `loop dispatch` or `loop continue` individually.
-
-Monitor the subprocess output for progress signals:
-- `[POLARIS] RUNNING <child-id> (N/M)` — child dispatch started
-- `[POLARIS] COMPLETE <child-id> (commit: <sha>)` — child finished and checkpointed
-- `[POLARIS] COMPLETE (cluster-complete)` — all children done, subprocess exits 0
-
-Evaluate the exit to determine the decision:
-
-### DISPATCH (all remaining children) — default
-
-`loop run` dispatches all eligible children serially and exits when done. No per-child handling
-by the Foreman is needed. When `loop run` exits 0 with `cluster-complete`, proceed to STOP
-(all-done) or DELIVER.
-
-### STOP (blocked)
-
-If `loop run` exits non-zero:
-- Report the blocker and unblock condition from the output.
-- Do not push. Do not create a PR.
-- Resume instruction: resolve the blocker then run `npm run polaris -- loop run <cluster-id>`.
-
-### STOP (all-done, awaiting delivery)
-
-If `loop run` exits 0 and all children are Done but delivery was not explicitly requested:
-- Halt cleanly.
-- Report: all children Done, branch name, last commit.
-- Provide delivery command: `Use polaris-run on <PARENT-ID>. Finalize delivery.`
-- Do not push. Do not create a PR.
-
-### DELIVER
-
-Proceed to step 08 only if:
-- All children are Done (confirmed via runtime state).
-- The user explicitly requested delivery in this session invocation.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-run/current-state.json`:
-- `status: stopped`
-- `current_step_id: 07-decide-continuation`
-- `updated_at: <timestamp>`
-
-## Next step
-
-halted (STOP) or 08-closeout-librarian (DELIVER)

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/08-closeout-librarian.md

@@ -1,146 +0,0 @@
----
-name: polaris-run-step-08-closeout-librarian
-description: Dispatch the Closeout Librarian exactly once after cluster-complete. PR creation is blocked until the Librarian result is validated.
----
-
-# Step 08 — Closeout Librarian
-
-## Purpose
-
-The Closeout Librarian reconciles completed cluster work into project cognition and documentation.
-It runs exactly once per cluster, after all children complete and before PR creation.
-
-PR creation MUST NOT occur until this step succeeds.
-
-## Preconditions
-
-- All children in this cluster are confirmed Done.
-- The cluster state is `cluster-complete`.
-- The delivery branch is clean (no uncommitted worker changes).
-
-If any precondition fails: stop and report. Do not proceed.
-
-## Librarian Dispatch Model
-
-The Closeout Librarian is dispatched as a bounded session, separate from worker sessions.
-The Foreman:
-1. Generates the Librarian packet.
-2. Dispatches the Librarian as a subagent (same dispatch model as workers).
-3. Waits for the Librarian to write its sealed result JSON.
-4. Validates the result before proceeding to step 09.
-
-The Foreman does NOT:
-- Read the Librarian's session transcript.
-- Observe the Librarian's execution in detail.
-- Repair the Librarian's output manually.
-- Skip this step because the Librarian appears slow.
-
-## Actions
-
-### 8.1 Generate Librarian Packet
-
-Run:
-```bash
-npm run polaris -- librarian packet <cluster-id>
-```
-
-This generates a `CloseoutLibrarianPacket` at:
-`.polaris/clusters/<cluster-id>/librarian-packet-<dispatch-id>.json`
-
-The packet includes:
-- All completed child IDs, commit SHAs, changed files
-- All affected folder POLARIS.md and SUMMARY.md paths
-- All pending cognition note paths
-- SmartDocs raw paths for ingestion consideration
-- Run report path
-- Result path: `.polaris/clusters/<cluster-id>/librarian-result-<dispatch-id>.json`
-- Prohibited and allowed write paths
-
-If packet generation fails: stop and report. Do not dispatch.
-
-### 8.2 Dispatch Librarian Session
-
-Dispatch the Librarian as a bounded subagent session:
-```text
-Packet path: .polaris/clusters/<cluster-id>/librarian-packet-<dispatch-id>.json
-Role: closeout-librarian
-Skill: .polaris/skills/closeout-librarian/SKILL.md
-```
-
-The Librarian session prompt must contain ONLY the packet path. Do not add implementation
-instructions or context. The packet is the complete and authoritative instruction source.
-
-Dispatch boundary enforcement:
-- The Foreman does not inline the Librarian's work.
-- The Foreman waits for the sealed result file to appear at the packet's `result_path`.
-- The Foreman does not read the Librarian's transcript.
-
-### 8.3 Wait for Sealed Result
-
-Wait for the Librarian to write the sealed result JSON to `packet.result_path`.
-
-Timeout: 10 minutes (600 seconds). If timeout exceeded:
-1. Record blocker: `librarian-timeout`
-2. Escalate to operator with options:
-   - Re-dispatch Librarian
-   - Halt run
-
-### 8.4 Validate Librarian Result
-
-Read the sealed result JSON from `packet.result_path`.
-
-Validate:
-1. `result.role` must be `"closeout-librarian"`
-2. `result.run_id` must match the active run
-3. `result.dispatch_id` must match the dispatch
-4. `result.status` must be `"success"` or `"partial"` to proceed
-5. If `result.commit_sha` is non-null: verify the commit is in the current git log
-6. `result.files_committed` must not contain any path from `prohibited_write_paths`
-
-### 8.5 Decision
-
-| Result Status | Action |
-|---|---|
-| `"success"` | Proceed to step 09 |
-| `"partial"` | Proceed to step 09; record partial result in run state |
-| `"blocked"` | Halt; escalate to operator with blocker descriptions |
-| `"failure"` | Halt; escalate to operator with failure details |
-| Result file missing | Halt; escalate: librarian did not produce output |
-
-### 8.6 Record Librarian Result in State
-
-Update run state with the Librarian dispatch record:
-```json
-{
-  "librarian_dispatch_id": "<dispatch-id>",
-  "librarian_commit": "<commit_sha or null>",
-  "librarian_status": "<status>",
-  "librarian_completed_at": "<ISO timestamp>"
-}
-```
-
-## Scope Declarations
-
-```yaml
-allowed_files:
-  - .polaris/clusters/<cluster-id>/librarian-packet-*.json
-  - .polaris/clusters/<cluster-id>/librarian-result-*.json
-  - .taskchain_artifacts/polaris-run/current-state.json
-allowed_routes:
-  - .polaris/skills/closeout-librarian/SKILL.md
-  - .polaris/skills/closeout-librarian/chain.md
-expected_evidence:
-  - librarian packet generated
-  - librarian session dispatched
-  - sealed result written and validated
-  - librarian result recorded in run state
-stop_rules:
-  - preconditions not met
-  - packet generation fails
-  - librarian result status is "blocked" or "failure"
-  - result validation fails
-```
-
-## Next Step
-
-Proceed to step 09 (final delivery) only when librarian result status is `"success"` or `"partial"`.

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/08-final-delivery.md

@@ -1,91 +0,0 @@
----
-name: polaris-run-step-08-final-delivery
-description: Run polaris finalize to push, open the draft PR, emit JSONL closeout events, and archive the run snapshot.
----
-
-# Step 08 — Final delivery
-
-## Purpose
-
-Complete the parent cluster via `polaris finalize run` — the Polaris runtime handles push, PR, telemetry, and archive.
-
-## Preconditions (verify before proceeding)
-
-- All children in this parent cluster are marked Done in Linear.
-- The branch is clean (no uncommitted changes).
-
-If any precondition fails: stop and report the gap.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .taskchain_artifacts/polaris-run/runs/*.jsonl
-  - .taskchain_artifacts/polaris-run/run-report.md
-  - git log and branch metadata
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-expected_evidence:
-  - all children Done in Linear
-  - polaris finalize executed successfully
-  - PR URL recorded
-  - run-complete event in telemetry JSONL
-stop_rules:
-  - any child is not Done
-  - branch has uncommitted changes
-  - polaris finalize fails
-```
-
-## Actions
-
-1. Verify all children are Done in Linear (re-fetch, do not assume).
-2. Verify the working tree is clean.
-3. Run:
-   ```bash
-   npm run polaris -- finalize run
-   ```
-   `npm run polaris -- finalize run` executes the full 12-step sequence:
-   - Validates the Polaris map
-   - Validates `current-state.json` schema
-   - Runs targeted checks
-   - Generates `run-report.md`
-   - Commits any pending artifacts
-   - Pushes the branch
-   - Opens a draft PR targeting `main`
-   - Updates `current-state.json` to `status: complete`
-   - Appends `pr-opened` and `run-complete` events to telemetry JSONL
-   - Updates Linear parent with PR URL
-   - Archives the run snapshot to `.polaris/runs/<run-id>/`
-
-4. Add a final evidence comment to the Linear parent issue including the PR URL and `run_id`.
-
-## PR body requirements (handled by polaris finalize — verify the generated PR includes)
-
-- Completed child issue IDs and titles
-- Summary of files changed
-- Validation result
-- Residual risks (if any)
-- Run metadata footer:
-  ```text
-  ---
-  Run-ID: <run_id>
-  Skill: polaris-run
-  Tracker: linear / <parent_issue_id>
-  Related-Run-ID: <related_run_id or omit if null>
-  ```
-
-## Artifact update
-
-`polaris finalize` handles all artifact updates. Verify afterward:
-
-- `.taskchain_artifacts/polaris-run/current-state.json`: `status: complete`
-- `.taskchain_artifacts/polaris-run/run-report.md`: exists and complete
-- Telemetry JSONL: ends with `run-complete` event
-
-Do not report completion until these are verified.
-
-## Session end
-
-This is the terminal step.

package/dist/workspace/workspace/.polaris/skills/polaris-run/steps/09-final-delivery.md

@@ -1,104 +0,0 @@
----
-name: polaris-run-step-09-final-delivery
-description: Run polaris finalize to push, open the PR, emit JSONL closeout events, and archive the run snapshot. Proceeds only after Closeout Librarian succeeds.
----
-
-# Step 09 — Final Delivery
-
-## Purpose
-
-Complete the parent cluster via `polaris finalize run` — the Polaris runtime handles push,
-PR, telemetry, and archive.
-
-This step runs ONLY after the Closeout Librarian in step 08 has completed successfully
-(status: `"success"` or `"partial"`).
-
-## Preconditions (verify before proceeding)
-
-- All children in this parent cluster are marked Done in Linear.
-- Closeout Librarian completed (step 08) with status `"success"` or `"partial"`.
-- The branch is clean (no uncommitted changes beyond the librarian commit).
-
-If any precondition fails: stop and report the gap.
-
-## Scope Declarations
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/polaris-run/current-state.json
-  - .taskchain_artifacts/polaris-run/runs/*.jsonl
-  - .taskchain_artifacts/polaris-run/run-report.md
-  - git log and branch metadata
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-run/chain.md
-expected_evidence:
-  - closeout librarian completed (step 08)
-  - all children Done in Linear
-  - polaris finalize executed successfully
-  - PR URL recorded
-  - run-complete event in telemetry JSONL
-stop_rules:
-  - closeout librarian not completed or failed
-  - any child is not Done
-  - branch has uncommitted changes
-  - polaris finalize fails
-```
-
-## Actions
-
-1. Verify step 08 (Closeout Librarian) completed with `"success"` or `"partial"` status.
-2. Verify all children are Done in Linear (re-fetch, do not assume).
-3. Verify the working tree is clean.
-4. Run:
-   ```bash
-   npm run polaris -- map index && npm run polaris -- finalize run --state-file .taskchain_artifacts/polaris-run/current-state.json
-   ```
-
-   `map index` rebuilds the atlas so finalize has accurate route data. `finalize run` then executes the full finalize sequence:
-   - Validates the Polaris map
-   - Validates `current-state.json` schema
-   - Runs targeted checks
-   - Generates `run-report.md`
-   - Commits any pending artifacts
-   - Pushes the branch (including the librarian commit)
-   - Opens a draft PR targeting `main`
-   - Updates `current-state.json` to `status: complete`
-   - Appends `pr-opened` and `run-complete` events to telemetry JSONL
-   - Updates Linear parent with PR URL
-   - Archives the run snapshot to `.polaris/runs/<run-id>/`
-
-5. Add a final evidence comment to the Linear parent issue including the PR URL, `run_id`,
-   and `librarian_commit` SHA (from step 08).
-
-## PR Body Requirements (handled by polaris finalize — verify the generated PR includes)
-
-- Completed child issue IDs and titles
-- Summary of files changed
-- Validation result
-- Librarian commit SHA and summary (from step 08 result)
-- Residual risks (if any)
-- Run metadata footer:
-  ```text
-  ---
-  Run-ID: <run_id>
-  Skill: polaris-run
-  Tracker: linear / <parent_issue_id>
-  Librarian-Commit: <commit_sha or none>
-  Librarian-Status: <status>
-  Related-Run-ID: <related_run_id or omit if null>
-  ```
-
-## Artifact Update
-
-`polaris finalize` handles all artifact updates. Verify afterward:
-
-- `.taskchain_artifacts/polaris-run/current-state.json`: `status: complete`
-- `.taskchain_artifacts/polaris-run/run-report.md`: exists and complete
-- Telemetry JSONL: ends with `run-complete` event
-
-Do not report completion until these are verified.
-
-## Session End
-
-This is the terminal step.