@lsctech/polaris 0.3.2 → 0.3.4

package/dist/governance/review-packet.js

@@ -52,14 +52,15 @@ function groupAndSort(packets) {
  * Write _review-queue.json (canonical) and _review-queue.md (display-only) to outputDir.
  * Markdown is regenerated from JSON — never parse markdown to recover decisions.
  */
-function writeReviewQueue(packets, runId, outputDir) {
+function writeReviewQueue(packets, runId, outputDir, filename = "_review-queue.json") {
     (0, node_fs_1.mkdirSync)(outputDir, { recursive: true });
     const queueFile = {
         generated_at: new Date().toISOString(),
         run_id: runId,
         packets,
     };
-    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_review-queue.json"), JSON.stringify(queueFile, null, 2) + "\n", "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, filename), JSON.stringify(queueFile, null, 2) + "\n", "utf-8");
+    const mdFilename = filename.replace(/\.json$/, ".md");
     const sorted = groupAndSort(packets);
     const sections = sorted.map(renderPacketMarkdown).join("\n\n---\n\n");
     const md = [
@@ -69,21 +70,21 @@ function writeReviewQueue(packets, runId, outputDir) {
         `**Generated:** ${queueFile.generated_at}`,
         `**Pending review:** ${packets.length} document(s)`,
         ``,
-        `> Markdown is display-only. Edit \`_review-queue.json\` to set \`reviewDecision\` fields.`,
+        `> Markdown is display-only. Edit \`${filename}\` to set \`reviewDecision\` fields.`,
         `> Rerun \`polaris docs ingest\` to apply decisions.`,
         ``,
         `---`,
         ``,
         sections,
     ].join("\n");
-    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, "_review-queue.md"), md, "utf-8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outputDir, mdFilename), md, "utf-8");
 }
 /**
  * Read review queue from JSON. Returns empty array if no queue file exists.
  * Never reads markdown.
  */
