@lsctech/polaris 0.3.21 → 0.3.23

package/dist/workspace/workspace/.polaris/skills/polaris-medic/SKILL.md

@@ -1,52 +0,0 @@
----
-name: polaris-medic
-description: Diagnose and repair failed worker executions, create medical charts, and prepare for Librarian reconciliation.
-role: medic
-role_file: .polaris/roles/medic.md
----
-
-## Entry Points
-
-This skill is invoked by the Foreman as a dispatched session when a worker returns a failed result packet.
-
-Invocation: The Foreman dispatches Medic after detecting a failed result packet and marking triage required. The packet path is passed as the session prompt.
-
----
-
-## Polaris Skill Bootloader
-
-This skill does NOT use the standard Polaris skill bootloader. The Medic receives its packet directly from the Foreman — the packet is the sole authoritative instruction source for this session.
-
-The Medic MUST:
-1. Read the packet at the path provided in the dispatch prompt.
-2. Validate the packet schema (role must be `"medic"`).
-3. Execute `chain.md` in strict step order.
-4. Write the sealed result to `packet.result_path` before the session ends.
-
-If the packet cannot be read or fails schema validation, write a failure result immediately and terminate. Do not attempt to reconstruct the packet from context.
-
----
-
-## Authority Reminder
-
-The Medic may modify implementation code to repair failures. The Medic may create charts in `smartdocs/medic/charts/`. The Medic does NOT modify runtime state, dispatch workers, or perform normal implementation work.
-
-Full authority boundaries: `.polaris/roles/medic.md`
-
----
-
-## Packet Schema
-
-The packet is a `MedicPacket`. See:
-- `src/types/result-packet.ts` for TypeScript types
-- This packet includes the failed worker result packet and cluster context
-
-Required packet fields: `role`, `run_id`, `dispatch_id`, `cluster_id`, `failed_result_packet`, `cluster_context`, `result_path`, `allowed_write_paths`, `prohibited_write_paths`.
-
----
-
-## Execution
-
-Read `chain.md` and execute steps in strict order.
-
-Do not skip steps. Do not reorder steps.

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

@@ -1,111 +0,0 @@
----
-name: polaris-medic-chain
-description: Step-order execution map for the Medic role. Dispatched when worker execution fails.
----
-
-# Medic Chain
-
-## Authority
-
-**The packet is authoritative. Do not infer cluster scope or conversation context.**
-
-Read the packet before any analysis. Execute steps in strict order.
-
-## Scope Contract
-
-The Medic operates on implementation repair and chart creation only.
-
-**Allowed writes:** Implementation code (repair only), `smartdocs/medic/charts/` (chart creation), sealed result JSON, medic commit.
-
-**Prohibited writes:** Runtime state files, telemetry JSONL, cluster plan, issue tracker status, POLARIS.md, SUMMARY.md (Librarian responsibility).
-
----
-
-## Step Traversal Order
-
-```text
-01-orient-medic       ← Read packet, load failed result, build diagnosis inventory
-02-diagnose           ← Analyze failure, identify root cause, determine repair strategy
-03-repair             ← Execute repair changes to implementation code
-04-validate           ← Verify repair resolves the failure
-05-create-chart       ← Create medical chart documenting the failure and treatment
-06-closeout           ← Commit repair changes, write sealed result, terminate
-```
-
-All steps must complete in order. Termination after step 06 is mandatory.
-
----
-
-## Execution Rules
-
-### Step Gate Behavior
-
-- Each step must complete before the next begins.
-- If a step encounters a recoverable error (e.g., diagnosis uncertain), record the blocker and continue with best-effort repair.
-- If a step encounters a fatal error (e.g., packet unreadable, commit fails), record `status: "failure"` in the result and proceed to step 06 (sealed result write).
-- Do not skip to step 06 for recoverable errors — complete the remaining steps.
-
-### Write Discipline
-
-Before writing any file, verify it is in `packet.allowed_write_paths`.
-If the target file is in `packet.prohibited_write_paths`, skip and record as blocker.
-
-### Commit Timing
-
-All repair writes occur during step 03. Chart creation occurs during step 05.
-Step 06 creates exactly one git commit containing all changes from this session.
-If no repair or chart was created (e.g., diagnosis deferred), step 06 makes no commit.
-The result records `commit_sha: null` in this case — do not create an empty commit.
-
-### Result Timing
-
-Step 06 writes the sealed result JSON and terminates. No further writes are permitted after the sealed result is written.
-
----
-
-## Narration Rules
-
-The Medic does NOT produce user-facing narration during normal execution.
-
-**Allowed output:**
-- The sealed result JSON written to `result_path` (step 06)
-- Escalation output if blocked on a decision that requires operator input
-
-**Prohibited output:**
-- Step-by-step progress narration
-- Summary of diagnosis or repair
-- Interim status updates
-
-All communication with the Foreman occurs through the sealed result and the commit record.
-
----
-
-## Telemetry Events
-
-Emit the following structured events to the telemetry file (if path provided in packet):
-
-| Event | Step | Fields |
-|---|---|---|
-| `medic-start` | 01 | `run_id`, `cluster_id`, `dispatch_id`, `timestamp` |
-| `medic-step-complete` | each step | `step`, `run_id`, `timestamp`, `outcome` |
-| `medic-commit` | 06 | `commit_sha`, `files_changed`, `timestamp` |
-| `medic-complete` | 06 | `status`, `run_id`, `timestamp` |
-
-If no telemetry file is specified in the packet, skip telemetry events silently.
-
----
-
-## Failure Handling
-
-| Condition | Action |
-|---|---|
-| Packet unreadable | Write failure result to `result_path` if possible, otherwise stderr. Terminate. |
-| Packet schema invalid | Write failure result, terminate |
-| Diagnosis uncertain | Record blocker, proceed to repair with best-effort or deferred treatment |
-| Repair fails | Status: failure, record repair error, proceed to step 06 |
-| Validation fails | Status: partial, record validation failure, proceed to chart creation |
-| Chart creation fails | Status: partial, record chart error, proceed to step 06 |
-| Commit fails | Status: failure, record commit error, proceed to step 06 |
-| Result write fails | Stderr only. Cannot recover. |
-| All blockers, no writes | Status: `"blocked"`, list blockers, commit nothing |
-| Some work done, some blocked | Status: `"partial"`, describe both |

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

