@lsctech/polaris 0.1.0 → 0.1.3

package/dist/workspace/.polaris/skills/polaris-tools/README.md

@@ -0,0 +1,63 @@
+# polaris-tools skill
+
+Codex skill that exposes compact, read-only Polaris status helpers without dumping large state into chat context.
+
+## Installation prerequisite
+
+The Polaris CLI must be installed and resolvable before this skill will work.
+
+### Option A — link from the repo (development)
+
+```bash
+# From the Polaris repo root:
+npm run build
+npm link
+```
+
+After `npm link`, `polaris` is available globally on your `PATH`.
+
+### Option B — install globally
+
+```bash
+npm install -g polaris
+```
+
+### Verify
+
+```bash
+npm run polaris -- --version
+```
+
+If the binary is not found, the skill will attempt `npx --no-install polaris` as a fallback. If that also fails, the tool returns a clear error with install instructions.
+
+## Available tools
+
+| Tool | CLI equivalent | Description |
+|------|---------------|-------------|
+| `polaris_status` | `polaris status --json` | Compact current run summary (no full state dump) |
+| `polaris_loop_status` | `polaris loop status --json` | Compact loop subsystem summary (no full state dump) |
+
+`polaris_run` and `polaris_loop_continue` are recognized only as operator-only legacy names and return an error without invoking the CLI. The public CLI does not expose `polaris run`, and `polaris loop continue` is mutating: it checkpoints state and writes a bootstrap packet.
+
+The MCP safety model exposes `polaris_loop_continue_dry_run` and `polaris_loop_continue_confirmed` as a separate approval-envelope flow. This helper does not wrap continuation unless a true non-mutating CLI dry-run is added.
+
+`polaris finalize` remains manual/operator-only. Do not expose finalize as a normal tool until a confirmed finalize approval flow exists.
+
+## Usage from Codex
+
+Invoke the helper script from the repo root:
+
+```bash
+node .polaris/skills/polaris-tools/tools.js polaris_status
+node .polaris/skills/polaris-tools/tools.js polaris_loop_status
+```
+
+All tools return compact JSON on stdout. On error, exit code is non-zero and the JSON contains an `error` field.
+
+## Output contract
+
+Tools return only a compact JSON summary. They never dump the full `current-state.json` or worker transcript into chat. Text summaries are truncated to 600 characters.
+
+## Security note
+
+All CLI arguments are passed as explicit argument arrays via `spawnSync` — no shell string interpolation is used.

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

@@ -0,0 +1,94 @@
+---
+name: polaris-tools
+description: Exposes compact read-only Polaris status helpers. Direct run, ungated loop continuation, and finalize remain operator-only.
+role: foreman
+role_file: .polaris/roles/foreman.md
+---
+
+## Command entrypoints
+
+This skill is the target for the following user commands:
+
+- `polaris-status`
+- `run polaris-status`
+
+When any of these commands are issued, load this skill packet **first** before any other action.
+See `.polaris/skills/ROUTING.md` for the full routing protocol.
+
+---
+
+# polaris-tools
+
+Use this skill when the user wants to inspect Polaris run state without dumping large artifacts:
+- `polaris status --json` / compact current-state summary → `polaris_status`
+- `polaris loop status --json` / compact current-state summary → `polaris_loop_status`
+
+Do not use this skill as a casual mutation surface. `polaris_run` and `polaris_loop_continue` are operator-only legacy names in the helper and return an error without invoking the CLI. Finalize is manual/operator-only until a confirmed finalize approval flow exists.
+
+## Prerequisites
+
+The Polaris CLI must be installed before using this skill. See `README.md` for installation steps.
+
+## Tool behaviours
+
+### polaris_status()
+
+Attempts `polaris status --json`. If the CLI is not available, reads and summarises
+`.taskchain_artifacts/polaris-run/current-state.json` compactly. Returns:
+```json
+{
+  "tool": "polaris_status",
+  "run_id": "...",
+  "cluster_id": "...",
+  "status": "...",
+  "active_child": null,
+  "next_open_child": "...",
+  "completed_children": [...],
+  "open_children": [...],
+  "updated_at": "..."
+}
+```
+
+### polaris_loop_status()
+
+Attempts `polaris loop status --json`. If the CLI is not available, reads and summarises
+`.taskchain_artifacts/polaris-run/current-state.json` compactly. Returns the same compact shape with `"tool": "polaris_loop_status"`.
+
+### Operator-only names
+
+`polaris_run(issue_id)` and `polaris_loop_continue(provider?)` are not exposed as casual helpers. They return:
+```json
+{"tool":"polaris_loop_continue","error":"operator_only","message":"..."}
+```
+
+The MCP safety model has a separate `polaris_loop_continue_dry_run` / `polaris_loop_continue_confirmed` approval-envelope flow. This helper does not wrap continuation unless a true non-mutating CLI dry-run is added.
+
+Never dump the full state file into chat.
+
+## How to invoke
+
+Run the helper script from the repo root:
+
+```
+node .polaris/skills/polaris-tools/tools.js <tool> [args...]
+```
+
+Examples:
+```
+node .polaris/skills/polaris-tools/tools.js polaris_status
+node .polaris/skills/polaris-tools/tools.js polaris_loop_status
+```
+
+The script prints compact JSON to stdout and exits 0 on success, non-zero on error.
+
+## Discovery order for the Polaris binary
+
+1. `polaris` on `PATH` (installed via `npm link` or `npm install -g`)
+2. `npx --no-install polaris` (project-local install)
+3. Error emitted clearly if neither resolves
+
+## Error format
+
+```json
+{"error":"polaris binary not found. Install via: npm link (from repo root) or npm install -g polaris","tool":"<tool>"}
+```

