@lsctech/polaris 0.1.1 → 0.1.3

package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/06-execute-promote-deprecate.md

@@ -0,0 +1,65 @@
+---
+name: docs-promote-step-06-execute-promote-deprecate
+description: Execute the approved promote and deprecate CLI commands one at a time. Halt on any failure.
+---
+
+# Step 06 — Execute promote / deprecate
+
+## Purpose
+
+Fire the CLI commands for every candidate the user approved. One command at a time. Record the result after each before continuing.
+
+## Actions
+
+For each candidate with `decision: approved`:
+
+### Spec promotion
+```bash
+npm run polaris -- doctrine spec-promote <path> --approve
+```
+
+### Doctrine candidate promotion
+```bash
+npm run polaris -- doctrine promote <path>
+```
+
+### Active doctrine deprecation
+```bash
+npm run polaris -- doctrine deprecate <path>
+```
+
+After each command:
+- Record `promoted_to` or `deprecated_to` path in state
+- Emit `docs-promoted` telemetry with `file` and result path
+
+If a command exits non-zero:
+- **Halt immediately.** Do not attempt any remaining commands.
+- Record the error in state under `execution_error`.
+- Report the failure in full. Wait for user instruction.
+
+Candidates with `decision: rejected` or `deferred`: skip. Record in state as `skipped`.
+
+## Scope
+
+```yaml
+allowed_files:
+  - smartdocs/raw/ (write — files will be moved by CLI)
+  - smartdocs/doctrine/candidate/ (write — files will be moved by CLI)
+  - smartdocs/doctrine/active/ (write — files will be moved by CLI)
+  - smartdocs/specs/active/ (write — files will be moved by CLI)
+  - .taskchain_artifacts/docs-promote/current-state.json
+stop_rules:
+  - any CLI command exits non-zero → halt immediately
+```
+
+## Artifact update
+
+Update `current-state.json` after each command:
+- `current_step_id: 06-execute-promote-deprecate`
+- Per candidate: `promoted_to|deprecated_to|skipped`, `execution_error` if applicable
+
+Emit `step-complete` for `06-execute-promote-deprecate` only after all approved candidates are processed (or halted).
+
+## Next step
+
+07-finalize-promote

package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/07-finalize-promote.md

@@ -0,0 +1,44 @@
+---
+name: docs-promote-step-07-finalize-promote
+description: Emit completion telemetry, mark the run complete, and print the promotion summary.
+---
+
+# Step 07 — Finalize promote
+
+## Purpose
+
+Close out the session cleanly. Emit telemetry. Write final state. Report.
+
+## Actions
+
+1. **Emit `docs-promote-complete` telemetry**.
+
+2. **Update `current-state.json`**:
+   - `status: complete`
+   - `current_step_id: 07-finalize-promote`
+   - `completed_at: <ISO timestamp>`
+
+3. **Print promotion summary**:
+
+```text
+**docs-promote complete**
+Promoted:    <file> → <destination>  (one line per promoted file)
+Deprecated:  <file> → <destination>  (one line per deprecated file)
+Held:        <file> — <reason>       (one line per held/deferred file)
+Errors:      none | <detail>
+```
+
+## Completion rule
+
+Do not report complete until `current-state.json` has `status: complete`.
+
+## Scope
+
+```yaml
+allowed_files:
+  - .taskchain_artifacts/docs-promote/current-state.json
+```
+
+## Artifact update
+
+Emit `step-complete` for `07-finalize-promote` and `docs-promote-complete` to telemetry JSONL.

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