@@ -1,75 +0,0 @@
----
-name: polaris-medic-step-01
-description: Read packet, load failed result, and build the diagnosis inventory for this session.
----
-
-# Step 01 — Orient Medic
-
-## Purpose
-
-Build a complete picture of the failure event. This is the foundation for all subsequent diagnosis and repair steps. Nothing is written in this step.
-
-## Actions
-
-### 1.1 Read and Validate Packet
-
-Read the packet from the path provided in the dispatch prompt.
-
-Validate required fields:
-- `role` must be `"medic"`
-- `run_id`, `dispatch_id`, `cluster_id` must be present and non-empty
-- `failed_result_packet` must be present
-- `result_path` must be present
-- `allowed_write_paths` must be present
-
-If validation fails: write a minimal failure result to `result_path` and terminate.
-
-### 1.2 Load Failed Result Packet
-
-Read the failed result packet from `packet.failed_result_packet`.
-
-Extract:
-- Child ID that failed
-- Error message
-- Files that were changed (if any)
-- Validation failures (if any)
-- Execution context (if any)
-
-### 1.3 Load Cluster Context
-
-Load cluster context from `packet.cluster_context`.
-
-Extract:
-- Cluster ID
-- Branch name
-- Related work items
-- Route information (if available)
-
-### 1.4 Build Diagnosis Inventory
-
-Produce an internal inventory (not written to disk):
-
-```yaml
-diagnosis_inventory:
-  cluster_id: <from packet>
-  failed_child_id: <from failed_result_packet>
-  error_message: <from failed_result_packet>
-  changed_files: <from failed_result_packet>
-  validation_failures: <from failed_result_packet>
-  execution_context: <from failed_result_packet>
-  route: <from cluster_context>
-  branch: <from cluster_context>
-```
-
-### 1.5 Emit Telemetry
-
-Emit `medic-start` event (if telemetry path provided).
-
-## Completion Criteria
-
-- Packet validated
-- Failed result packet loaded
-- Cluster context loaded
-- Diagnosis inventory built
-
-Proceed to step 02.

package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/02-diagnose.md