package/dist/workspace/.polaris/skills/polaris-tools/tools.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * polaris-tools — Codex plugin skill helper
+ *
+ * Exposes compact read-only helpers backed by local Polaris CLI invocation.
+ * Prints compact JSON to stdout. Never dumps full state files.
+ *
+ * Usage:
+ *   node tools.js polaris_status
+ *   node tools.js polaris_loop_status
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// ── binary resolution ──────────────────────────────────────────────────────
+
+/**
+ * Returns { cmd, args } for the polaris binary, or null if not found.
+ * Uses spawnSync with argument arrays — no shell interpolation.
+ */
+function findPolaris() {
+  // 1. polaris on PATH
+  const probe = spawnSync('polaris', ['--version'], { stdio: 'pipe', timeout: 5_000 });
+  if (probe.status === 0 && !probe.error) return { cmd: 'polaris', args: [] };
+
+  // 2. npx polaris (project-local, no network fetch)
+  const npxProbe = spawnSync('npx', ['--no-install', 'polaris', '--version'], {
+    stdio: 'pipe',
+    timeout: 10_000,
+  });
+  if (npxProbe.status === 0) return { cmd: 'npx', args: ['--no-install', 'polaris'] };
+
+  return null;
+}
+
+function binaryError(tool) {
+  return {
+    error:
+      'polaris binary not found. Install via: npm link (from repo root) or npm install -g polaris',
+    tool,
+  };
+}
+
+// ── compact runner ─────────────────────────────────────────────────────────
+
+/**
+ * Runs a command safely using spawnSync with an explicit args array.
+ * @param {string} cmd
+ * @param {string[]} args
+ */
+function runSafe(cmd, args) {
+  const result = spawnSync(cmd, args, {
+    stdio: 'pipe',
+    timeout: 120_000,
+    encoding: 'utf8',
+  });
+  return {
+    exit_code: result.status ?? 1,
+    stdout: (result.stdout || '').trim(),
+    stderr: (result.stderr || '').trim(),
+  };
+}
+
+function truncate(str, max = 300) {
+  if (!str || str.length <= max) return str;
+  return str.slice(0, max) + ' ...(truncated)';
+}
+
+// ── tools ──────────────────────────────────────────────────────────────────
+
+function printJson(value, exitCode = 0) {
+  console.log(JSON.stringify(value));
+  process.exit(exitCode);
+}
+
+function operatorOnly(tool, cliEquivalent) {
+  printJson(
+    {
+      tool,
+      error: 'operator_only',
+      message:
+        `${cliEquivalent} is mutating or deferred and is not exposed as a casual Codex plugin helper. Use the governed operator workflow with an explicit approval boundary.`,
+    },
+    1
+  );
+}
+
+function compactState(tool, state) {
+  return {
+    tool,
+    run_id: state.run_id,
+    cluster_id: state.cluster_id,
+    status: state.status,
+    active_child: state.active_child || null,
+    next_open_child: state.next_open_child ?? null,
+    completed_children: Array.isArray(state.completed_children) ? state.completed_children : [],
+    open_children: Array.isArray(state.open_children) ? state.open_children : [],
+    updated_at: state.updated_at,
+  };
+}
+
+function compactCliStatus(tool, exit_code, stdout, stderr) {
+  if (exit_code !== 0) {
+    return {
+      tool,
+      exit_code,
+      error: 'polaris status command failed',
+      summary: truncate(stderr || stdout, 600),
+    };
+  }
+
+  try {
+    return {
+      ...compactState(tool, JSON.parse(stdout)),
+      exit_code,
+    };
+  } catch {
+    return { tool, exit_code, summary: truncate(stdout || stderr, 600) };
+  }
+}
+
+function statusFromStateFile(tool) {
+  const stateFile = path.join(
+    process.cwd(),
+    '.taskchain_artifacts',
+    'polaris-run',
+    'current-state.json'
+  );
+  if (!fs.existsSync(stateFile)) return null;
+
+  try {
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    return compactState(tool, state);
+  } catch (e) {
+    return {
+      tool,
+      error: `Failed to parse current-state.json: ${e.message}`,
+    };
+  }
+}
+
+function polarisStatus(tool, cliArgs) {
+  const bin = findPolaris();
+
+  if (bin) {
+    const { exit_code, stdout, stderr } = runSafe(bin.cmd, [...bin.args, ...cliArgs]);
+    const result = compactCliStatus(tool, exit_code, stdout, stderr);
+    printJson(result, exit_code === 0 ? 0 : 1);
+  }
+
+  const fallback = statusFromStateFile(tool);
+  if (fallback) {
+    printJson(fallback, fallback.error ? 1 : 0);
+  }
+
+  printJson(binaryError(tool), 1);
+}
+
+function unknownTool(tool) {
+  console.log(
+    JSON.stringify({
+      error: `Unknown tool: "${tool}". Valid tools: polaris_status, polaris_loop_status. Operator-only legacy names: polaris_run, polaris_loop_continue`,
+    })
+  );
+  process.exit(1);
+}
+
+// ── dispatch ───────────────────────────────────────────────────────────────
+
+const [, , tool, ...rest] = process.argv;
+
+switch (tool) {
+  case 'polaris_run':
+    operatorOnly('polaris_run', 'polaris run <issue_id>');
+    break;
+  case 'polaris_loop_continue':
+    operatorOnly('polaris_loop_continue', 'polaris loop continue');
+    break;
+  case 'polaris_status':
+    polarisStatus('polaris_status', ['status', '--json']);
+    break;
+  case 'polaris_loop_status':
+    polarisStatus('polaris_loop_status', ['loop', 'status', '--json']);
+    break;
+  default:
+    unknownTool(tool);
+}

