@lsctech/polaris 0.3.21 → 0.3.23

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

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

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

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/01-fetch-and-orient.md

@@ -1,79 +0,0 @@
----
-name: polaris-analyze-step-01-fetch-and-orient
-description: Generate run_id, emit run-start telemetry, fetch the Linear issue and check repo-analysis provider availability in parallel.
----
-
-# Step 01 — Fetch and orient
-
-## Purpose
-
-Load the issue state, confirm the repo index is current, and establish governed session context before any inspection.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .polaris/skills/polaris-analyze/SKILL.md
-  - .polaris/skills/polaris-analyze/chain.md
-  - .taskchain_artifacts/polaris-analyze/current-state.json
-allowed_routes:
-  - CLAUDE.md
-  - docs/Polaris/spec/polaris-implementation-plan.md
-  - .polaris/skills/polaris-analyze/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - run_id generated
-  - run-start telemetry emitted
-  - Linear issue fetched
-  - repo-analysis provider status checked
-  - analysis target and context recorded
-stop_rules:
-  - run-start telemetry write fails
-  - issue missing or inaccessible
-  - issue is already Done or Cancelled
-```
-
-## Actions
-
-0. **Generate `run_id`** — pure local computation:
-   - Format: `polaris-analyze-<slug>-<date>-<seq>` (see `chain.md` for format rules)
-   - For resumed sessions, read the prior `run_id` from current-state.json first.
-
-1. **Emit `run-start` telemetry** — first I/O action:
-   ```bash
-   mkdir -p .taskchain_artifacts/polaris-analyze/runs/<run-id>
-   echo '{"event":"run-start","run_id":"<run-id>","prior_run_id":"<prior or null>","timestamp":"<ISO>"}' \
-     >> .taskchain_artifacts/polaris-analyze/runs/<run-id>/telemetry.jsonl
-   ```
-   If this write fails: halt.
-
-2. Run both of the following **in the same turn** (independent, parallelizable):
-   - Fetch the Linear issue by ID. Read: title, description, labels, state, priority, existing child issues, blocking relationships.
-     - If already Done or Cancelled: report and stop.
-   - Check `polaris.config.json` for `providers.repoAnalysis.preferred`.
-     - If a provider is configured and available in the session environment:
-       - Check provider index freshness. If stale: attempt refresh per provider's documented mechanism.
-       - Record `repo_analysis_status: available` in artifact.
-     - If not configured or unavailable:
-       - Note: no repo-analysis provider available — polaris map query + direct inspection will be used in step 02.
-       - Record `repo_analysis_status: not-configured` or `unavailable` accordingly.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-analyze/current-state.json`:
-- `run_id: <generated>`
-- `cluster_id: <issue ID>`
-- `skill: polaris-analyze`
-- `artifact_dir: ".taskchain_artifacts/polaris-analyze"`
-- `status: running`
-- `parent_issue: <ID — title>`
-- `repo_analysis_status: available | unavailable | not-configured`
-- `current_step_id: 01-fetch-and-orient`
-- `started_at: <timestamp>`
-
-Emit `step-complete` for `01-fetch-and-orient` to telemetry JSONL.
-
-## Next step
-
-02-map-affected-code

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/02-map-affected-code.md

