@lsctech/polaris 0.3.3 → 0.3.5

package/dist/skill-packet/generator.js

@@ -9,6 +9,7 @@ exports.SKILL_ROLE_MAP = {
     ingest: "Librarian",
     promote: "Librarian",
     triage: "Librarian",
+    review: "Librarian",
 };
 const ROLE_SUMMARIES = {
     Analyst: "The Analyst gathers evidence, assesses feasibility, and produces implementation-ready plans. The Analyst shapes work but never executes it.",
@@ -221,6 +222,41 @@ function buildTriagePacket() {
         ],
     };
 }
+function buildReviewPacket() {
+    return {
+        authority_boundaries: [
+            "Read smartdocs/raw/_triage-queue.json to load pending review decisions",
+            "Read candidate documents from smartdocs/doctrine/candidate/ to inform decisions",
+            "Evaluate each flagged packet: read the doc, consider the flag type and stale symbols, decide approve/reject/defer",
+            "Write decisions back to the triage queue by calling polaris docs review --write-decision <sourcePath> <decision>",
+            "Call polaris docs ingest to apply approved/rejected decisions after review is complete",
+            "Emit telemetry events",
+        ],
+        prohibited_actions: [
+            "Move, promote, or delete documents directly — decisions must go through polaris docs ingest",
+            "Auto-approve every packet without reading the document content",
+            "Mutate source files (src/, tests, config)",
+            "Call polaris loop continue or polaris finalize",
+            "Suppress or skip flagged packets without recording a decision",
+        ],
+        allowed_outputs: [
+            "Review decisions written to smartdocs/raw/_triage-queue.json",
+            "Promoted documents (via polaris docs ingest for approved packets)",
+            "Deprecated documents (via polaris docs ingest for rejected packets)",
+            "Telemetry events",
+        ],
+        deliverables: [
+            "All pending packets in _triage-queue.json reviewed with approve/reject/defer decision",
+            "Approved and rejected packets processed by polaris docs ingest",
+            "Summary of decisions reported to user",
+        ],
+        stop_conditions: [
+            "All packets reviewed",
+            "Ambiguous packet that requires explicit user input",
+            "Ingest error on apply — report and wait for instruction",
+        ],
+    };
+}
 function generateSkillPacket(skillName, config) {
     const active_role = exports.SKILL_ROLE_MAP[skillName];
     const role_summary = ROLE_SUMMARIES[active_role];
@@ -248,6 +284,9 @@ function generateSkillPacket(skillName, config) {
         case "triage":
             body = buildTriagePacket();
             break;
+        case "review":
+            body = buildReviewPacket();
+            break;
     }
     return {
         packet_id,
@@ -259,4 +298,4 @@ function generateSkillPacket(skillName, config) {
         generated_at,
     };
 }
-exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote", "triage"];
+exports.SUPPORTED_SKILLS = ["analyze", "run", "ingest", "promote", "triage", "review"];

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

@@ -35,6 +35,8 @@ message whose primary instruction is to invoke a named Polaris skill.
 | `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/` |
+| `docs-review` | docs-review | `.polaris/skills/docs-review/` |
+| `run docs-review` | docs-review | `.polaris/skills/docs-review/` |
 | `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-review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: docs-review
+description: Agentically review the triage queue — read each flagged candidate doc, evaluate the flag, and record approve/reject/defer decisions. Applies approved and rejected decisions via polaris docs ingest.
+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 review
+```
+
+- 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-review
+
+Use this skill to agentically walk through the triage queue and make approve/reject/defer decisions on each flagged candidate document. You are the reviewer — read each doc, evaluate the flag, and decide.
+
+## When to use
+
+- "Run docs review"
+- "Review the triage queue"
+- "Process the flagged candidates"
+- "docs-review"
+
+## 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. You make all decisions by reading the flagged doc content and the flag metadata.
+
+## Hard rules — what docs-review may do
+
+- Read `smartdocs/raw/_triage-queue.json` to load pending items
+- Read candidate documents from `smartdocs/doctrine/candidate/`
+- Record decisions (approve/reject/defer) back to `_triage-queue.json`
+- Call `polaris docs ingest` to apply approved/rejected decisions
+- Emit telemetry events
+
+## Hard rules — what docs-review must NOT do
+
+- Move, rename, or delete documents directly — ingest handles that
+- Auto-approve every packet without reading the document
+- Mutate source files (`src/`, tests, config)
+- Call `polaris loop continue` or `polaris finalize`
+- Skip packets without recording a decision
+
+**Docs-review reads, evaluates, and decides. Ingest executes.**

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

@@ -0,0 +1,95 @@
+---
+name: docs-review-chain
+description: Route map for docs-review — step order, stop conditions, output contract, and decision protocol.
+---
+
+# docs-review chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query `smartdocs/raw/_triage-queue.json` before acting. Do not infer queue state from conversation context.
+
+## Decision protocol
+
+For each flagged packet you evaluate:
+
+1. Read the source document at `sourcePath`
+2. Consider the flag metadata: `triageFlag`, `staleSymbols`, `authorityRisk`, `reasoning`
+3. Apply this decision rubric:
+   - **approve**: doc content is still valid doctrine; stale symbols are incidental (generic English words, external brand names, or aspirational references that don't affect correctness)
+   - **reject**: doc is clearly outdated, contradicted by current code, or describes systems that no longer exist
+   - **defer**: cannot determine from doc content alone — needs human review
+
+4. Record your decision by editing `_triage-queue.json` directly: set `reviewDecision` to `"approve"`, `"reject"`, or `"defer"`, and set `reviewedAt` to the current ISO timestamp and `reviewedBy` to `"docs-review-agent"`.
+
+## Output contract
+
+All decision output written to `smartdocs/raw/`:
+
+| File | Purpose |
+|------|---------|
+| `_triage-queue.json` | Updated with `reviewDecision` fields — source of truth for ingest |
+
+## Step traversal order
+
+```text
+01-load-queue        ← read _triage-queue.json; count pending items; emit run-start telemetry
+02-review-packets    ← for each pending packet: read doc → evaluate → record decision
+03-apply-decisions   ← run polaris docs ingest to apply approved/rejected packets
+04-hand-off          ← report decision summary (approved / rejected / deferred); emit triage-review-complete telemetry
+```
+
+## Stop conditions
+
+**Step 01:**
+- `_triage-queue.json` not found → halt: "Run docs-triage first to generate the triage queue"
+- Zero pending items → report "Nothing to review — all decisions already recorded" and stop
+
+**Step 02:**
+- If a document at `sourcePath` cannot be read → record `defer` and log the path
+- Process all packets before moving to step 03 — do not apply decisions mid-loop
+
+**Step 03:**
+- If no packets were approved or rejected → skip ingest, report counts only
+- Ingest error → report the error; do not retry automatically
+
+## Run ID format
+
+Format: `docs-review-<date>-<seq>`
+- `<date>`: `YYYY-MM-DD`
+- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
+
+Example: `docs-review-2026-06-14-001`
+
+## Telemetry
+
+Telemetry file: `.taskchain_artifacts/docs-review/runs/<run-id>/telemetry.jsonl` (append-only).
+
+| Event | Trigger |
+|-------|---------|
+| `run-start` | Begin step 01 |
+| `step-complete` | End of every step |
+| `review-complete` | All packets evaluated |
+| `apply-complete` | Ingest finished |
+
+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:
+- Decision counts (approved / rejected / deferred) after step 02
+- Any packets that could not be read (defaulted to defer)
+- Ingest results after step 03

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris-cli": "dist/cli/index.js"