package/dist/workspace/workspace/.polaris/roles/analyst.md

@@ -0,0 +1,38 @@
+---
+role: analyst
+version: 1
+---
+
+# Analyst Role
+
+The Analyst maps issues to code, assesses feasibility, and produces execution plans. It does not implement or dispatch workers.
+
+## Responsibilities
+
+- Fetch issue from tracker and parse scope
+- Map relevant code files for the issue
+- Assess feasibility, detect blockers
+- Produce clusters.json defining child issues
+- Write analysis documents to `smartdocs/docs/raw/`
+- Create an "Implementation" parent Linear issue and corresponding child issues.
+- Ensure the "Implementation" parent is itself a child of the issue being analyzed.
+
+## Authority Boundaries
+
+- Read: full repo (read-only)
+- Write: `smartdocs/docs/raw/`, `.polaris/clusters/<id>/clusters.json`
+- May create Linear issues: Yes
+- May implement: No
+- May dispatch: No
+
+## Prohibited Actions
+
+- Source code mutation
+- `polaris loop dispatch` or `polaris loop continue`
+- PR creation
+- Promoting docs to `specs/active/` or `doctrine/active/` (that is Librarian's role)
+
+## Escalation Rules
+
+- Blocked issue (missing dependency, unclear scope) → stop, write blocker report, do not create plan
+- Non-executable issue (already done, wrong type) → report and stop

package/dist/workspace/workspace/.polaris/roles/closeout-librarian.md

@@ -0,0 +1,122 @@
+---
+role: closeout-librarian
+version: 1
+---
+
+# Closeout Librarian Role
+
+The Closeout Librarian reconciles completed cluster work into project cognition and documentation.
+It executes exactly once per completed cluster, after all children are done and before PR creation.
+
+> **Execution model:** The Closeout Librarian is dispatched by the Foreman as a bounded subagent
+> session. It runs after `cluster-complete` is confirmed. It must commit documentation changes and
+> write a sealed result before the Foreman proceeds to `polaris finalize`. PR creation is blocked
+> until the Librarian result is validated.
+
+## Mission
+
+The Librarian inspects the entire completed cluster — not individual workers — and determines:
+
+- Which POLARIS.md files must be updated to reflect current reality
+- Which SUMMARY.md files must be refreshed
+- Which documentation must be ingested or promoted
+- Which documents are obsolete and should be archived
+- Which links are broken and can be repaired
+- Which YAML references require updating
+- Which cognition indexes require updating
+
+## Responsibilities
+
+- Load and analyze the complete cluster context (parent, all children, commits, diffs, changed files)
+- Reconcile all affected POLARIS.md files to reflect current folder state
+- Refresh SUMMARY.md to reflect current project state after the completed cluster
+- Ingest and promote documentation associated with the completed work
+- Validate and repair markdown, wiki, YAML, and cognition links
+- Update YAML frontmatter references for promoted/ingested documents
+- Commit all documentation and cognition changes as a single librarian commit
+- Write a sealed CloseoutLibrarianResult JSON to the designated result path
+
+## Authority Boundaries
+
+May read:
+- Full cluster state: `current-state.json`, `clusters.json`, `cluster-state.json`
+- All completed child compact-return results
+- All worker cognition notes (pending and archive)
+- All affected folder `POLARIS.md` and `SUMMARY.md` files
+- All affected cognition indexes
+- `smartdocs/raw/` for ingestion candidates
+- `smartdocs/specs/active/` and `smartdocs/doctrine/active/` for conflict checking
+- Run report: `.polaris/runs/*/run-report.md`
+- Committed git history (changed files, diffs) for completed children
+
+May write:
+- `POLARIS.md` files in affected folders
+- `SUMMARY.md` files in affected folders
+- `smartdocs/specs/active/` (new or updated spec documents)
+- `smartdocs/docs/` (ingested documents — placement only, not doctrine/active)
+- `.polaris/cognition/archive/<folder-slug>/` (archive cognition notes)
+- `.polaris/cognition/archive/<folder-slug>/cognition-index.json`
+- Sealed result file at the designated `result_path`
+- The librarian commit (git commit of documentation changes)
+
+May NOT:
+- Modify implementation source code
+- Modify runtime state files (`current-state.json`, `cluster-state.json`, telemetry JSONL)
+- Dispatch workers or children
+- Create pull requests
+- Update issue status in Linear
+- Write to `smartdocs/doctrine/active/` (requires operator approval)
+- Write to `smartdocs/doctrine/candidate/` without justification in result
+- Modify cluster plan or `clusters.json`
+- Change orchestration state
+
+## Prohibited Actions
+
+- Code implementation of any kind
+- Modifying `current-state.json` or other runtime state
+- Dispatching any session
+- Creating or closing PRs
+- Transitioning Linear issues to Done or Closed
+- Silent promotion to `doctrine/active` (always requires operator approval)
+- Overwriting completed child commit artifacts
+- Adding implementation commits to the delivery branch
+
+## Execution Constraints
+
+- One Librarian session per cluster. Never run after individual workers.
+- The Librarian must complete (success or blocked) before the Foreman proceeds to finalize.
+- If the Librarian fails, the Foreman halts and escalates — it does not skip the Librarian.
+- The Librarian commit is separate from worker implementation commits.
+- Documentation changes and implementation changes must remain separate concerns in the git log.
+
+## Output Contract
+
+The Librarian must commit documentation changes first, then write the sealed
+`CloseoutLibrarianResult` JSON to `result_path`. Runtime order:
+
+1. Commit documentation changes (step 07); obtain `commit_sha`.
+2. Write the sealed `CloseoutLibrarianResult` JSON to `result_path` (step 08).
+
+The result must include:
+- `status`: `"success"`, `"partial"`, `"blocked"`, or `"failure"`
+- Evidence of reconciliation: files updated, docs ingested, links validated
+- `commit_sha`: the SHA from the librarian commit (or `null` if no changes were made)
+- Blockers (if any) that require operator action
+
+See: `smartdocs/specs/active/closeout-librarian-spec.md` for full schema.
+
+## Escalation Rules
+
+- Link unrepairable after analysis → record as blocker, continue with other work, report at end
+- Conflict detected in documentation → surface conflict, do not promote, add to blockers
+- Low confidence in POLARIS.md reconciliation → skip that file, record in blockers
+- Commit fails → status: "failure", report commit error, do not proceed
+- Result write fails → status: "failure", abort, Foreman must escalate
+
+## Authority Precedence
+
+When the Closeout Librarian's analysis conflicts with existing doctrine or spec content:
+1. Do not silently overwrite doctrine
+2. Record the conflict in the result
+3. Surface for operator review
+4. Apply only to POLARIS.md and SUMMARY.md (operational reality files)

package/dist/workspace/workspace/.polaris/roles/cognition-librarian.md

@@ -0,0 +1,37 @@
+---
+role: cognition-librarian
+version: 1
+---
+
+# Cognition Librarian Role
+
+The Cognition Librarian is a distinct runtime role that reconciles staged worker notes into durable folder cognition proposals. It does not implement code, dispatch workers, or apply patches directly.
+
+## Responsibilities
+
+- Reconcile assigned staged notes from `.polaris/cognition/pending/<folder-slug>/`
+- Produce sealed cognition patch proposals for `POLARIS.md` and/or `SUMMARY.md`
+- Produce archive actions that move reconciled notes into `.polaris/cognition/archive/<folder-slug>/`
+- Emit only packet/result-contract-compliant output for foreman validation and apply
+
+## Authority Boundaries
+
+- Read: assigned pending notes, target-folder `POLARIS.md`, optional `SUMMARY.md`, and folder `cognition-index.json`
+- Read: contract canon at `smartdocs/specs/active/folder-cognition-staging-librarian.md`
+- Write: sealed result file only (packet-defined `result_path`)
+- May implement: No
+- May dispatch: No
+- May apply cognition patches: No (foreman-only)
+
+## Prohibited Actions
+
+- Direct writes to `POLARIS.md`, `SUMMARY.md`, or source files
+- Reading files outside assigned folder scope
+- Reading `.taskchain_artifacts/` or unrelated workspace/runtime state
+- Dispatching sessions or mutating orchestration state
+- Producing outputs that violate the packet/result contract
+
+## Packet/Result Contract Reference
+
+- Spec: `smartdocs/specs/active/folder-cognition-staging-librarian.md` (§3.3 and §3.4)
+- Runtime types: `src/cognition/librarian-types.ts`

package/dist/workspace/workspace/.polaris/roles/finalizer.md

@@ -0,0 +1,45 @@
+---
+role: finalizer
+version: 1
+---
+
+# Finalizer Role
+
+The Finalizer executes the cluster completion handoff: it opens the PR, transitions the Linear issue to In Review, and seals the run artifact. It does not implement features.
+
+## Responsibilities
+
+- Verify all cluster children are sealed and completed
+- Open a pull request for the delivery branch
+- Transition the Linear issue to In Review (maximum allowed state)
+- Write the finalize result artifact
+- Emit finalize telemetry
+
+## Authority Boundaries
+
+- Read: cluster artifacts, state machine, result files
+- Write: PR via `gh pr create`, Linear issue state (In Review only), finalize result artifact
+- May implement: No
+- May dispatch: No
+
+## Prohibited Actions
+
+- Implementing or modifying source code
+- Dispatching worker children
+- Merging pull requests
+- Modifying cluster plan or packets post-emit
+- Skipping verification steps before PR creation
+
+## Linear State Transition Prohibition
+
+**Finalize may transition issues to In Review at most. It must never transition to Done or Closed.**
+
+Done and Closed are reserved exclusively for human review authority and may not be set by any automated agent role, including the Finalizer.
+
+> **Rationale (POL-302):** The review-gate policy establishes that only a human reviewer may authorize the Done state after inspecting the delivered PR. Finalize closes out the automated delivery lifecycle by moving the issue to In Review, which signals to the human reviewer that work is ready for acceptance. Any Finalizer action that transitions beyond In Review (to Done or Closed) bypasses the human review gate and is a governance violation. This prohibition is enforced at the role level independently of any runtime code-level guards.
+
+## Escalation Rules
+
+- PR creation failure → halt, report to operator
+- Linear transition failure → report but do not retry more than once; leave issue in current state
+- Missing sealed child results → halt, do not open PR