@lsctech/polaris 0.1.0 → 0.1.3

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

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

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

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

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

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

package/dist/workspace/workspace/.polaris/skills/polaris-analyze/steps/06-final-report.md

@@ -0,0 +1,60 @@
+---
+name: polaris-analyze-step-06-final-report
+description: Produce the structured analysis summary, cluster plan, and recommended polaris-run command.
+---
+
+# Step 06 — Final report
+
+## Purpose
+
+Deliver the complete analysis result and the command the operator needs to begin implementation.
+
+## Scope declarations
+
+```yaml
+allowed_files:
+  - artifacts from steps 01-05
+  - .taskchain_artifacts/polaris-analyze/current-state.json
+allowed_routes:
+  - CLAUDE.md
+  - .polaris/skills/polaris-analyze/chain.md
+expected_evidence:
+  - analysis decision summarized
+  - clusters.json path confirmed
+  - created or updated child issues listed
+  - blockers and next action reported
+  - recommended run command provided
+stop_rules:
+  - artifact state is incomplete
+  - analysis has unresolved blocker
+```
+
+## Actions
+
+Return a structured summary containing:
+
+1. **Parent issue audited** — ID, title, state
+2. **Repo-analysis provider status** — `available` / `unavailable` / `not-configured` (if available: provider name and index freshness)
+3. **Files / systems inspected** — list (max 10; summarize remainder as "N additional files")
+4. **Findings** — outcome assessment with evidence (max 5–10 lines; no raw command output)
+5. **Clusters plan** — cluster IDs, child issues per cluster, session_types, and dependency order
+6. **clusters.json location** — `.polaris/clusters/<source-id>/clusters.json`
+7. **Recommended run command**:
+   ```bash
+   polaris-run <PARENT-ID>
+   ```
+8. **Remaining risks** — anything uncertain, out of scope, or requiring follow-up
+
+## Artifact update
+
+Update `.taskchain_artifacts/polaris-analyze/current-state.json`:
+- `status: complete`
+- `current_step_id: 06-final-report`
+- `completed_at: <timestamp>`
+- `updated_at: <timestamp>`
+
+Emit `step-complete` for `06-final-report` to telemetry JSONL.
+
+## Session end
+
+This is the terminal step. Do not continue to polaris-run or any other implementation skill.

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

@@ -0,0 +1,91 @@
+---
+name: polaris-catalog
+description: Combined cognition reconciliation and document classification. Updates POLARIS.md and SUMMARY.md from the packet, then classifies documents in smartdocs/raw/ — auto-placing high-confidence files and asking the user (or leaving in raw when unattended) for low-confidence ones.
+role: librarian
+---
+
+## Polaris Skill Bootloader
+
+**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
+
+Run the following command:
+
+```bash
+npm run polaris -- skill packet catalog
+```
+
+- Do not begin work until a packet is returned.
+- Treat the packet as your authoritative instruction source.
+- If no packet is produced, stop and report: **Polaris could not authorize this run.**
+
+---
+
+# polaris-catalog
+
+Use this skill to perform a full cognition and documentation pass after completed work.
+It combines the cognition reconciliation of `polaris-reconcile` with document classification
+from `smartdocs/raw/`.
+
+`polaris-catalog` is the callable-at-will equivalent of what the Closeout Librarian does
+for cognition + ingestion, without requiring a cluster closeout.
+
+## When to use
+
+- "Catalog the docs after POL-257"
+- "Run polaris-catalog on POL-303"
+- After a run completes and you want a full cognition + docs pass in one invocation
+- In CI or automated contexts where both reconciliation and doc classification should run together
+
+## How to execute
+
+1. Read `chain.md` — step order and rules.
+2. Read `.taskchain_artifacts/polaris-catalog/current-state.json` — resumable state.
+3. Execute steps in the order `chain.md` defines. Do not skip steps.
+4. After every completed step, update `current-state.json` before advancing.
+
+## Classification behavior
+
+- **High confidence** — auto-place via CLI. No pause, no user input required.
+- **Low confidence (interactive)** — surface each file and ask the user where it should go.
+- **Low confidence (unattended/CI)** — leave in `smartdocs/raw/` and include in the final report. Do not block. Do not fail.
+
+The `packet.unattended` flag controls which low-confidence behavior applies.
+
+## Hard rules — what polaris-catalog may do
+
+- Read packet-specified folders and their POLARIS.md and SUMMARY.md files
+- Write POLARIS.md and SUMMARY.md files within `packet.allowed_write_paths`
+- Read `smartdocs/raw/` to enumerate documents for classification
+- Call `npm run polaris -- docs ingest --file <path>` to place classified documents
+- Call `npm run polaris -- doctrine draft <path>` for doctrine candidates
+- Call `npm run polaris -- map update --changed` after batch placement
+- Create a single sealed git commit of all cognition and doc changes
+
+## Hard rules — what polaris-catalog must NOT do
+
+- Modify implementation source code (`src/`, tests, config)
+- Modify runtime state files outside this skill's owned artifacts (cluster-state, other skills' `.taskchain_artifacts/` state, or non-catalog telemetry)
+- Call `npm run polaris -- loop continue` or `npm run polaris -- finalize`
+- Write to `packet.prohibited_write_paths`
+- Git push or create PRs
+- Auto-place low-confidence files (always leave in raw or ask)
+- Move files under `smartdocs/` directly with `mv` or `cp` — use the CLI
+
+## Packet schema
+
+The packet is a `CatalogPacket`. Required fields:
+
+| Field | Description |
+|---|---|
+| `run_id` | Identifier for this catalog run |
+| `issue_id` | Bound issue (e.g. `POL-257`) |
+| `affected_folders` | Folders whose POLARIS.md and/or SUMMARY.md may need updating |
+| `work_inventory` | Summary of completed work: changed files, child summaries, cognition notes |
+| `unattended` | Boolean — `true` means CI/automated context; low-confidence files left in raw |
+| `allowed_write_paths` | Paths this skill may write |
+| `prohibited_write_paths` | Paths this skill must not write |
+| `constraints.max_summary_addition_lines` | Net new line cap per SUMMARY.md update (default: 50) |
+
+## Execution
+
+Read `chain.md` and execute steps in strict order. Do not skip steps. Do not reorder steps.

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

@@ -0,0 +1,22 @@
+{
+  "name": "polaris-catalog-chain",
+  "steps": [
+    "01-orient-catalog",
+    "02-reconcile-polaris-md",
+    "03-reconcile-summary-md",
+    "04-classify-and-place",
+    "05-catalog-commit"
+  ],
+  "terminal_steps": ["05-catalog-commit"],
+  "scope": "cognition-and-docs",
+  "forbidden_actions": [
+    "src file mutations",
+    "runtime state file mutations",
+    "polaris loop continue",
+    "polaris finalize",
+    "git push",
+    "pr creation",
+    "mv/cp on smartdocs/ files",
+    "auto-placing low-confidence files"
+  ]
+}