@lsctech/polaris 0.1.1 → 0.2.0

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

@@ -0,0 +1,85 @@
+---
+name: polaris-catalog-chain
+description: Step order, CLI reference, canonical paths, run ID format, telemetry, and artifact authority for polaris-catalog.
+---
+
+# polaris-catalog chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query runtime state before acting. Do not infer affected folders, doc classifications, or
+change scope from conversation context.
+
+## Step traversal order
+
+```text
+01-orient-catalog
+02-reconcile-polaris-md
+03-reconcile-summary-md
+04-classify-and-place
+05-catalog-commit
+```
+
+Read the current step's file in `steps/` before acting. Do not read ahead.
+
+## CLI
+
+Always use the repo-local Polaris CLI:
+
+```
+npm run polaris -- docs ingest --file <path>
+npm run polaris -- doctrine draft <path>
+npm run polaris -- map update --changed
+```
+
+Never assume a globally linked `polaris` command exists.
+
+## Canonical paths
+
+| State | Path |
+|---|---|
+| Doc drop zone | `smartdocs/raw/` |
+| Skill state | `.taskchain_artifacts/polaris-catalog/current-state.json` |
+| Telemetry | `.taskchain_artifacts/polaris-catalog/runs/<run-id>/telemetry.jsonl` |
+
+## Run ID format
+
+`polaris-catalog-<slug>-<YYYY-MM-DD>-<seq>` — e.g. `polaris-catalog-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 |
+| `doc-classified` | Classification assigned per file in raw |
+| `doc-placed` | File moved via CLI |
+| `doc-held` | Low-confidence file left in raw |
+| `catalog-commit` | Commit created |
+| `catalog-complete` | All steps done |
+
+## Artifact authority
+
+`.taskchain_artifacts/polaris-catalog/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
+- polaris loop continue
+- polaris finalize
+- git push
+- PR creation
+- mv/cp on files under smartdocs/ (use CLI)
+- auto-placing low-confidence files

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