@@ -0,0 +1,94 @@
+---
+name: polaris-analyze
+description: Audit one Polaris issue against the actual repo using a configured repo-analysis provider (if available) and targeted inspection, then produce an ordered execution plan and cluster artifacts. Analysis and planning only — no code changes, no implementation execution.
+role: analyst
+role_file: .polaris/roles/analyst.md
+---
+
+## Command entrypoints
+
+This skill is the target for the following user commands:
+
+- `polaris-analyze <POL-###>`
+- `run polaris-analyze on issue <POL-###>`
+- `run polaris-analyze on <POL-###>`
+
+When any of these commands are issued, load this skill packet **first** before any other action.
+Bind the named issue exactly as specified. See `.polaris/skills/ROUTING.md` for the full routing
+protocol.
+
+---
+
+## Polaris Skill Bootloader
+
+**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
+
+Run the following command:
+
+```
+npm run polaris -- skill packet analyze
+```
+
+- 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.**
+
+---
+
+# polaris-analyze
+
+Use this skill when the user asks to analyze or break down a Polaris issue before execution.
+
+## Related doctrine
+
+See `docs/Polaris/spec/polaris-implementation-plan.md` for the Polaris architecture reference.
+
+## Canonical issue template
+
+All implementation issues (IMPLEMENT parents and children) must use the 8-section canonical format.
+See `.polaris/skills/polaris-analyze/issue-template.md` for the full template.
+
+Key rules:
+- Use `## Scope` exactly — no variants ("Implementation scope", "Expected code areas", etc.).
+- If scope is unknown: write `- TBD — BLOCKED: scope missing` under `## Scope` and mark the issue Blocked in Linear.
+- Both IMPLEMENT parents and child issues require a full body — no title-only stubs.
+- Every child must have `## Scope` and `## Validation` or the dispatch preflight gate will halt execution.
+
+## When to use
+
+- "Analyze POL-XXX before running it"
+- "Break down POL-XXX into child issues"
+- "Is POL-XXX ready to execute?"
+- "Plan the execution clusters for POL-XXX"
+
+## How to execute
+
+1. Read `chain.md` — it defines the step order and traversal rules.
+2. Read `.taskchain_artifacts/polaris-analyze/current-state.json` — it contains any resumable state.
+3. Execute steps in the order `chain.md` defines. Do not skip steps.
+4. After every completed step, update `.taskchain_artifacts/polaris-analyze/current-state.json` before advancing.
+
+## Hard rules — what analyze may do
+
+- Inspect repo files and architecture
+- Query the configured repo-analysis provider for code intelligence (if available; falls back to polaris map query + ripgrep)
+- Summarize findings and assess feasibility
+- Create implementation plans and specs (in `docs/`)
+- Create or update tracker child issues (Linear)
+- Generate local cluster artifacts (`.polaris/clusters/<id>/clusters.json`)
+- Update tracker comments and status
+- Close the analysis issue when complete
+
+## Hard rules — what analyze must NOT do
+
+- Implement production or runtime code
+- Mutate source files (`src/`, tests, config)
+- Execute implementation loops
+- Open implementation PRs
+- Continue automatically into polaris-run execution
+- Call `polaris loop continue` or `polaris finalize`
+
+**Analyze shapes work. Run executes work.**
+
+If implementation execution is attempted during an analyze session: halt immediately and report the boundary violation.

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/chain.json

@@ -0,0 +1,20 @@
+{
+  "name": "polaris-analyze-chain",
+  "steps": [
+    "01-fetch-and-orient",
+    "02-map-affected-code",
+    "03-assess-issue",
+    "04-blocker-check",
+    "05-create-cluster-plan",
+    "06-final-report"
+  ],
+  "terminal_steps": ["06-final-report"],
+  "scope": "analyze-only",
+  "forbidden_actions": [
+    "src file mutations",
+    "polaris loop continue",
+    "polaris finalize",
+    "git push",
+    "pr creation"
+  ]
+}

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

