@lsctech/polaris 0.1.1 → 0.2.0

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

@@ -0,0 +1,75 @@
+---
+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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,64 @@
+---
+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

@@ -0,0 +1,66 @@
+---
+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

@@ -0,0 +1,85 @@
+---
+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

@@ -0,0 +1,86 @@
+---
+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

@@ -0,0 +1,75 @@
+---
+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.

package/dist/workspace/workspace/.polaris/skills/polaris-reconcile/chain.json

@@ -0,0 +1,20 @@
+{
+  "name": "polaris-reconcile-chain",
+  "steps": [
+    "01-orient-reconcile",
+    "02-reconcile-polaris-md",
+    "03-reconcile-summary-md",
+    "04-reconcile-commit"
+  ],
+  "terminal_steps": ["04-reconcile-commit"],
+  "scope": "cognition-only",
+  "forbidden_actions": [
+    "src file mutations",
+    "runtime state file mutations",
+    "document ingestion or promotion",
+    "polaris loop continue",
+    "polaris finalize",
+    "git push",
+    "pr creation"
+  ]
+}

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

@@ -0,0 +1,67 @@
+---
+name: polaris-reconcile-chain
+description: Step order, CLI reference, canonical paths, run ID format, telemetry, and artifact authority for polaris-reconcile.
+---
+
+# polaris-reconcile chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query runtime state before acting. Do not infer affected folders or change scope from
+conversation context.
+
+## Step traversal order
+
+```text
+01-orient-reconcile
+02-reconcile-polaris-md
+03-reconcile-summary-md
+04-reconcile-commit
+```
+
+Read the current step's file in `steps/` before acting. Do not read ahead.
+
+## Canonical paths
+
+| State | Path |
+|---|---|
+| Skill state | `.taskchain_artifacts/polaris-reconcile/current-state.json` |
+| Telemetry | `.taskchain_artifacts/polaris-reconcile/runs/<run-id>/telemetry.jsonl` |
+
+## Run ID format
+
+`polaris-reconcile-<slug>-<YYYY-MM-DD>-<seq>` — e.g. `polaris-reconcile-POL-257-2026-06-04-001`
+
+## Telemetry
+
+Append-only JSONL. Required fields: `event`, `run_id`, `timestamp`.
+
+| Event | Trigger |
+|---|---|
+| `run-start` | Begin orient step |
+| `step-complete` | End of every step |
+| `polaris-md-updated` | POLARIS.md written for a folder |
+| `summary-md-updated` | SUMMARY.md written for a folder |
+| `reconcile-commit` | Commit created |
+| `reconcile-complete` | All steps done |
+
+## Artifact authority
+
+`.taskchain_artifacts/polaris-reconcile/current-state.json` is the sole authoritative
+live state surface.
+
+- Update after every completed step — before advancing.
+- A step is NOT complete until the state update succeeds.
+- If the update fails: stop and report the persistence failure.
+
+## Forbidden actions
+
+- src file mutations
+- runtime state file mutations
+- document ingestion or promotion
+- polaris loop continue
+- polaris finalize
+- git push
+- PR creation

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

@@ -0,0 +1,82 @@
+---
+name: polaris-reconcile-step-01
+description: Generate run_id, emit run-start telemetry, load packet, validate schema, and establish work_inventory.
+---
+
+# Step 01 — Orient reconcile
+
+## Purpose
+
+Establish bounded execution context before touching any files. Validate the packet,
+confirm which folders are in scope, and build the work inventory.
+
+## Actions
+
+### 1.1 Generate run_id
+
+Format: `polaris-reconcile-<issue-slug>-<YYYY-MM-DD>-<seq>`
+Example: `polaris-reconcile-POL-257-2026-06-04-001`
+
+### 1.2 Emit run-start telemetry
+
+First I/O action, before any file access:
+
+```bash
+mkdir -p .taskchain_artifacts/polaris-reconcile/runs/<run-id>
+echo '{"event":"run-start","run_id":"<run-id>","issue_id":"<issue_id>","timestamp":"<ISO>"}' \
+  >> .taskchain_artifacts/polaris-reconcile/runs/<run-id>/telemetry.jsonl
+```
+
+If this write fails: halt. Do not continue.
+
+### 1.3 Validate packet
+
+Confirm the packet contains all required fields:
+`run_id`, `issue_id`, `affected_folders`, `work_inventory`, `allowed_write_paths`,
+`prohibited_write_paths`, `constraints`
+
+If any required field is missing: halt and report which field is absent.
+
+### 1.4 Build work inventory snapshot
+
+From `packet.work_inventory`, confirm:
+- `affected_folders` — list of folder paths whose cognition may need updating
+- `all_changed_files` — files changed by the completed work
+- `child_summaries` — summaries of completed children (if cluster-based)
+- `pending_cognition_notes` — any pending cognition notes per folder
+- `polaris_md_files` — current POLARIS.md paths per folder
+- `summary_md_files` — current SUMMARY.md paths per folder
+
+If `affected_folders` is empty: record as no-op, skip to step 04.
+
+### 1.5 Restate working context
+
+Summarize in under 8 bullets:
+- `run_id` and fresh/resumed
+- Bound issue
+- Affected folders (count and paths)
+- `allowed_write_paths` count
+- `prohibited_write_paths` count
+
+## Scope declarations
+
+```yaml
+allowed_files:
+  - .polaris/skills/polaris-reconcile/SKILL.md
+  - .polaris/skills/polaris-reconcile/chain.md
+  - .taskchain_artifacts/polaris-reconcile/current-state.json
+  - packet (read only)
+stop_rules:
+  - run-start telemetry write fails
+  - packet missing required fields
+```
+
+## Artifact update
+
+Update `.taskchain_artifacts/polaris-reconcile/current-state.json`:
+- `run_id`, `issue_id`, `status: orienting`, `current_step_id: 01-orient-reconcile`
+- `affected_folders`, `updated_at: <timestamp>`
+
+## Next step
+
+02-reconcile-polaris-md