@@ -1,79 +0,0 @@
----
-name: polaris-medic-step-02
-description: Analyze the failure, identify root cause, and determine repair strategy.
----
-
-# Step 02 — Diagnose
-
-## Purpose
-
-Analyze the failure event to understand what went wrong and determine a repair strategy. This step does not make any changes to the codebase.
-
-## Actions
-
-### 2.1 Analyze Error Message
-
-Examine the error message from the failed result packet:
-- What type of error occurred?
-- Which file or component is implicated?
-- Is this a syntax error, runtime error, validation error, or test failure?
-
-### 2.2 Examine Changed Files
-
-Review the files that were changed by the failed worker:
-- Do the changes introduce syntax errors?
-- Do the changes break existing functionality?
-- Are there missing dependencies or imports?
-- Are there type mismatches?
-
-### 2.3 Identify Root Cause
-
-Based on the error analysis and file examination, identify the root cause:
-
-Common root causes:
-- Syntax error in introduced code
-- Missing or incorrect dependency
-- Type mismatch or type error
-- Logic error in implementation
-- Test failure due to incorrect expectations
-- Configuration error
-- Environment mismatch
-
-### 2.4 Determine Repair Strategy
-
-Based on the root cause, determine the appropriate repair strategy:
-
-Repair strategies:
-- Fix syntax errors
-- Add missing dependencies
-- Correct type annotations
-- Adjust logic implementation
-- Update test expectations
-- Fix configuration
-- Document environment requirements
-
-If the root cause is unclear or the repair strategy is uncertain, record this as a blocker and proceed with best-effort repair or defer treatment.
-
-### 2.5 Record Diagnosis
-
-Record the diagnosis internally (not written to disk):
-
-```yaml
-diagnosis:
-  root_cause: <identified root cause>
-  repair_strategy: <chosen repair strategy>
-  uncertainty: <any doubts or blockers>
-  deferred: <true if treatment deferred>
-```
-
-### 2.6 Emit Telemetry
-
-Emit `medic-step-complete` event for step 02 (if telemetry path provided).
-
-## Completion Criteria
-
-- Error analyzed
-- Root cause identified (or uncertainty recorded)
-- Repair strategy determined (or deferred)
-
-Proceed to step 03.

package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/03-repair.md

@@ -1,64 +0,0 @@
----
-name: polaris-medic-step-03
-description: Execute repair changes to implementation code based on diagnosis.
----
-
-# Step 03 — Repair
-
-## Purpose
-
-Execute the repair strategy identified in step 02 to fix the failure. This step makes changes to implementation code only.
-
-## Actions
-
-### 3.1 Verify Write Permissions
-
-Before making any changes, verify that the target files are in `packet.allowed_write_paths` and not in `packet.prohibited_write_paths`.
-
-If a target file is prohibited, skip and record as a blocker.
-
-### 3.2 Execute Repair Strategy
-
-Apply the repair strategy determined in step 02:
-
-- **Syntax errors**: Fix syntax in the identified files
-- **Missing dependencies**: Add missing imports or dependencies
-- **Type mismatches**: Correct type annotations
-- **Logic errors**: Adjust the implementation logic
-- **Test failures**: Update test expectations or fix implementation
-- **Configuration errors**: Fix configuration files
-- **Environment issues**: Document requirements (do not change environment)
-
-Make the smallest scoped change that addresses the root cause.
-
-### 3.3 Verify Repair Completeness
-
-After applying the repair, verify:
-- The identified root cause is addressed
-- No new syntax errors are introduced
-- Changes are within the scope of the failed child's work
-
-If the repair cannot be completed (e.g., root cause unclear, changes too broad), record this as a blocker.
-
-### 3.4 Record Changes
-
-Record the changes made internally (not written to disk):
-
-```yaml
-repair_changes:
-  files_modified: [<list of files>]
-  changes_summary: <brief description of changes>
-  blockers: [<any blockers encountered>]
-```
-
-### 3.5 Emit Telemetry
-
-Emit `medic-step-complete` event for step 03 (if telemetry path provided).
-
-## Completion Criteria
-
-- Repair strategy executed (or blocked)
-- Changes made are minimal and scoped
-- No prohibited files were modified
-
-Proceed to step 04.

package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/04-validate.md