@@ -0,0 +1,105 @@
+---
+name: polaris-analyze-chain
+description: Route map for polaris-analyze — step order, stop conditions, analyze-only boundary enforcement, and artifact requirements.
+---
+
+# polaris-analyze chain
+
+## Authority
+
+**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
+
+Query runtime state before acting. Do not infer analysis scope or prior progress from conversation context.
+
+## CLI
+
+Always use the repo-local Polaris CLI:
+
+```
+npm run polaris -- <command>
+```
+
+Never assume a globally linked `polaris` command exists.
+
+## Step traversal order
+
+```text
+01-fetch-and-orient      ← parallel: Linear fetch + repo-analysis provider check + run-start telemetry
+02-map-affected-code     ← targeted repo-analysis inspection (provider or fallback)
+03-assess-issue          ← outcome classification
+04-blocker-check         ← STOP if blocked or non-executable
+05-create-cluster-plan   ← create tracker children + local clusters.json
+06-final-report          ← terminal step
+```
+
+## Stop conditions
+
+**Step 04 (blocker check):**
+Stop immediately if the issue is blocked or assessment outcome is not `needs-cluster-plan`. Do not advance to step 05.
+
+**Any step:**
+Stop if:
+- Implementation execution is attempted (scope violation — halt and report).
+- Canonical doctrine conflict cannot be resolved without user input.
+- HIGH or CRITICAL risk identified by repo-analysis provider without a clear resolution path.
+- Parent issue is already Done or Cancelled.
+
+## Analyze-only boundary
+
+polaris-analyze is a read-and-plan skill. It never executes implementation work.
+
+The boundary is enforced by this skill — not by the Polaris runtime — because analyze sessions do not call `polaris loop continue`.
+
+If a step produces source code changes, halts on a `src/` file edit, or attempts to push or PR: that is a scope violation. Halt immediately, report the violation, and do not continue.
+
+## Run ID format
+
+Format: `polaris-analyze-<slug>-<date>-<seq>`
+- `<slug>`: 2–4 lowercase hyphenated words from the issue title. No Linear IDs.
+- `<date>`: `YYYY-MM-DD`
+- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
+
+Example: `polaris-analyze-local-instructions-2026-05-23-001`
+
+## Telemetry
+
+Telemetry file: `.taskchain_artifacts/polaris-analyze/runs/<run-id>/telemetry.jsonl` (append-only).
+
+| Event | Emitted by | Step |
+|---|---|---|
+| `run-start` | agent | 01 — before any Linear access |
+| `step-complete` | agent | end of every step |
+| `loop-aborted` | `npm run polaris -- loop abort` | any blocker halt |
+
+Required fields on every event: `event`, `run_id`, `timestamp`.
+
+## Artifact authority
+
+`.taskchain_artifacts/polaris-analyze/current-state.json` is the sole authoritative live state surface.
+
+- Update after every completed step before advancing.
+- If the update fails: stop and report the persistence failure.
+
+## Linked-skill invocation boundaries
+
+| Skill | Allowed steps | Condition |
+|---|---|---|
+| repo-analysis | 01, 02 | targeted lookup only; conditional on provider availability |
+
+After each completed step, emit a checkpoint:
+
+```text
+**[step-name]** done | blocked | needs-input
+Changed: <Linear issues / docs created or updated> or none
+Validated: <checks passed> or none
+Blockers: none | <explicit blocker>
+```
+
+### Never compressed
+
+Always write in full:
+- Child issue bodies and cluster plans (generated planning artifacts)
+- Blocker reports and unblock conditions
+- Doctrine conflict findings
+- HIGH or CRITICAL repo-analysis provider risk findings
+- Final report (step 06)

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/issue-reconciliation.md

