@lsctech/polaris 0.3.21 → 0.3.23

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

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

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

@@ -1,22 +0,0 @@
-{
-  "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"
-  ]
-}

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

@@ -1,85 +0,0 @@
----
-name: polaris-catalog-chain
-description: Step order, CLI reference, canonical paths, run ID format, telemetry, and artifact authority for polaris-catalog.
----
-
-# polaris-catalog chain
-
-## Authority
-
-**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
-
-Query runtime state before acting. Do not infer affected folders, doc classifications, or
-change scope from conversation context.
-
-## Step traversal order
-
-```text
-01-orient-catalog
-02-reconcile-polaris-md
-03-reconcile-summary-md
-04-classify-and-place
-05-catalog-commit
-```
-
-Read the current step's file in `steps/` before acting. Do not read ahead.
-
-## CLI
-
-Always use the repo-local Polaris CLI:
-
-```
-npm run polaris -- docs ingest --file <path>
-npm run polaris -- doctrine draft <path>
-npm run polaris -- map update --changed
-```
-
-Never assume a globally linked `polaris` command exists.
-
-## Canonical paths
-
-| State | Path |
-|---|---|
-| Doc drop zone | `smartdocs/raw/` |
-| Skill state | `.taskchain_artifacts/polaris-catalog/current-state.json` |
-| Telemetry | `.taskchain_artifacts/polaris-catalog/runs/<run-id>/telemetry.jsonl` |
-
-## Run ID format
-
-`polaris-catalog-<slug>-<YYYY-MM-DD>-<seq>` — e.g. `polaris-catalog-POL-257-2026-06-04-001`
-
-## Telemetry
-
-Append-only JSONL. Required fields: `event`, `run_id`, `timestamp`.
-
-| Event | Trigger |
-|---|---|
-| `run-start` | Begin orient step |
-| `step-complete` | End of every step |
-| `polaris-md-updated` | POLARIS.md written for a folder |
-| `summary-md-updated` | SUMMARY.md written for a folder |
-| `doc-classified` | Classification assigned per file in raw |
-| `doc-placed` | File moved via CLI |
-| `doc-held` | Low-confidence file left in raw |
-| `catalog-commit` | Commit created |
-| `catalog-complete` | All steps done |
-
-## Artifact authority
-
-`.taskchain_artifacts/polaris-catalog/current-state.json` is the sole authoritative
-live state surface.
-
-- Update after every completed step — before advancing.
-- A step is NOT complete until the state update succeeds.
-- If the update fails: stop and report the persistence failure.
-
-## Forbidden actions
-
-- src file mutations
-- runtime state file mutations
-- polaris loop continue
-- polaris finalize
-- git push
-- PR creation
-- mv/cp on files under smartdocs/ (use CLI)
-- auto-placing low-confidence files

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/01-orient-catalog.md