@@ -1,66 +0,0 @@
----
-name: polaris-medic-step-04
-description: Verify that the repair resolves the failure.
----
-
-# Step 04 — Validate
-
-## Purpose
-
-Verify that the repair changes successfully resolve the original failure. This step runs validation to confirm the fix works.
-
-## Actions
-
-### 4.1 Run Validation Commands
-
-Run the validation commands specified in the failed result packet or cluster context:
-
-Common validation commands:
-- `npm run build` — verify TypeScript compilation
-- `npm test` — verify test suite passes
-- Specific test commands for the affected route
-
-If no validation commands are specified, run:
-- `npm run build`
-- `npm test`
-
-### 4.2 Analyze Validation Results
-
-Examine the validation output:
-- Did the build succeed?
-- Did the tests pass?
-- Are there any remaining errors related to the original failure?
-
-### 4.3 Determine Validation Outcome
-
-Based on the validation results, determine the outcome:
-
-- **Success**: All validation passes, original failure resolved
-- **Partial**: Some validation passes, but issues remain
-- **Failure**: Validation still fails, repair unsuccessful
-
-If validation fails, record this as a blocker. The Medic may proceed to chart creation to document the partial treatment.
-
-### 4.4 Record Validation Result
-
-Record the validation result internally (not written to disk):
-
-```yaml
-validation_result:
-  outcome: <success | partial | failure>
-  build_passed: <true | false>
-  tests_passed: <true | false>
-  remaining_errors: [<any remaining errors>]
-```
-
-### 4.5 Emit Telemetry
-
-Emit `medic-step-complete` event for step 04 (if telemetry path provided).
-
-## Completion Criteria
-
-- Validation commands executed
-- Validation outcome determined
-- Result recorded
-
-Proceed to step 05.

package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/05-create-chart.md

@@ -1,85 +0,0 @@
----
-name: polaris-medic-step-05
-description: Create a medical chart documenting the failure and treatment.
----
-
-# Step 05 — Create Chart
-
-## Purpose
-
-Create a medical chart in `smartdocs/medic/charts/` documenting the failure event, diagnosis, treatment, and validation outcome. This chart becomes part of the repository's medical history.
-
-## Actions
-
-### 5.1 Generate Chart ID
-
-Use the chart ID generator from the Chart system (POL-327):
-- Import `generateNextChartId` from `src/medic/chart-id.ts`
-- Generate the next chart ID for today
-- Charts directory: `smartdocs/medic/charts/`
-
-### 5.2 Prepare Chart Front-Matter
-
-Prepare the YAML front-matter for the chart:
-
-```yaml
----
-chart_id: <generated chart ID>
-cluster_id: <from packet>
-route: <from cluster context>
-status: <open | resolved | deferred>
-related_charts: []
-created: <ISO8601 timestamp>
-updated: <ISO8601 timestamp>
-drift_observations: []
----
-```
-
-Set status based on validation outcome:
-- `resolved` if validation succeeded
-- `deferred` if validation failed or repair was incomplete
-- `open` if diagnosis was uncertain
-
-### 5.3 Prepare Chart Sections
-
-Write the required chart sections:
-
-- **Problem**: Description of the original failure
-- **Symptoms**: Error messages, validation failures, observable behavior
-- **Root Cause**: Identified root cause from step 02
-- **Affected Files**: List of files involved in the failure and repair
-- **Treatment**: Description of repair changes made in step 03
-- **Validation**: Validation outcome from step 04
-- **Prevention**: Recommendations to prevent similar failures
-- **When To Read This Chart**: Conditions under which this chart is relevant
-
-### 5.4 Write Chart File
-
-Write the chart to `smartdocs/medic/charts/<chart_id>.md`
-
-Verify the chart passes schema validation using the Chart system (POL-327):
-- Front-matter must match `ChartFrontMatter` schema
-- All required sections must be present
-
-### 5.5 Record Chart Creation
-
-Record the chart creation internally (not written to disk):
-
-```yaml
-chart_created:
-  chart_id: <generated chart ID>
-  file_path: <path to chart file>
-  validation_passed: <true | false>
-```
-
-### 5.6 Emit Telemetry
-
-Emit `medic-step-complete` event for step 05 (if telemetry path provided).
-
-## Completion Criteria
-
-- Chart ID generated
-- Chart file created with valid front-matter and sections
-- Chart passes schema validation
-
-Proceed to step 06.

package/dist/workspace/workspace/.polaris/skills/polaris-medic/steps/06-closeout.md