-function readReviewQueue(outputDir) {
-    const jsonPath = (0, node_path_1.join)(outputDir, "_review-queue.json");
+function readReviewQueue(outputDir, filename = "_review-queue.json") {
+    const jsonPath = (0, node_path_1.join)(outputDir, filename);
     if (!(0, node_fs_1.existsSync)(jsonPath))
         return [];
     try {

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/smartdocs-engine/agentic-review.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agenticDecideKey = agenticDecideKey;
+const node_fs_1 = require("node:fs");
+async function agenticDecideKey(packet) {
+    let docContent = "";
+    try {
+        if ((0, node_fs_1.existsSync)(packet.sourcePath)) {
+            docContent = (0, node_fs_1.readFileSync)(packet.sourcePath, "utf-8").slice(0, 3000);
+        }
+    }
+    catch { /* ignore */ }
+    // @ts-ignore: @anthropic-ai/sdk may not be installed as a dependency
+    const mod = await import("@anthropic-ai/sdk");
+    const Anthropic = mod.default ?? mod.Anthropic;
+    const client = new Anthropic();
+    const staleSymbols = packet.staleSymbols;
+    const triageFlag = packet.triageFlag;
+    const prompt = `You are reviewing a candidate documentation file flagged during Polaris docs triage.
+
+Flag type: ${String(triageFlag ?? "unknown")}
+Authority risk: ${packet.authorityRisk}
+Recommendation from triage: ${packet.recommendation}
+Reasoning: ${packet.reasoning.join("; ")}
+${Array.isArray(staleSymbols) ? `Stale symbols (not found in codebase graph): ${staleSymbols.join(", ")}` : ""}
+
+Document content:
+---
+${docContent}
+---
+
+Decide whether this document should be:
+- approved: doc is valid doctrine and should be promoted to active
+- rejected: doc is outdated, incorrect, or superseded and should be deprecated
+- deferred: uncertain — needs human review
+
+Respond with exactly one word: approve, reject, or defer.`;
+    const response = await client.messages.create({
+        model: "claude-haiku-4-5-20251001",
+        max_tokens: 10,
+        messages: [{ role: "user", content: prompt }],
+    });
+    const text = (response.content[0].text ?? "defer").trim().toLowerCase();
+    if (text.startsWith("approve"))
+        return "a";
+    if (text.startsWith("reject"))
+        return "r";
+    return "d";
+}

package/dist/smartdocs-engine/index.js

@@ -142,12 +142,24 @@ function createDocsCommand(options = {}) {
         .description("Interactively review pending governance decisions in the review queue")
         .option("--queue <path>", "path to _review-queue.json (default: smartdocs/raw/_review-queue.json)")
         .option("-r, --repo-root <path>", "Repository root", defaultRepoRoot)
+        .option("--agentic", "use LLM agent to make review decisions automatically")
+        .option("--triage", "review the triage queue (_triage-queue.json) instead of the review queue")
         .action(async (opts) => {
+        const repoRoot = opts.repoRoot;
+        const queueFilename = opts.triage ? "_triage-queue.json" : "_review-queue.json";
+        const queueDir = opts.queue
+            ? (0, node_path_1.resolve)(opts.repoRoot, opts.queue)
+                .replace(/_review-queue\.json$/, "")
+                .replace(/_triage-queue\.json$/, "")
+                .replace(/\/$/, "")
+            : (0, node_path_1.resolve)(repoRoot, "smartdocs", "raw");
+        let readKey;
+        if (opts.agentic) {
+            const { agenticDecideKey } = await import("./agentic-review.js");
+            readKey = agenticDecideKey;
+        }
         try {
-            const queueDir = opts.queue
-                ? (0, node_path_1.resolve)(opts.repoRoot, opts.queue).replace(/_review-queue\.json$/, "").replace(/\/$/, "")
-                : (0, node_path_1.resolve)(opts.repoRoot, "smartdocs", "raw");
-            await (0, review_js_1.runReviewSession)({ repoRoot: opts.repoRoot, queueDir });
+            await (0, review_js_1.runReviewSession)({ repoRoot, queueDir, queueFilename, readKey });
         }
         catch (err) {
             console.error(`polaris docs review: ${err instanceof Error ? err.message : String(err)}`);

package/dist/smartdocs-engine/review.js

@@ -84,7 +84,8 @@ function readSingleKey() {
 async function runReviewSession(options) {
     const { repoRoot, readKey, getReviewedBy = defaultGetReviewedBy, output = (msg) => process.stdout.write(msg + "\n"), } = options;
     const queueDir = options.queueDir ?? (0, node_path_1.resolve)(repoRoot, "smartdocs", "raw");
-    const packets = (0, index_js_1.readReviewQueue)(queueDir);
+    const queueFilename = options.queueFilename;
+    const packets = (0, index_js_1.readReviewQueue)(queueDir, queueFilename);
     if (packets.length === 0) {
         output("No review queue found. Run polaris docs ingest first.");
         return;
@@ -98,7 +99,7 @@ async function runReviewSession(options) {
     for (let i = 0; i < undecided.length; i++) {
         const packet = undecided[i];
         output(formatPacketCard(packet, i + 1, undecided.length));
-        const key = readKey ? await readKey() : await readSingleKey();
+        const key = readKey ? await readKey(packet) : await readSingleKey();
         if (key === "q") {
             const remaining = undecided.length - decided;
             output(`\nSession ended. ${decided} decision(s) saved, ${remaining} packet(s) still pending.`);
@@ -126,7 +127,7 @@ async function runReviewSession(options) {
                 reviewedBy: getReviewedBy(),
             };
         }
-        (0, index_js_1.writeReviewQueue)(packets, "review-session", queueDir);
+        (0, index_js_1.writeReviewQueue)(packets, "review-session", queueDir, queueFilename);
         decided++;
     }
     const approved = packets.filter((p) => p.reviewDecision === "approve").length;

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.2",
+  "version": "0.3.4",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris-cli": "dist/cli/index.js"