@@ -1,58 +0,0 @@
----
-name: polaris-analyze-step-02-map-affected-code
-description: Use the configured repo-analysis provider (if available) or the fallback path to map the files, symbols, and execution flows affected by the issue scope.
----
-
-# Step 02 — Map affected code
-
-## Purpose
-
-Identify the files, symbols, and execution flows relevant to the issue before assessing feasibility or decomposition.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - files named in Linear issue
-  - nearest POLARIS.md or INSTRUCTIONS.md for named paths
-  - repo-analysis provider query results for issue concepts (when provider is available)
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-analyze/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - affected files and symbols listed
-  - impact and execution-flow evidence recorded
-  - unknown surfaces called out
-stop_rules:
-  - issue has no mappable code surface
-  - repo-analysis provider result is stale and cannot be refreshed (only when provider is in use; if unavailable use fallback)
-  - mapping requires broad unrelated traversal
-```
-
-## Actions
-
-1. Check `repo_analysis_status` from the step 01 artifact.
-2. **If provider is available:** use it for targeted inspection only — query concepts relevant to the issue scope. Use impact analysis and context queries for specific symbols mentioned in the issue. Do not summarize the whole repo.
-3. **If provider is unavailable (fallback path):**
-   - Use `npm run polaris -- map query <path>` for route/domain/taskchain context on affected files
-   - Use `rg <symbol>` for symbol and pattern location across the repo
-   - Use direct file inspection for implementation details
-   - The fallback path is always sufficient to complete the analysis.
-4. Always run `npm run polaris -- map query <path>` for each affected file — it provides Polaris-specific routing context regardless of whether a provider is also in use.
-5. Inspect only files relevant to the issue scope.
-6. Record the files and execution flows inspected.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-analyze/current-state.json`:
-- `files_inspected: [<list of files/flows>]`
-- `current_step_id: 02-map-affected-code`
-- `updated_at: <timestamp>`
-
-Emit `step-complete` for `02-map-affected-code` to telemetry JSONL.
-
-## Next step
-
-03-assess-issue

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/03-assess-issue.md

@@ -1,58 +0,0 @@
----
-name: polaris-analyze-step-03-assess-issue
-description: Classify the issue into one of five outcomes based on Linear state and repo inspection results.
----
-
-# Step 03 — Assess issue
-
-## Purpose
-
-Determine whether the issue is executable, already satisfied, blocked, ambiguous, or needs splitting before planning clusters.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - Linear issue description and comments
-  - affected-code map from step 02
-  - direct file snippets needed to verify claims
-allowed_routes:
-  - CLAUDE.md
-  - docs/Polaris/spec/polaris-implementation-plan.md
-  - .polaris/skills/polaris-analyze/chain.md
-expected_evidence:
-  - issue classified as one of five outcomes
-  - evidence supports classification
-  - recommended next action recorded
-stop_rules:
-  - claims cannot be verified
-  - acceptance criteria are ambiguous without user input
-  - assessment depends on external state unavailable to this run
-```
-
-## Actions
-
-Determine one of the following outcomes:
-
-| Outcome | Condition |
-|---|---|
-| **Already satisfied** | Repo already implements what the issue describes |
-| **Needs cluster plan** | Clear implementation work can be decomposed into executable clusters |
-| **Needs doctrine clarification** | Issue is ambiguous or conflicts with existing architecture |
-| **Blocked** | A prerequisite issue or condition is unmet |
-| **Should be split** | Issue spans multiple unrelated concerns |
-
-Report the outcome with evidence before advancing to step 04.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-analyze/current-state.json`:
-- `outcome: <already-satisfied | needs-cluster-plan | needs-doctrine-clarification | blocked | should-be-split>`
-- `current_step_id: 03-assess-issue`
-- `updated_at: <timestamp>`
-
-Emit `step-complete` for `03-assess-issue` to telemetry JSONL.
-
-## Next step
-
-04-blocker-check

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/04-blocker-check.md