@@ -0,0 +1,149 @@
+---
+name: polaris-issue-reconciliation
+description: Workflow for reconciling existing Linear issues into the canonical Polaris format. Use when existing implementation issues are missing required sections or use non-canonical section names.
+---
+
+# Polaris Issue Reconciliation Workflow
+
+Use this workflow to bring existing Linear implementation issues into the canonical 8-section format
+defined in `issue-template.md`. This is not a `polaris-analyze` run — it is a manual or
+scripted reconciliation pass.
+
+## When to use
+
+- An existing IMPLEMENT parent or child issue is blocking a `polaris-run` execution.
+- `polaris-run` reported `preflight-scope-missing` or `preflight-body-missing`.
+- An issue uses non-canonical headers ("Implementation scope", "Expected code areas", etc.).
+- An issue has no body at all (title-only stub).
+- You want to prepare a set of existing issues before starting a new `polaris-run`.
+
+---
+
+## Reconciliation rules
+
+### Preserve original meaning
+
+Do not change what an issue is asking for. Only restructure the body into the canonical format.
+If you are uncertain whether a passage belongs under one header vs. another, preserve it verbatim
+and note the ambiguity in a comment.
+
+### Scope
+
+- If scope is explicitly stated anywhere in the body (paths, globs, named files, module names),
+  move that content into `## Scope` as a bullet list.
+- If scope can be clearly inferred from the objective or goal, write the inferred paths and
+  note that they were inferred: `- src/loop/** (inferred from objective)`.
+- If scope is genuinely not determinable from the existing body, write:
+  ```markdown
+  ## Scope
+  - TBD — BLOCKED: scope missing
+  ```
+  Then mark the issue as **Blocked** in Linear. Do not guess or invent paths.
+
+### Acceptance Criteria and Validation
+
+- If acceptance criteria exist under any heading, move them to `## Acceptance Criteria`.
+- If validation commands exist (e.g. `npm test`, CI commands), move them to `## Validation`.
+- If no validation commands exist, write the standard minimum:
+  ```markdown
+  ## Validation
+  - npm run build
+  - npm test
+  ```
+
+### Links
+
+- Preserve all links to related issues, PRs, and clusters.
+- Move them to `## Context` if they explain why the issue exists.
+- Move them to `## Ordering` if they express a dependency.
+
+### Non-goals / Out of scope
+
+- If the original issue has "Out of scope" or "Non-goals" content, move it to `## Non-goals`.
+
+### Do not mark ready if TBD/BLOCKED remains
+
+If any section still contains `TBD — BLOCKED` after reconciliation, do not change the issue
+status to Ready or In Progress. The issue must remain Blocked until scope (or other TBD content)
+is resolved by a human.
+
+---
+
+## Step-by-step reconciliation prompt
+
+Use this prompt with a capable AI assistant to reconcile a single issue.
+Replace `<ISSUE_BODY>` and `<ISSUE_TITLE>` with the actual content.
+
+```text
+You are reconciling a Polaris Linear issue into the canonical 8-section format.
+
+Issue title: <ISSUE_TITLE>
+Current body:
+---
+<ISSUE_BODY>
+---
+
+Produce a rewritten body using exactly these sections in this order:
+  ## Objective
+  ## Context
+  ## Goal
+  ## Scope
+  ## Acceptance Criteria
+  ## Validation
+  ## Ordering
+  ## Non-goals
+
+Rules:
+1. Preserve original meaning. Do not change what the issue asks for.
+2. Do not invent scope. If scope is stated or clearly inferable, use it.
+   If not, write:
+     ## Scope
+     - TBD — BLOCKED: scope missing
+3. Preserve all links to related issues, PRs, or clusters.
+4. If acceptance criteria exist anywhere, move them under ## Acceptance Criteria.
+5. If validation commands exist, move them under ## Validation.
+   If none exist, add:
+     ## Validation
+     - npm run build
+     - npm test
+6. Do not mark the issue ready if any section still says TBD — BLOCKED.
+7. Output only the rewritten body (no commentary).
+```
+
+---
+
+## Batch reconciliation guidance
+
+For a set of issues before a `polaris-run`:
+
+1. **Identify affected issues**: Run `polaris-run` in dry-run mode or check `clusters.json`
+   for child issue IDs with missing/empty bodies.
+
+2. **Fetch current bodies**: For each issue ID, use the Linear MCP tool or CLI to fetch
+   the current title and body.
+
+3. **Reconcile one at a time**: Apply the reconciliation prompt above to each issue.
+   Review the output before updating Linear.
+
+4. **Update Linear**: Use the Linear MCP `save_issue` tool to update the body of each issue.
+   Do not change issue status unless explicitly reconciling a TBD-BLOCKED scope.
+
+5. **Mark TBD-BLOCKED issues as Blocked**: For any issue where scope is TBD, update the
+   Linear status to Blocked and add a comment explaining what is needed to unblock.
+
+6. **Re-run preflight**: After reconciling, re-run `polaris-run` (or the preflight check)
+   to confirm all issues are now packet-actionable.
+
+---
+
+## Verification after reconciliation
+
+After updating issue bodies, verify the reconciled issues are packet-actionable:
+
+```bash
+# Dry-run a polaris-run to check all preflight gates pass
+npm run polaris -- loop dispatch --dry-run <cluster-id>
+```
+
+All children should pass body and scope preflight gates. If any fail,
+the output will identify which issue and which section is still missing.

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/issue-template.md

