@lsctech/polaris 0.3.0 → 0.3.1

package/dist/skill-packet/generator.js

@@ -8,6 +8,7 @@ exports.SKILL_ROLE_MAP = {
     run: "Foreman",
     ingest: "Librarian",
     promote: "Librarian",
+    triage: "Librarian",
 };
 const ROLE_SUMMARIES = {
     Analyst: "The Analyst gathers evidence, assesses feasibility, and produces implementation-ready plans. The Analyst shapes work but never executes it.",
@@ -187,6 +188,39 @@ function buildPromotePacket() {
         ],
     };
 }
+function buildTriagePacket() {
+    return {
+        authority_boundaries: [
+            "Read smartdocs/doctrine/active/ to load canonicals for comparison",
+            "Read smartdocs/doctrine/candidate/ to load candidates for triage",
+            "Call polaris docs triage [--dry-run] [--batch-size N] [--resume] to run the triage pipeline",
+            "Read smartdocs/raw/_triage-queue.json and _triage-report.md produced by triage",
+            "Emit telemetry events",
+        ],
+        prohibited_actions: [
+            "Move, promote, or delete any document — triage flags only, never decides",
+            "Mutate source files (src/, tests, config)",
+            "Call polaris loop continue or polaris finalize",
+            "Suppress or ignore detected flags",
+            "Auto-approve or auto-reject any triage flag without user review",
+        ],
+        allowed_outputs: [
+            "smartdocs/raw/_triage-queue.json — machine-readable flag list for polaris docs review",
+            "smartdocs/raw/_triage-report.md — human-readable summary",
+            "Telemetry events",
+        ],
+        deliverables: [
+            "_triage-queue.json written with all flags from Phase 1 (doc-vs-doc) and Phase 2 (doc-vs-code)",
+            "_triage-report.md written summarising flag counts by type",
+            "Checkpoint deleted on successful completion",
+        ],
+        stop_conditions: [
+            "Triage pipeline completes and outputs written",
+            "API key not available — report and wait for instruction",
+            "Graph coverage below threshold — Phase 2 skipped with warning",
+        ],
+    };
+}
 function generateSkillPacket(skillName, config) {
     const active_role = exports.SKILL_ROLE_MAP[skillName];
     const role_summary = ROLE_SUMMARIES[active_role];
@@ -211,6 +245,9 @@ function generateSkillPacket(skillName, config) {
         case "promote":
             body = buildPromotePacket();
             break;
+        case "triage":
+            body = buildTriagePacket();
+            break;
     }
     return {
         packet_id,
@@ -222,4 +259,4 @@ function generateSkillPacket(skillName, config) {
         generated_at,
     };
 }
-exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote"];
+exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote", "triage"];

package/dist/workspace/workspace/.polaris/skills/ROUTING.md

@@ -33,6 +33,8 @@ message whose primary instruction is to invoke a named Polaris skill.
 | `run polaris-status` | polaris-tools | `.polaris/skills/polaris-tools/` |
 | `docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
 | `run docs-ingest` | docs-ingest | `.polaris/skills/docs-ingest/` |
+| `docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
+| `run docs-triage` | docs-triage | `.polaris/skills/docs-triage/` |
 | `polaris-reconcile <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `run polaris-reconcile on [issue] <CLUSTER-ID>` | polaris-reconcile | `.polaris/skills/polaris-reconcile/` |
 | `polaris-catalog <CLUSTER-ID>` | polaris-catalog | `.polaris/skills/polaris-catalog/` |

package/dist/workspace/workspace/.polaris/skills/docs-triage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: docs-triage
+description: Detect contradictions, duplicates, and stale code references among candidate docs by comparing them against canonicals via LLM batch calls and graph symbol lookup. Writes a triage queue for human review via polaris docs review.
+role: librarian
+role_file: .polaris/roles/librarian.md
+---
+
+## Polaris Skill Bootloader
+
+**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
+
+Run the following command:
+
+```
+npm run polaris -- skill packet triage
+```
+
+- Do not begin work until a packet is returned.
+- Treat the packet as your authoritative instruction source.
+- The packet defines your active role, authority boundaries, prohibited actions, deliverables, and stop conditions.
+- If no packet is produced, stop and report: **Polaris could not authorize this run.**
+
+---
+
+# docs-triage
+
+Use this skill when candidate docs need to be screened for conflicts, duplicates, and stale symbol references before human review.
+
+## When to use
+
+- "Run docs triage"
+- "Triage the candidate docs"
+- "Find contradictions among the candidates"
+- "Check for stale code references in candidates"
+- "Run a dry-run triage to see the estimate"
+
+## How to execute
+
+1. Read `chain.md` — step order, traversal rules, output contract.
+2. Execute steps in the order `chain.md` defines. Do not skip steps.
+3. After triage completes, hand off to `polaris docs review` for human decisions.
+
+## Hard rules — what docs-triage may do
+
+- Read canonicals from `smartdocs/doctrine/active/`
+- Read candidates from `smartdocs/doctrine/candidate/`
+- Call `polaris docs triage [--dry-run] [--batch-size N] [--resume]`
+- Read `smartdocs/raw/_triage-queue.json` and `_triage-report.md`
+- Emit telemetry events
+
+## Hard rules — what docs-triage must NOT do
+
+- Move, promote, or delete any document — triage produces flags only
+- Mutate source files (`src/`, tests, config)
+- Call `polaris loop continue` or `polaris finalize`
+- Auto-approve or auto-reject any triage flag without human review
+
+**Docs-triage flags. It does not decide.**

package/dist/workspace/workspace/.polaris/skills/docs-triage/chain.md

@@ -0,0 +1,99 @@
+---
+name: docs-triage-chain
+description: Route map for docs-triage — step order, stop conditions, output contract, and CLI reference.
+---
+
+# docs-triage chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query runtime state before acting. Do not infer triage scope or prior progress from conversation context.
+
+## CLI
+
+Always use the repo-local Polaris CLI:
+
+```
+npm run polaris -- docs triage [--dry-run] [--batch-size <n>] [--resume] [--repo-root <path>]
+```
+
+- `--dry-run`: prints cluster count, estimated batches, estimated tokens, and model — no LLM calls
+- `--batch-size <n>`: docs per LLM call (default: 10)
+- `--resume`: resume from last checkpoint (auto-detected if checkpoint exists)
+
+Never assume a globally linked `polaris` command exists.
+
+## Output contract
+
+All outputs written to `smartdocs/raw/`:
+
+| File | Purpose |
+|------|---------|
+| `_triage-queue.json` | Machine-readable flag list — fed directly into `polaris docs review` |
+| `_triage-report.md` | Human-readable summary — display only, never parsed |
+| `_triage-checkpoint.json` | Resume state — deleted automatically on completion |
+
+## Step traversal order
+
+```text
+01-orient-triage     ← dry-run first to confirm cluster count and cost estimate; emit telemetry
+02-run-triage        ← polaris docs triage (with --resume if checkpoint exists)
+03-verify-outputs    ← confirm _triage-queue.json and _triage-report.md written; read summary
+04-hand-off          ← report flag counts by type; instruct user to run polaris docs review
+```
+
+## Stop conditions
+
+**Any step:**
+- `ANTHROPIC_API_KEY` not available → halt, report: "Set ANTHROPIC_API_KEY and re-run"
+- `smartdocs/doctrine/active/` or `smartdocs/doctrine/candidate/` not found → halt, report
+- `_triage-queue.json` not written after pipeline completes → halt, report
+
+**Step 01 (dry-run):**
+- Estimated batches > 500 → pause and surface cost estimate to user before proceeding
+
+**Step 02 (run-triage):**
+- Checkpoint detected → pass `--resume` automatically
+- Graph symbol count < 1000 → Phase 2 skipped (this is expected — log and continue)
+
+## Run ID format
+
+Format: `docs-triage-<date>-<seq>`
+- `<date>`: `YYYY-MM-DD`
+- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
+
+Example: `docs-triage-2026-06-14-001`
+
+## Telemetry
+
+Telemetry file: `.taskchain_artifacts/docs-triage/runs/<run-id>/telemetry.jsonl` (append-only).
+
+| Event | Trigger |
+|-------|---------|
+| `run-start` | Begin step 01 |
+| `step-complete` | End of every step |
+| `triage-dry-run-complete` | Dry-run summary printed |
+| `triage-complete` | Pipeline finished, outputs written |
+
+Required fields on every event: `event`, `run_id`, `timestamp`.
+
+## Execution reporting
+
+After each completed step, emit a checkpoint:
+
+```text
+**[step-name]** done | blocked | needs-input
+Changed: <outputs written> or none
+Validated: <checks passed> or none
+Blockers: none | <explicit blocker>
+```
+
+### Never compressed
+
+Always write in full:
+- Flag count summary (contradictions / duplicates / stale-references)
+- Any batches skipped due to API errors
+- Phase 2 skip warning if graph coverage is low
+- Hand-off instructions for `polaris docs review`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris-cli": "dist/cli/index.js"
@@ -71,5 +71,8 @@
     "@types/node": "^25.9.1",
     "typescript": "^5.4.2",
     "vitest": "^3.0.5"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.104.1"
   }
 }