@@ -1,92 +0,0 @@
----
-name: polaris-catalog-step-01
-description: Generate run_id, emit run-start telemetry, validate packet, establish work_inventory, and enumerate smartdocs/raw/ for classification.
----
-
-# Step 01 — Orient catalog
-
-## Purpose
-
-Establish bounded execution context before touching any files. Validate the packet,
-confirm cognition scope, and enumerate `smartdocs/raw/` for the classification step.
-
-## Actions
-
-### 1.1 Generate run_id
-
-Format: `polaris-catalog-<issue-slug>-<YYYY-MM-DD>-<seq>`
-Example: `polaris-catalog-POL-257-2026-06-04-001`
-
-### 1.2 Emit run-start telemetry
-
-First I/O action, before any file access:
-
-```bash
-mkdir -p .taskchain_artifacts/polaris-catalog/runs/<run-id>
-echo '{"event":"run-start","run_id":"<run-id>","issue_id":"<issue_id>","unattended":<bool>,"timestamp":"<ISO>"}' \
-  >> .taskchain_artifacts/polaris-catalog/runs/<run-id>/telemetry.jsonl
-```
-
-If this write fails: halt. Do not continue.
-
-### 1.3 Validate packet
-
-Confirm required fields are present:
-`run_id`, `issue_id`, `affected_folders`, `work_inventory`, `unattended`,
-`allowed_write_paths`, `prohibited_write_paths`, `constraints`
-
-If any required field is missing: halt and report which field is absent.
-
-### 1.4 Build work inventory snapshot
-
-From `packet.work_inventory`, confirm:
-- `affected_folders` — folders whose cognition may need updating
-- `all_changed_files` — files changed by the completed work
-- `child_summaries` — summaries of completed children (if cluster-based)
-- `pending_cognition_notes` — pending cognition notes per folder
-- `polaris_md_files` — current POLARIS.md paths per folder
-- `summary_md_files` — current SUMMARY.md paths per folder
-
-If `affected_folders` is empty: record cognition scope as no-op, continue to step 04 to
-still process any docs in `smartdocs/raw/`.
-
-### 1.5 Enumerate smartdocs/raw/
-
-List all files currently in `smartdocs/raw/` (excluding `.provenance.json` sidecars and
-hidden files). This is the batch for step 04.
-
-If `smartdocs/raw/` is empty or does not exist: record doc classification as no-op.
-Continue — cognition steps may still have work to do.
-
-### 1.6 Restate working context
-
-Summarize in under 10 bullets:
-- `run_id` and fresh/resumed
-- Bound issue
-- Mode: interactive or unattended
-- Affected folders for cognition (count)
-- Files in `smartdocs/raw/` for classification (count)
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .polaris/skills/polaris-catalog/SKILL.md
-  - .polaris/skills/polaris-catalog/chain.md
-  - .taskchain_artifacts/polaris-catalog/current-state.json
-  - smartdocs/raw/ (enumerate only)
-  - packet (read only)
-stop_rules:
-  - run-start telemetry write fails
-  - packet missing required fields
-```
-
-## Artifact update
-
-Update `.taskchain_artifacts/polaris-catalog/current-state.json`:
-- `run_id`, `issue_id`, `unattended`, `status: orienting`, `current_step_id: 01-orient-catalog`
-- `affected_folders`, `raw_files: [...]`, `updated_at: <timestamp>`
-
-## Next step
-
-02-reconcile-polaris-md

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/02-reconcile-polaris-md.md

@@ -1,33 +0,0 @@
----
-name: polaris-catalog-step-02
-description: Update affected POLARIS.md files to accurately reflect the current state of each folder after the completed work.
----
-
-# Step 02 — Reconcile POLARIS.md
-
-Identical in behavior to `polaris-reconcile` step 02. See
-`.polaris/skills/polaris-reconcile/steps/02-reconcile-polaris-md.md` for full detail.
-
-## Summary
-
-For each folder in `work_inventory.affected_folders`:
-1. Assess which files changed and how they affect the folder's operational reality.
-2. Read the current POLARIS.md.
-3. Apply the confidence threshold (≥0.85 write, 0.70–0.84 write with note, <0.70 skip).
-4. Write the full updated POLARIS.md if needed — full replacement, not append.
-5. Record in `polaris_md_updates`.
-
-POLARIS.md is NOT a changelog. Replace stale statements with current truth.
-
-## Output
-
-```yaml
-polaris_md_updates: [
-  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
-  ...
-]
-```
-
-## Next step
-
-03-reconcile-summary-md

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/03-reconcile-summary-md.md

@@ -1,70 +0,0 @@
----
-name: polaris-catalog-step-03
-description: Refresh SUMMARY.md files to reflect current project state after the completed work.
----
-
-# Step 03 — Reconcile SUMMARY.md
-
-Identical in behavior to `polaris-reconcile` step 03. See
-`.polaris/skills/polaris-reconcile/steps/03-reconcile-summary-md.md` for full detail.
-
-## Summary
-
-For each folder in `work_inventory.affected_folders` that has a SUMMARY.md:
-1. Assess staleness against the completed work.
-2. Remove stale information. Replace superseded references. Preserve current understanding.
-3. Write the full updated SUMMARY.md — net new line cap of `packet.constraints.max_summary_addition_lines` (default: 50).
-4. Record in `summary_md_updates`.
-
-SUMMARY.md is NOT a changelog. It must read as a coherent current-state snapshot.
-
-## Required Structure (per June 5 doctrine)
-
-SUMMARY.md must contain the following sections:
-
-### Current State
-Brief description of what is implemented, what is not yet, and known gaps.
-
-### Route Health
-Current operational condition. Example subsections:
-- Healthy
-- Monitoring
-- Known Issues
-- Recent Treatments
-- Improvement Opportunities
-
-Goal: Workers understand route condition in under 10 seconds. Not history, not doctrine, not implementation detail.
-
-### Canonical References
-YAML block listing navigation paths (not reading assignments):
-
-```yaml
-canonical_docs:
-  - smartdocs/active/runtime/worker-packet-contract.md
-  - smartdocs/active/runtime/librarian-closeout.md
-  - POLARIS.md
-```
-
-These are retrieval paths, not preload instructions.
-
-## Reconciliation Behavior
-
-- Do NOT overwrite an existing Route Health section if it has content
-- Do NOT auto-populate Route Health status from runtime data — scaffold a skeleton only
-- Canonical References block must use the `canonical_docs:` key
-- Preserve any existing valid content; only update stale state sections
-
-## Output
-
-```yaml
-summary_md_updates: [
-  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
-  { file: "<path>", action: "no_change" },
-  { file: "<path>", action: "path_not_allowed" },
-  ...
-]
-```
-
-## Next step
-
-04-classify-and-place

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/04-classify-and-place.md

@@ -1,117 +0,0 @@
----
-name: polaris-catalog-step-04
-description: Classify documents in smartdocs/raw/, auto-place high-confidence files via CLI, and surface or hold low-confidence files based on mode.
----
-
-# Step 04 — Classify and place
-
-## Purpose
-
-Process all files enumerated in `current-state.json.raw_files`. Classify each one,
-auto-place high-confidence results via the Polaris CLI, and handle low-confidence files
-according to the session mode (`packet.unattended`).
-
-If `raw_files` is empty: record as no-op and proceed to step 05.
-
-## Classification table
-
-| Class | Target path | Auto-place on high confidence |
-|---|---|---|
-| `runtime-summary` | `smartdocs/runtime/summaries/` | yes |
-| `run-report` | `smartdocs/runtime/run-reports/` | yes |
-| `spec-raw` | `smartdocs/raw/` | no-op (already there) |
-| `spec-active` | `smartdocs/specs/active/` | yes |
-| `audit-finding` | `smartdocs/audits/findings/` | yes |
-| `doctrine-candidate` | `smartdocs/doctrine/candidate/` | yes |
-| `architecture` | `smartdocs/architecture/` | yes |
-| `decision` | `smartdocs/decisions/` | yes |
-| `deprecated-noise` | `smartdocs/runtime/generated/` | yes |
-
-**Confidence is the only gate.** High confidence → place regardless of authority level.
-Low confidence → ask user (interactive) or leave in raw (unattended).
-
-## Classification process (per file)
-
-1. Read the document.
-2. Check for explicit Polaris front-matter (`status`, `authority`, `classification`).
-   If present and unambiguous → **confidence: high**.
-3. Otherwise infer from content signals:
-   - Polaris architectural assertions / "how things should work" → `doctrine-candidate`
-   - Structured spec with Spec ID, Status, Purpose headings → `spec-active`
-   - Run output, telemetry summaries, session notes → `runtime-summary`
-   - Structured run output with metrics → `run-report`
-   - `FINDING:` markers or audit-style analysis → `audit-finding`
-   - ADR-style decision record → `decision`
-   - Architectural diagrams or structural design context → `architecture`
-   - Low-signal, transient, or auto-generated → `deprecated-noise`
-   - Unclear or multiple signals → low confidence, class remains `spec-raw`
-4. Assign confidence:
-   - **high**: explicit front-matter, or exactly one signal matches unambiguously
-   - **low**: multiple signals, sparse content, or no clear signal
-
-## Placement actions
-
-### High confidence
-
-Run the appropriate CLI command immediately. Do not pause for user input.
-
-```bash
-# All classes except doctrine-candidate:
-npm run polaris -- docs ingest --file <path>
-
-# doctrine-candidate:
-npm run polaris -- doctrine draft <path>
-```
-
-Record in `docs_placed`.
-
-### Low confidence — interactive mode (`packet.unattended: false`)
-
-Surface each file to the user:
-
-```text
-needs-input: <filename>
-Inferred class: <class> [confidence: low]
-Reason: <why confidence is low>
-Where should this go? Options:
-  1. <class> → <target>  (inferred)
-  2. Leave in smartdocs/raw/
-  3. [other class]
-```
-
-Wait for user response before placing. Record the user's decision in `docs_placed` or
-`docs_held` accordingly.
-
-### Low confidence — unattended mode (`packet.unattended: true`)
-
-Leave the file in `smartdocs/raw/`. Record in `docs_held` with reason. Do not block.
-Do not fail the run.
-
-## After batch
-
-Run map update:
-
-```bash
-npm run polaris -- map update --changed
-```
-
-## Hard rules
-
-- Use the CLI for all file moves. Never use `mv` or `cp` directly on `smartdocs/` files.
-- If the CLI rejects a file as ignored (`POLARIS.md`, `SUMMARY.md`, `README.md`): leave in
-  raw, record as ineligible in `docs_held`.
-- If a target path collision is detected: record as a blocker for that file. Do not
-  overwrite without explicit user approval.
-- Source files already in `smartdocs/` sub-directories other than `raw/` are out of scope
-  for this step. Skip them.
-
-## Output
-
-```yaml
-docs_placed: [{ file: "<source>", target: "<path>", class: "<class>", confidence: "high" }]
-docs_held: [{ file: "<source>", reason: "<low-confidence|ineligible|collision>", detail: "..." }]
-```
-
-## Next step
-
-05-catalog-commit

package/dist/workspace/workspace/.polaris/skills/polaris-catalog/steps/05-catalog-commit.md

@@ -1,94 +0,0 @@
----
-name: polaris-catalog-step-05
-description: Commit all cognition and document changes as a single sealed catalog commit.
----
-
-# Step 05 — Catalog commit
-
-## Purpose
-
-All changes produced by steps 02–04 must be committed as a single sealed commit.
-This separates implementation commits from documentation and cognition reconciliation.
-
-## Commit constraints
-
-The catalog commit MUST:
-- Contain only files from `packet.allowed_write_paths`
-- Contain no implementation source code
-- Contain no runtime state files (`current-state.json`, telemetry JSONL, cluster-state)
-
-If any staged file would violate these constraints, unstage it and record as a blocker.
-
-## No-change case
-
-If steps 02–04 produced no file changes, this step is a no-op. Record `commit_sha: null`.
-Do not create an empty commit.
-
-## Commit message format
-
-```text
-docs(catalog): reconcile cognition and classify docs for <issue_id>
-
-Run: <run_id>
-Issue: <issue_id>
-Files updated:
-- POLARIS.md: <count> files
-- SUMMARY.md: <count> files
-- docs placed: <count>
-- docs held in raw: <count>
-```
-
-## Actions
-
-### 5.1 Pre-commit validation
-
-Verify:
-1. Every file to be committed is in `packet.allowed_write_paths`.
-2. No file is in `packet.prohibited_write_paths`.
-3. At least one non-empty change exists.
-
-If prohibited files are staged: `git reset HEAD <file>` before committing.
-
-### 5.2 Stage changed files
-
-```bash
-git add <polaris_md_updates[*].file where action == "update">
-git add <summary_md_updates[*].file where action == "update">
-git add <docs_placed[*].target>
-```
-
-### 5.3 Verify staged files
-
-Run `git diff --cached --name-only` and confirm all staged files are in
-`packet.allowed_write_paths` and none are in `packet.prohibited_write_paths`.
-
-### 5.4 Commit
-
-```bash
-git commit -m "<commit message>"
-```
-
-Capture the resulting commit SHA.
-
-### 5.5 Finalize
-
-Update `.taskchain_artifacts/polaris-catalog/current-state.json`:
-- `status: complete`
-- `current_step_id: 05-catalog-commit`
-- `commit_sha: <sha or null>`
-- `completed_at: <ISO timestamp>`
-
-Emit `catalog-commit` and `catalog-complete` telemetry events.
-
-Report summary:
-```text
-polaris-catalog complete
-Issue:           <issue_id>
-Mode:            interactive | unattended
-POLARIS.md:      <count> files updated
-SUMMARY.md:      <count> files updated
-Docs placed:     <count>
-Docs held raw:   <count> (<filenames if any>)
-Commit:          <sha> | no changes
-Blockers:        <none | list>
-```