@@ -1,60 +0,0 @@
----
-name: polaris-analyze-step-04-blocker-check
-description: Halt if the issue is blocked or non-executable; advance to cluster planning only if outcome is needs-cluster-plan.
----
-
-# Step 04 — Blocker check
-
-## Purpose
-
-Stop forward execution if the issue cannot proceed. Only `needs-cluster-plan` advances to step 05.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - Linear issue relations and labels
-  - assessment output from step 03
-allowed_routes:
-  - CLAUDE.md
-  - .polaris/skills/polaris-analyze/chain.md
-expected_evidence:
-  - blockers and unblock conditions listed
-  - safe continuation decision recorded
-stop_rules:
-  - blocking dependency exists
-  - outcome is not needs-cluster-plan
-```
-
-## Actions
-
-**If outcome is `blocked`:**
-1. Add a comment to the parent issue explaining the unblock condition.
-2. Apply a blocked label if available.
-3. Halt. Do not advance to step 05.
-
-**If outcome is `already-satisfied`, `needs-doctrine-clarification`, or `should-be-split`:**
-1. Produce the appropriate report describing the finding and recommended next action.
-2. Do not create cluster plans or child issues.
-3. Halt.
-
-**If outcome is `needs-cluster-plan`:** advance to step 05.
-
-## Artifact update
-
-If halting:
-- `status: blocked | halted`
-- `current_step_id: 04-blocker-check`
-- `next_step: halted`
-- `updated_at: <timestamp>`
-
-If advancing:
-- `current_step_id: 04-blocker-check`
-- `next_step: 05-create-cluster-plan`
-- `updated_at: <timestamp>`
-
-Emit `step-complete` for `04-blocker-check` to telemetry JSONL.
-
-## Next step
-
-05-create-cluster-plan (if `needs-cluster-plan`), or halted

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/05-create-cluster-plan.md

@@ -1,197 +0,0 @@
----
-name: polaris-analyze-step-05-create-cluster-plan
-description: Create ordered child issues in the tracker (if tracker-backed) and generate a local clusters.json artifact for polaris-run to consume.
----
-
-# Step 05 — Create cluster plan
-
-## Purpose
-
-Produce an ordered execution plan that polaris-run can execute without ambiguity. Always generate a local `clusters.json` artifact. For tracker-backed workflows, also create Linear child issues.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - assessment output from steps 03-04
-  - .polaris/clusters/<source-id>/clusters.json
-  - docs/ (for any analysis docs produced)
-  - Linear project/team metadata
-allowed_routes:
-  - CLAUDE.md
-  - docs/Polaris/spec/polaris-implementation-plan.md
-  - .polaris/skills/polaris-analyze/chain.md
-expected_evidence:
-  - clusters.json written to .polaris/clusters/<implement-parent-id>/clusters.json
-  - Linear IMPLEMENT parent issue created under the ANALYZE issue (tracker-backed)
-  - Linear child issues created under the IMPLEMENT parent (tracker-backed) or task list updated (trackerless)
-  - execution ordering is unambiguous
-  - no source code changes made
-stop_rules:
-  - cluster boundary is not evidence-backed
-  - would require source code changes to produce the plan
-  - blocked parent should not receive cluster plan
-```
-
-## Hard rules
-
-- No source code (`src/`, tests, config) may be created or modified in this step.
-- Cluster plans are analysis artifacts only.
-- If source code changes are needed to plan: note them as findings in the plan — do not make them.
-
-## Actions
-
-### 1. Design execution clusters
-
-Group the work into executable clusters. Each cluster maps to one polaris-run session.
-
-Ordering rules:
-- Clusters with no dependencies execute first.
-- No forward dependencies within a cluster.
-- Children within a cluster execute in ascending numeric/dependency order.
-- Analyze-type children must precede implement-type children in mixed clusters.
-
-Each child must have:
-- `session_type`: `analyze` | `implement`
-- `blockedBy`: list of child IDs that must be Done first (empty list if none)
-- A well-scoped Linear issue body (see below) for tracker-backed workflows
-
-### 2. Create Linear IMPLEMENT parent issue (tracker-backed only)
-
-Before creating any child issue, create or reuse a separate Linear IMPLEMENT parent issue:
-- Title: `IMPLEMENT: <slug>`
-- Parent: the ANALYZE source issue that produced this cluster plan
-- Purpose: hold executable implementation children for `polaris-run`
-
-If a matching IMPLEMENT parent already exists under the ANALYZE issue, update/refine it instead of duplicating it.
-
-Children must be created under the IMPLEMENT parent, not under the ANALYZE issue.
-
-**The IMPLEMENT parent MUST have a full body using the canonical format.** Title-only stubs are not allowed. Use:
-
-```text
-## Objective
-One sentence. What this cluster accomplishes when complete.
-
-## Context
-Why this cluster was created. Link to ANALYZE source issue.
-
-## Goal
-The specific implementation outcome for the entire cluster.
-
-## Scope
-Cluster-wide allowed paths or globs for documentation purposes. Each child must include its own explicit ## Scope.
-- <path-or-glob>
-- ...
-
-## Acceptance Criteria
-- Verifiable conditions for the cluster as a whole.
-
-## Validation
-- <command>
-- ...
-
-## Ordering
-Dependencies relative to other IMPLEMENT clusters, if any.
-
-## Non-goals
-What the cluster must not change.
-```
-
-### 3. Write clusters.json
-
-Always write to `.polaris/clusters/<implement-parent-id>/clusters.json`.
-
-Set `clusters.json` `source_id` to the IMPLEMENT parent issue ID, not the ANALYZE issue ID. Set `analyze_source_id` to the ANALYZE issue ID for traceability.
-
-```json
-{
-  "source_id": "<Linear IMPLEMENT parent issue ID>",
-  "analyze_source_id": "<Linear ANALYZE issue ID>",
-  "source_type": "linear",
-  "created_at": "<ISO timestamp>",
-  "clusters": [
-    {
-      "cluster_id": "cluster-01",
-      "children": [
-        {
-          "id": "<Linear child issue ID or planned ID>",
-          "title": "<child title>",
-          "session_type": "analyze | implement",
-          "blockedBy": []
-        }
-      ]
-    }
-  ]
-}
-```
-
-For trackerless workflows (`source_type: "local"`), IDs are locally generated slugs. polaris-run reads from clusters.json rather than Linear.
-
-### 4. Create Linear child issues (tracker-backed only)
-
-**Before creating any child:**
-- Check all existing child issues.
-- If a matching child already exists, update/refine it — do not duplicate.
-- Confirm the child parent is the IMPLEMENT parent issue.
-
-**Every child issue MUST have a full body. Title-only stubs are not allowed.**
-
-**Canonical child issue body format (use this exactly):**
-
-```text
-## Objective
-One sentence. What this child achieves when complete.
-
-## Context
-Why this child exists. Include relevant bug, PR, cluster, or doctrine context.
-
-## Goal
-Specific implementation outcome for this child.
-
-## Scope
-Machine-readable list of allowed paths or globs. Use explicit repo paths.
-- src/loop/**
-- src/finalize/**
-
-## Acceptance Criteria
-- Verifiable condition 1
-- Verifiable condition 2
-
-## Validation
-- npm run build
-- npm test
-- npx vitest run <relevant paths>
-
-## Ordering
-- List of sibling child IDs this child depends on (or "None").
-
-## Non-goals
-- What this child must not change.
-```
-
-**Critical rules for `## Scope`:**
-
-- Use the header `## Scope` exactly — not "Implementation scope", "Expected code areas", "Files", or any other variant. Aliases exist for backward compatibility only; new issues must use `## Scope`.
-- List explicit repo paths or globs, one per bullet.
-- If scope is not yet determinable, write:
-  ```markdown
-  ## Scope
-  - TBD — BLOCKED: scope missing
-  ```
-  and mark the Linear issue as **Blocked** status. Do NOT invent paths. A blocked issue will not be dispatched by polaris-run.
-- Do not omit the `## Scope` section. A missing scope section causes a hard preflight failure at dispatch time.
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-analyze/current-state.json`:
-- `clusters_file: ".polaris/clusters/<implement-parent-id>/clusters.json"`
-- `child_issues: [<ID — title>, ...]`
-- `current_step_id: 05-create-cluster-plan`
-- `updated_at: <timestamp>`
-
-Emit `step-complete` for `05-create-cluster-plan` to telemetry JSONL.
-
-## Next step
-
-06-final-report