@@ -1,86 +0,0 @@
----
-name: polaris-medic-step-06
-description: Commit repair changes, write sealed result, and terminate.
----
-
-# Step 06 — Closeout
-
-## Purpose
-
-Commit all changes from this session (repairs and chart), write the sealed result, and terminate. This is the final step.
-
-## Actions
-
-### 6.1 Determine Commit Strategy
-
-Based on the work completed:
-- If repairs were made and/or chart was created: create a commit
-- If no changes were made (e.g., diagnosis deferred): do not create a commit
-
-### 6.2 Create Commit (if changes exist)
-
-If changes were made:
-1. Stage all modified files
-2. Create a commit with message:
-
-```
-[POL-326] Medic: <brief description of repair>
-
-Generated with [Devin](https://cli.devin.ai/docs)
-
-Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
-```
-
-3. Record the commit SHA
-
-If no changes were made, set `commit_sha: null`.
-
-### 6.3 Prepare Sealed Result
-
-Prepare the sealed result JSON:
-
-```json
-{
-  "run_id": "<from packet>",
-  "dispatch_id": "<from packet>",
-  "cluster_id": "<from packet>",
-  "status": "<success | partial | failure | blocked>",
-  "commit_sha": "<commit SHA or null>",
-  "chart_id": "<chart ID or null>",
-  "diagnosis": {
-    "root_cause": "<root cause>",
-    "repair_strategy": "<repair strategy>"
-  },
-  "validation": {
-    "outcome": "<success | partial | failure>",
-    "build_passed": <true | false>,
-    "tests_passed": <true | false>
-  },
-  "blockers": [<any blockers encountered>],
-  "timestamp": "<ISO8601 timestamp>"
-}
-```
-
-Set status based on overall outcome:
-- `success`: Repair completed, validation passed, chart created
-- `partial`: Some work done, but blockers remain
-- `failure`: Fatal error encountered
-- `blocked`: All work blocked
-
-### 6.4 Write Sealed Result
-
-Write the sealed result JSON to `packet.result_path`.
-
-If the write fails, output to stderr and terminate (cannot recover).
-
-### 6.5 Emit Telemetry
-
-Emit `medic-commit` event (if commit created) and `medic-complete` event (if telemetry path provided).
-
-## Completion Criteria
-
-- Commit created (if changes were made)
-- Sealed result written to result_path
-- Telemetry events emitted
-
-Terminate session. No further steps.

package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/SKILL.md

@@ -1,75 +0,0 @@
----
-name: polaris-reconcile
-description: Update POLARIS.md and SUMMARY.md files to reflect completed work. Callable at will — does not require a cluster closeout. Uses the Polaris packet for work context.
-role: librarian
----
-
-## Polaris Skill Bootloader
-
-**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
-
-Run the following command:
-
-```bash
-npm run polaris -- skill packet reconcile
-```
-
-- Do not begin work until a packet is returned.
-- Treat the packet as your authoritative instruction source.
-- If no packet is produced, stop and report: **Polaris could not authorize this run.**
-
----
-
-# polaris-reconcile
-
-Use this skill to reconcile project cognition after completed work — updating POLARIS.md and
-SUMMARY.md files to reflect current reality. This is the standalone form of the cognition
-reconciliation steps performed by the Closeout Librarian, callable at will rather than only
-at cluster closeout.
-
-## When to use
-
-- "Reconcile the docs after POL-257"
-- "Update POLARIS.md and SUMMARY.md for this run"
-- "Run polaris-reconcile on POL-303"
-- After a run completes and you want cognition updated without waiting for full closeout
-
-## How to execute
-
-1. Read `chain.md` — step order and rules.
-2. Read `.taskchain_artifacts/polaris-reconcile/current-state.json` — resumable state.
-3. Execute steps in the order `chain.md` defines. Do not skip steps.
-4. After every completed step, update `current-state.json` before advancing.
-
-## Hard rules — what polaris-reconcile may do
-
-- Read packet-specified folders and their POLARIS.md and SUMMARY.md files
-- Write POLARIS.md and SUMMARY.md files within `packet.allowed_write_paths`
-- Create a single sealed git commit of all cognition changes
-
-## Hard rules — what polaris-reconcile must NOT do
-
-- Modify implementation source code (`src/`, tests, config)
-- Modify runtime state files outside this skill's owned artifacts (cluster-state, other skills' `.taskchain_artifacts/` state, or non-reconcile telemetry)
-- Move, ingest, classify, or promote documents
-- Call `npm run polaris -- loop continue` or `npm run polaris -- finalize`
-- Write to `packet.prohibited_write_paths`
-- Git push or create PRs
-
-## Packet schema
-
-The packet is a `ReconcilePacket`. Required fields:
-
-| Field | Description |
-|---|---|
-| `run_id` | Identifier for this reconcile run |
-| `issue_id` | Bound issue (e.g. `POL-257`) |
-| `affected_folders` | Folders whose POLARIS.md and/or SUMMARY.md may need updating |
-| `work_inventory` | Summary of completed work: changed files, child summaries, cognition notes |
-| `allowed_write_paths` | Paths this skill may write |
-| `prohibited_write_paths` | Paths this skill must not write |
-| `constraints.max_summary_addition_lines` | Net new line cap per SUMMARY.md update (default: 50) |
-
-## Execution
-
-Read `chain.md` and execute steps in strict order. Do not skip steps. Do not reorder steps.