@@ -0,0 +1,133 @@
+---
+name: polaris-linear-issue-template
+description: Canonical Linear issue template for Polaris implementation issues. Use for both IMPLEMENT parent issues and child implementation issues.
+---
+
+# Canonical Polaris Linear Issue Template
+
+All implementation issues created by the `polaris-analyze` skill must use this exact structure.
+Sections must appear in this order with these exact `##` headers.
+
+## Why canonical format matters
+
+The Polaris runtime parses issue bodies to derive `allowed_scope` and `validation_commands`
+for worker packets. Non-canonical section names (e.g. "Implementation scope", "Expected code areas")
+cause `allowed_scope` to be empty, which triggers the preflight gate and halts execution.
+
+---
+
+## Template
+
+```markdown
+## Objective
+Short statement of what this issue accomplishes.
+
+## Context
+Why this issue exists. Include relevant bug, PR, cluster, or doctrine context.
+Link to the ANALYZE source issue and any related issues.
+
+## Goal
+Specific implementation outcome.
+
+## Scope
+Machine-readable list of allowed paths or areas. Use explicit repo paths or globs.
+
+- src/loop/**
+- src/finalize/**
+- src/cluster-state/**
+- src/loop/parent.test.ts
+
+## Acceptance Criteria
+
+- [ ] Observable completion requirement 1
+- [ ] Observable completion requirement 2
+- [ ] Tests pass
+
+## Validation
+
+Commands that must be run:
+
+- npm run build
+- npm test
+- npx vitest run src/loop src/finalize src/cluster-state
+
+## Ordering
+
+Dependencies or sequencing relative to sibling issues:
+
+- Depends on <child-id> being Done first (or "None").
+
+## Non-goals
+
+What this issue must not change:
+
+- Do not modify <area>.
+- Do not change <schema/API/etc>.
+```
+
+---
+
+## Rules
+
+### Section names
+
+Use the headers above exactly. Do NOT use:
+
+| Non-canonical (do not use)  | Canonical         |
+|-----------------------------|-------------------|
+| Implementation scope        | `## Scope`        |
+| Expected code areas         | `## Scope`        |
+| Code areas                  | `## Scope`        |
+| Files to change             | `## Scope`        |
+| Test commands               | `## Validation`   |
+| Verify                      | `## Validation`   |
+| Requirements                | `## Acceptance Criteria` |
+| Dependencies / Blockers     | `## Ordering`     |
+| Out of scope                | `## Non-goals`    |
+| Allowed Changes             | *(merge into Scope)* |
+
+Aliases are supported by the body parser for backward compatibility, but new issues
+must always use the canonical header names.
+
+### `## Scope` is required
+
+- Every implementation child issue MUST have `## Scope` with at least one path or glob.
+- Child issues must include their own explicit `## Scope` section (they may not omit it).
+- The runtime derives `allowed_scope` from the child's `## Scope` section. An empty or missing `## Scope` causes
+  a hard preflight failure — the issue cannot be dispatched.
+- If scope is not yet determinable, write:
+
+  ```markdown
+  ## Scope
+  - TBD — BLOCKED: scope missing
+  ```
+
+  Then mark the Linear issue as **Blocked** status. The blocked status prevents dispatch.
+  Do NOT invent paths or use placeholder globs like `src/**`.
+
+### `## Validation` is required
+
+Every implementation issue must list the commands that confirm acceptance criteria are met.
+Minimum: `npm run build` and `npm test`.
+
+### Full bodies required
+
+Neither IMPLEMENT parent issues nor child issues may be title-only stubs. Every issue
+must include all 8 canonical sections, populated with real content.
+
+### IMPLEMENT parents
+
+IMPLEMENT parent issues must include a cluster-wide `## Scope` section for documentation
+and context purposes. However, every child issue must include its own explicit `## Scope`
+section — children may not omit scope to inherit from the parent.
+
+---
+
+## Checklist before marking analysis Done
+
+- [ ] Every IMPLEMENT child has a full body (not title-only)
+- [ ] Every child has `## Scope` with real paths (not `TBD — BLOCKED`)
+- [ ] Every child has `## Validation` with runnable commands
+- [ ] Issues with unknown scope are marked Blocked in Linear
+- [ ] IMPLEMENT parent has a full body with cluster-wide `## Scope`
+- [ ] `clusters.json` references the IMPLEMENT parent as `source_id`

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/linked-skills/repo-analysis.md

@@ -0,0 +1,55 @@
+---
+title: repo-analysis provider linkage
+description: Provide targeted code intelligence when a repo-analysis provider is configured and available in the session environment.
+version: "1.0"
+---
+
+# repo-analysis provider linkage
+
+---
+
+## Allowed steps
+
+- 01-fetch-and-orient
+- 02-map-affected-code
+
+---
+
+## Purpose
+
+Provide targeted code intelligence when polaris-analyze needs to understand the affected code surface.
+
+This linked-skill governs use of the configured repo-analysis provider (e.g., GitNexus). If no provider is available, the fallback path (polaris map query + ripgrep + direct file inspection) is authoritative. See `docs/Polaris/spec/provider-capabilities.md` for the full provider model.
+
+---
+
+## Allowed scope
+
+- Check configured provider availability at session start
+- Query specific files, symbols, or concepts relevant to the issue scope
+- Run impact analysis on symbols mentioned in the issue
+- Check provider index freshness and trigger refresh if stale
+- Report execution flows relevant to the issue
+
+---
+
+## Forbidden scope
+
+- Do not perform broad graph dumps or full-repo reports
+- Do not replace direct repository inspection
+- Do not invoke outside allowed steps
+- Do not assume a specific provider product is present — check availability first
+
+---
+
+## Provider detection
+
+At step 01, check `polaris.config.json` for `providers.repoAnalysis.preferred`.
+If a provider is configured and available in the session environment: use it.
+If unavailable or not configured: note `repo_analysis_status: not-configured` in artifact and proceed with fallback.
+
+---
+
+## Invocation note
+
+Conditional. Invoke when the issue references specific files, symbols, or flows that benefit from graph context. When the provider is unavailable, the fallback path runs instead — the session continues either way.