@@ -0,0 +1,92 @@
+---
+name: polaris-catalog-step-01
+description: Generate run_id, emit run-start telemetry, validate packet, establish work_inventory, and enumerate smartdocs/raw/ for classification.
+---
+
+# Step 01 — Orient catalog
+
+## Purpose
+
+Establish bounded execution context before touching any files. Validate the packet,
+confirm cognition scope, and enumerate `smartdocs/raw/` for the classification step.
+
+## Actions
+
+### 1.1 Generate run_id
+
+Format: `polaris-catalog-<issue-slug>-<YYYY-MM-DD>-<seq>`
+Example: `polaris-catalog-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-catalog/runs/<run-id>
+echo '{"event":"run-start","run_id":"<run-id>","issue_id":"<issue_id>","unattended":<bool>,"timestamp":"<ISO>"}' \
+  >> .taskchain_artifacts/polaris-catalog/runs/<run-id>/telemetry.jsonl
+```
+
+If this write fails: halt. Do not continue.
+
+### 1.3 Validate packet
+
+Confirm required fields are present:
+`run_id`, `issue_id`, `affected_folders`, `work_inventory`, `unattended`,
+`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` — folders 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` — 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 cognition scope as no-op, continue to step 04 to
+still process any docs in `smartdocs/raw/`.
+
+### 1.5 Enumerate smartdocs/raw/
+
+List all files currently in `smartdocs/raw/` (excluding `.provenance.json` sidecars and
+hidden files). This is the batch for step 04.
+
+If `smartdocs/raw/` is empty or does not exist: record doc classification as no-op.
+Continue — cognition steps may still have work to do.
+
+### 1.6 Restate working context
+
+Summarize in under 10 bullets:
+- `run_id` and fresh/resumed
+- Bound issue
+- Mode: interactive or unattended
+- Affected folders for cognition (count)
+- Files in `smartdocs/raw/` for classification (count)
+
+## Scope declarations
+
+```yaml
+allowed_files:
+  - .polaris/skills/polaris-catalog/SKILL.md
+  - .polaris/skills/polaris-catalog/chain.md
+  - .taskchain_artifacts/polaris-catalog/current-state.json
+  - smartdocs/raw/ (enumerate only)
+  - packet (read only)
+stop_rules:
+  - run-start telemetry write fails
+  - packet missing required fields
+```
+
+## Artifact update
+
+Update `.taskchain_artifacts/polaris-catalog/current-state.json`:
+- `run_id`, `issue_id`, `unattended`, `status: orienting`, `current_step_id: 01-orient-catalog`
+- `affected_folders`, `raw_files: [...]`, `updated_at: <timestamp>`
+
+## Next step
+
+02-reconcile-polaris-md

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/02-reconcile-polaris-md.md

@@ -0,0 +1,33 @@
+---
+name: polaris-catalog-step-02
+description: Update affected POLARIS.md files to accurately reflect the current state of each folder after the completed work.
+---
+
+# Step 02 — Reconcile POLARIS.md
+
+Identical in behavior to `polaris-reconcile` step 02. See
+`.polaris/skills/polaris-reconcile/steps/02-reconcile-polaris-md.md` for full detail.
+
+## Summary
+
+For each folder in `work_inventory.affected_folders`:
+1. Assess which files changed and how they affect the folder's operational reality.
+2. Read the current POLARIS.md.
+3. Apply the confidence threshold (≥0.85 write, 0.70–0.84 write with note, <0.70 skip).
+4. Write the full updated POLARIS.md if needed — full replacement, not append.
+5. Record in `polaris_md_updates`.
+
+POLARIS.md is NOT a changelog. Replace stale statements with current truth.
+
+## Output
+
+```yaml
+polaris_md_updates: [
+  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
+  ...
+]
+```
+
+## Next step
+
+03-reconcile-summary-md

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/03-reconcile-summary-md.md

@@ -0,0 +1,70 @@
+---
+name: polaris-catalog-step-03
+description: Refresh SUMMARY.md files to reflect current project state after the completed work.
+---
+
+# Step 03 — Reconcile SUMMARY.md
+
+Identical in behavior to `polaris-reconcile` step 03. See
+`.polaris/skills/polaris-reconcile/steps/03-reconcile-summary-md.md` for full detail.
+
+## Summary
+
+For each folder in `work_inventory.affected_folders` that has a SUMMARY.md:
+1. Assess staleness against the completed work.
+2. Remove stale information. Replace superseded references. Preserve current understanding.
+3. Write the full updated SUMMARY.md — net new line cap of `packet.constraints.max_summary_addition_lines` (default: 50).
+4. Record in `summary_md_updates`.
+
+SUMMARY.md is NOT a changelog. It must read as a coherent current-state snapshot.
+
+## Required Structure (per June 5 doctrine)
+
+SUMMARY.md must contain the following sections:
+
+### Current State
+Brief description of what is implemented, what is not yet, and known gaps.
+
+### Route Health
+Current operational condition. Example subsections:
+- Healthy
+- Monitoring
+- Known Issues
+- Recent Treatments
+- Improvement Opportunities
+
+Goal: Workers understand route condition in under 10 seconds. Not history, not doctrine, not implementation detail.
+
+### Canonical References
+YAML block listing navigation paths (not reading assignments):
+
+```yaml
+canonical_docs:
+  - smartdocs/active/runtime/worker-packet-contract.md
+  - smartdocs/active/runtime/librarian-closeout.md
+  - POLARIS.md
+```
+
+These are retrieval paths, not preload instructions.
+
+## Reconciliation Behavior
+
+- Do NOT overwrite an existing Route Health section if it has content
+- Do NOT auto-populate Route Health status from runtime data — scaffold a skeleton only
+- Canonical References block must use the `canonical_docs:` key
+- Preserve any existing valid content; only update stale state sections
+
+## Output
+
+```yaml
+summary_md_updates: [
+  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
+  { file: "<path>", action: "no_change" },
+  { file: "<path>", action: "path_not_allowed" },
+  ...
+]
+```
+
+## Next step
+
+04-classify-and-place

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/04-classify-and-place.md

@@ -0,0 +1,117 @@
+---
+name: polaris-catalog-step-04
+description: Classify documents in smartdocs/raw/, auto-place high-confidence files via CLI, and surface or hold low-confidence files based on mode.
+---
+
+# Step 04 — Classify and place
+
+## Purpose
+
+Process all files enumerated in `current-state.json.raw_files`. Classify each one,
+auto-place high-confidence results via the Polaris CLI, and handle low-confidence files
+according to the session mode (`packet.unattended`).
+
+If `raw_files` is empty: record as no-op and proceed to step 05.
+
+## Classification table
+
+| Class | Target path | Auto-place on high confidence |
+|---|---|---|
+| `runtime-summary` | `smartdocs/runtime/summaries/` | yes |
+| `run-report` | `smartdocs/runtime/run-reports/` | yes |
+| `spec-raw` | `smartdocs/raw/` | no-op (already there) |
+| `spec-active` | `smartdocs/specs/active/` | yes |
+| `audit-finding` | `smartdocs/audits/findings/` | yes |
+| `doctrine-candidate` | `smartdocs/doctrine/candidate/` | yes |
+| `architecture` | `smartdocs/architecture/` | yes |
+| `decision` | `smartdocs/decisions/` | yes |
+| `deprecated-noise` | `smartdocs/runtime/generated/` | yes |
+
+**Confidence is the only gate.** High confidence → place regardless of authority level.
+Low confidence → ask user (interactive) or leave in raw (unattended).
+
+## Classification process (per file)
+
+1. Read the document.
+2. Check for explicit Polaris front-matter (`status`, `authority`, `classification`).
+   If present and unambiguous → **confidence: high**.
+3. Otherwise infer from content signals:
+   - Polaris architectural assertions / "how things should work" → `doctrine-candidate`
+   - Structured spec with Spec ID, Status, Purpose headings → `spec-active`
+   - Run output, telemetry summaries, session notes → `runtime-summary`
+   - Structured run output with metrics → `run-report`
+   - `FINDING:` markers or audit-style analysis → `audit-finding`
+   - ADR-style decision record → `decision`
+   - Architectural diagrams or structural design context → `architecture`
+   - Low-signal, transient, or auto-generated → `deprecated-noise`
+   - Unclear or multiple signals → low confidence, class remains `spec-raw`
+4. Assign confidence:
+   - **high**: explicit front-matter, or exactly one signal matches unambiguously
+   - **low**: multiple signals, sparse content, or no clear signal
+
+## Placement actions
+
+### High confidence
+
+Run the appropriate CLI command immediately. Do not pause for user input.
+
+```bash
+# All classes except doctrine-candidate:
+npm run polaris -- docs ingest --file <path>
+
+# doctrine-candidate:
+npm run polaris -- doctrine draft <path>
+```
+
+Record in `docs_placed`.
+
+### Low confidence — interactive mode (`packet.unattended: false`)
+
+Surface each file to the user:
+
+```text
+needs-input: <filename>
+Inferred class: <class> [confidence: low]
+Reason: <why confidence is low>
+Where should this go? Options:
+  1. <class> → <target>  (inferred)
+  2. Leave in smartdocs/raw/
+  3. [other class]
+```
+
+Wait for user response before placing. Record the user's decision in `docs_placed` or
+`docs_held` accordingly.
+
+### Low confidence — unattended mode (`packet.unattended: true`)
+
+Leave the file in `smartdocs/raw/`. Record in `docs_held` with reason. Do not block.
+Do not fail the run.
+
+## After batch
+
+Run map update:
+
+```bash
+npm run polaris -- map update --changed
+```
+
+## Hard rules
+
+- Use the CLI for all file moves. Never use `mv` or `cp` directly on `smartdocs/` files.
+- If the CLI rejects a file as ignored (`POLARIS.md`, `SUMMARY.md`, `README.md`): leave in
+  raw, record as ineligible in `docs_held`.
+- If a target path collision is detected: record as a blocker for that file. Do not
+  overwrite without explicit user approval.
+- Source files already in `smartdocs/` sub-directories other than `raw/` are out of scope
+  for this step. Skip them.
+
+## Output
+
+```yaml
+docs_placed: [{ file: "<source>", target: "<path>", class: "<class>", confidence: "high" }]
+docs_held: [{ file: "<source>", reason: "<low-confidence|ineligible|collision>", detail: "..." }]
+```
+
+## Next step
+
+05-catalog-commit

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/05-catalog-commit.md

@@ -0,0 +1,94 @@
+---
+name: polaris-catalog-step-05
+description: Commit all cognition and document changes as a single sealed catalog commit.
+---
+
+# Step 05 — Catalog commit
+
+## Purpose
+
+All changes produced by steps 02–04 must be committed as a single sealed commit.
+This separates implementation commits from documentation and cognition reconciliation.
+
+## Commit constraints
+
+The catalog commit MUST:
+- Contain only files from `packet.allowed_write_paths`
+- Contain no implementation source code
+- Contain no runtime state files (`current-state.json`, telemetry JSONL, cluster-state)
+
+If any staged file would violate these constraints, unstage it and record as a blocker.
+
+## No-change case
+
+If steps 02–04 produced no file changes, this step is a no-op. Record `commit_sha: null`.
+Do not create an empty commit.
+
+## Commit message format
+
+```text
+docs(catalog): reconcile cognition and classify docs for <issue_id>
+
+Run: <run_id>
+Issue: <issue_id>
+Files updated:
+- POLARIS.md: <count> files
+- SUMMARY.md: <count> files
+- docs placed: <count>
+- docs held in raw: <count>
+```
+
+## Actions
+
+### 5.1 Pre-commit validation
+
+Verify:
+1. Every file to be committed is in `packet.allowed_write_paths`.
+2. No file is in `packet.prohibited_write_paths`.
+3. At least one non-empty change exists.
+
+If prohibited files are staged: `git reset HEAD <file>` before committing.
+
+### 5.2 Stage changed files
+
+```bash
+git add <polaris_md_updates[*].file where action == "update">
+git add <summary_md_updates[*].file where action == "update">
+git add <docs_placed[*].target>
+```
+
+### 5.3 Verify staged files
+
+Run `git diff --cached --name-only` and confirm all staged files are in
+`packet.allowed_write_paths` and none are in `packet.prohibited_write_paths`.
+
+### 5.4 Commit
+
+```bash
+git commit -m "<commit message>"
+```
+
+Capture the resulting commit SHA.
+
+### 5.5 Finalize
+
+Update `.taskchain_artifacts/polaris-catalog/current-state.json`:
+- `status: complete`
+- `current_step_id: 05-catalog-commit`
+- `commit_sha: <sha or null>`
+- `completed_at: <ISO timestamp>`
+
+Emit `catalog-commit` and `catalog-complete` telemetry events.
+
+Report summary:
+```text
+polaris-catalog complete
+Issue:           <issue_id>
+Mode:            interactive | unattended
+POLARIS.md:      <count> files updated
+SUMMARY.md:      <count> files updated
+Docs placed:     <count>
+Docs held raw:   <count> (<filenames if any>)
+Commit:          <sha> | no changes
+Blockers:        <none | list>
+```

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

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

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