@lsctech/polaris 0.3.22 → 0.3.24

package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/04-conflict-surface.md

@@ -1,65 +0,0 @@
----
-name: docs-promote-step-04-conflict-surface
-description: Run the CLI conflict gate for each candidate and capture the full report. Do not promote yet.
----
-
-# Step 04 — Conflict surface
-
-## Purpose
-
-Surface every conflict before asking for approval. The agent must not approve anything it has not checked. This step is read-only — no files are moved.
-
-## Actions
-
-### For raw specs (`route: spec-promote`)
-
-Run the dry gate for each:
-
-```bash
-npm run polaris -- doctrine spec-promote <path>
-```
-
-Capture the full stdout. This is the conflict report. Do **not** pass `--approve`.
-
-### For doctrine candidates (`route: doctrine-governance`)
-
-Check front-matter for all required governance fields:
-- `doc-type`
-- `confidence`
-- `recommended-action`
-- `overlap-analysis`
-
-If any field is missing or `recommended-action` is not `promote`: mark as `needs-governance-update`. Do not proceed to promotion for this candidate.
-
-### For active docs targeted for deprecation
-
-Confirm the doc's `linkedMapArea` code is gone or marked superseded (from step 03 findings). If relevance is `current`: flag as `deprecation-contested` — surface to user before acting.
-
-### After all candidates checked
-
-Emit `docs-promote-conflict-report` telemetry for each candidate with their conflict status.
-
-## Scope
-
-```yaml
-allowed_files:
-  - smartdocs/raw/ (read only)
-  - smartdocs/doctrine/candidate/ (read only)
-  - smartdocs/doctrine/active/ (read only)
-  - smartdocs/specs/active/ (read only)
-  - .taskchain_artifacts/docs-promote/current-state.json
-stop_rules:
-  - CLI command exits non-zero unexpectedly (capture output; do not halt batch — record error per candidate)
-```
-
-## Artifact update
-
-Update `current-state.json`:
-- `current_step_id: 04-conflict-surface`
-- Per candidate: `conflict_report: "<captured stdout>"`, `governance_status: ok|needs-governance-update`, `deprecation_status: ok|deprecation-contested`
-
-Emit `step-complete` for `04-conflict-surface`.
-
-## Next step
-
-05-await-approval

package/dist/workspace/workspace/.polaris/skills/docs-promote/steps/05-await-approval.md

@@ -1,61 +0,0 @@
----
-name: docs-promote-step-05-await-approval
-description: Present the full conflict report and linked-code findings to the user. Hard stop — do not advance without explicit approval.
----
-
-# Step 05 — Await approval
-
-## Purpose
-
-The user must see everything before anything is promoted. This step never auto-advances.
-
-## Actions
-
-1. **Present the summary table**:
-
-```text
-| File | Type | Linked Area | Relevance | Conflicts | Governance | Recommended Action |
-```
-
-Fill every column from state. Use `—` only when genuinely unknown.
-
-2. **Print the full conflict report** for any candidate that has one. Never compress or summarize conflict output.
-
-3. **Print governance validation failures** in full for any `needs-governance-update` candidates.
-
-4. **State the recommended action** for each candidate:
-   - `promote` — no conflicts, governance ok, code is current
-   - `promote-with-override` — conflicts detected; user may approve with understanding
-   - `hold` — governance incomplete; needs update before promotion
-   - `deprecate` — code area gone or superseded
-   - `skip` — unlinked or contested; needs human judgment
-
-5. **Stop and wait.** Do not call any CLI command. Do not write any files. Do not advance to step 06.
-
-6. When the user responds: record their decision per candidate in state as `approved`, `rejected`, or `deferred`. Then advance to step 06.
-
-## Hard rule
-
-**Never call `--approve` in this step. Never move files in this step.**
-
-## Scope
-
-```yaml
-allowed_files:
-  - .taskchain_artifacts/docs-promote/current-state.json (read then write after user responds)
-stop_rules:
-  - do not advance without user confirmation
-```
-
-## Artifact update
-
-After user responds, update `current-state.json`:
-- `current_step_id: 05-await-approval`
-- Per candidate: `decision: approved|rejected|deferred`
-
-Emit `docs-promote-approved` or `docs-promote-rejected` telemetry per candidate.
-Emit `step-complete` for `05-await-approval`.
-
-## Next step
-
-06-execute-promote-deprecate

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

@@ -1,65 +0,0 @@
----
-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

@@ -1,44 +0,0 @@
----
-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

@@ -1,94 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
-{
-  "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

@@ -1,105 +0,0 @@
----
-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

@@ -1,149 +0,0 @@
----
-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.