@lsctech/polaris 0.3.22 → 0.3.24

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/07-yaml-linking.md

@@ -1,95 +0,0 @@
----
-name: closeout-librarian-step-07
-description: Update YAML frontmatter references, SUMMARY.md cognition mappings, and cognition index entries for promoted or ingested documents.
----
-
-# Step 07 — YAML Linking
-
-## Purpose
-
-When documents are promoted or ingested, the project's internal reference graph must
-be updated so promoted documents can be discovered through cognition and summary artifacts.
-
-## What Must Be Updated
-
-### 7.1 Promoted Document YAML Frontmatter
-
-For each document promoted to `smartdocs/specs/active/` in step 05:
-- Ensure `status: active` in frontmatter (set if missing).
-- Ensure `created` date is present (set if missing).
-- Add `promoted_by: closeout-librarian` metadata if not present.
-- Do NOT modify the document body beyond frontmatter.
-
-### 7.2 SUMMARY.md Cognition References
-
-When SUMMARY.md files were updated in step 04 and reference cognition indexes or spec
-documents, ensure those references use the post-promotion canonical paths.
-
-Specifically: if step 05 promoted a document from `raw/` to `specs/active/`, any
-SUMMARY.md reference to the old raw path should be updated to the new canonical path.
-
-This is a targeted fixup following the broader link validation in step 06. Step 06 handles
-structural link repair; step 07 handles the semantic reference graph.
-
-### 7.3 Cognition Index Updates
-
-For each folder that had cognition notes archived in step 05:
-1. Read the existing `cognition-index.json` (or initialize if not present).
-2. Add a reconciliation record:
-   ```json
-   {
-     "run_id": "<packet.run_id>",
-     "reconciled_at": "<ISO timestamp>",
-     "notes_archived": ["<filename>", ...],
-     "patches_applied": ["<polaris.md path>", ...],
-     "librarian_confidence": <average confidence from step 03>,
-     "status": "applied" | "no-change" | "rejected",
-     "librarian_role": "closeout-librarian"
-   }
-   ```
-3. Write the updated `cognition-index.json`.
-
-### 7.4 SmartDocs Reference Discovery
-
-If any SUMMARY.md references `smartdocs/specs/active/*.md` files, verify those files
-were not renamed or moved during this session. If they were, update the reference.
-
-## Write Constraints
-
-All YAML updates must:
-1. Preserve the rest of the file content unchanged.
-2. Stay within `packet.allowed_write_paths`.
-3. Not modify document bodies (only frontmatter and frontmatter-level metadata files).
-
-## Actions
-
-### 7.1 Frontmatter Updates
-
-For each promoted document (from step 05 `docs_ingested` list):
-- Update `status`, `created`, `promoted_by` fields.
-- Write the updated frontmatter block.
-
-### 7.2 Summary Reference Updates
-
-For each SUMMARY.md written in step 04:
-- Find references to documents promoted in step 05.
-- Update raw→canonical path.
-
-### 7.3 Cognition Index Write
-
-For each folder with archived cognition notes (from step 05):
-- Load or initialize `cognition-index.json`.
-- Append the reconciliation record.
-- Write the file.
-
-## Output
-
-Running list for step 09:
-```yaml
-yaml_updates: [
-  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
-  ...
-]
-```
-
-Proceed to step 08.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/08-librarian-commit.md

@@ -1,119 +0,0 @@
----
-name: closeout-librarian-step-08
-description: Commit all documentation and cognition changes as a single sealed librarian commit.
----
-
-# Step 08 — Librarian Commit
-
-## Purpose
-
-All documentation changes produced by steps 03–07 must be committed as a single commit
-before the Foreman proceeds to finalize. This separates implementation commits (from workers)
-from documentation reconciliation commits (from the Librarian).
-
-## Commit Constraints
-
-The Librarian 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)
-- Be a distinct commit from any worker implementation commit
-- Use the canonical commit message format (see below)
-
-If any staged file would violate these constraints, unstage it and record as a blocker.
-
-## Pre-Commit Validation
-
-Before staging, verify:
-1. Every file to be committed exists at a path within `packet.allowed_write_paths`.
-2. No file is at a path matching `packet.prohibited_write_paths`.
-3. At least one non-empty change exists (if no changes, skip commit and record no-op).
-
-If prohibited files are staged: `git reset HEAD <file>` before committing.
-
-## No-Change Case
-
-If steps 03–07 produced no file changes (everything was already current), step 08 is a
-no-op. Record `commit_sha: null` in the result. The Foreman will accept a null commit SHA
-from the Librarian result.
-
-## Commit Message Format
-
-```text
-docs(closeout): reconcile cognition for cluster <cluster_id>
-
-Run: <run_id>
-Cluster: <cluster_id>
-Children: <comma-separated completed child IDs>
-Files updated:
-- POLARIS.md: <count> files
-- SUMMARY.md: <count> files
-- docs ingested: <count>
-- links repaired: <count>
-```
-
-Example:
-```text
-docs(closeout): reconcile cognition for cluster POL-303
-
-Run: polaris-run-closeout-librarian-2026-06-03-001
-Cluster: POL-303
-Children: POL-304, POL-305, POL-306, POL-307
-Files updated:
-- POLARIS.md: 3 files
-- SUMMARY.md: 2 files
-- docs ingested: 1
-- links repaired: 2
-```
-
-## Actions
-
-### 8.1 Stage Changed Files
-
-Stage all files that were written in steps 03–07:
-```bash
-git add <polaris_md_updates[*].file>
-git add <summary_md_updates[*].file>
-git add <docs_ingested[*].target_path>
-git add <yaml_updates[*].file>
-git add <cognition archive paths>
-git add <cognition-index.json paths>
-```
-
-### 8.2 Verify Staged Files
-
-Run `git diff --cached --name-only` and verify:
-- All staged files are in `packet.allowed_write_paths`
-- None are in `packet.prohibited_write_paths`
-
-If any violation: unstage the offending file, record as blocker.
-
-### 8.3 Commit
-
-If staged files exist:
-```bash
-git commit -m "<commit message>"
-```
-
-Capture the resulting commit SHA.
-
-### 8.4 Record
-
-Record the commit SHA and list of committed files for step 09.
-
-## Failure Handling
-
-If `git commit` fails:
-- Record `status: "failure"` in the running result state.
-- Record the commit error in `blockers`.
-- Proceed to step 09 (write failure result).
-
-If no files were staged (no-change case):
-- Record `commit_sha: null`.
-- Proceed to step 09.
-
-## Emit Telemetry
-
-Emit `librarian-commit` event with `commit_sha` and `files_changed` count.
-
-Proceed to step 09.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/09-sealed-result.md

@@ -1,118 +0,0 @@
----
-name: closeout-librarian-step-09
-description: Write the sealed CloseoutLibrarianResult JSON to result_path and terminate.
----
-
-# Step 09 — Sealed Result
-
-## Purpose
-
-The Librarian's sole communication channel with the Foreman is the sealed result JSON.
-This step assembles the result from all prior steps and writes it to `packet.result_path`.
-
-After writing the result, the Librarian session terminates. No further writes are permitted.
-
-## Result Schema
-
-```typescript
-interface CloseoutLibrarianResult {
-  schema_version: "1.0";
-  role: "closeout-librarian";
-  run_id: string;
-  dispatch_id: string;
-  cluster_id: string;
-  status: "success" | "partial" | "blocked" | "failure";
-  commit_sha: string | null;
-  commit_message: string;
-  files_committed: string[];
-  drift_reconciliation: DriftReconciliationResult;
-  polaris_md_updates: FileUpdate[];
-  summary_md_updates: FileUpdate[];
-  docs_ingested: DocAction[];
-  docs_archived: DocAction[];
-  yaml_updates: FileUpdate[];
-  cognition_archived: CognitionArchiveEntry[];
-  link_validation: LinkValidationReport;
-  blockers: LibrarianBlocker[];
-  reconciled_at: string;       // ISO8601
-  evidence_summary: string;    // ≤200 words
-}
-```
-
-## Status Determination
-
-| Condition | Status |
-|---|---|
-| Commit succeeded, no blockers | `"success"` |
-| Commit succeeded, informational blockers only | `"success"` |
-| Commit succeeded, some work could not be done (recoverable blockers) | `"partial"` |
-| No changes needed (everything already current) | `"success"` (commit_sha: null) |
-| Some work attempted but blocked before commit | `"blocked"` |
-| Commit failed | `"failure"` |
-| Packet unreadable or invalid | `"failure"` |
-
-## Evidence Summary
-
-The `evidence_summary` field must be ≤200 words. It should describe:
-- What was reconciled (POLARIS.md updated, docs ingested, etc.)
-- What was left as-is (already current)
-- Any blockers that require operator attention
-- What a future session needs to know
-
-Write it for a human operator or Foreman, not for a technical log.
-
-## Foreman Validation (Foreman Reads This)
-
-The Foreman validates the result before proceeding to `polaris finalize`:
-1. `status` must be `"success"` or `"partial"` to proceed.
-2. `"blocked"` or `"failure"` halts finalize and escalates to the operator.
-3. `commit_sha` (if non-null) must be reachable in the current git log.
-4. `files_committed` must not include any path from `prohibited_write_paths`.
-
-## Actions
-
-### 9.1 Assemble Result
-
-Collect from all prior steps:
-- `drift_reconciliation` (step 02)
-- `polaris_md_updates` (step 03)
-- `summary_md_updates` (step 04)
-- `docs_ingested`, `docs_archived`, `cognition_archived` (step 05)
-- `link_validation` (step 06)
-- `yaml_updates` (step 07)
-- `commit_sha`, `files_committed` (step 08)
-- Blockers accumulated across all steps
-
-### 9.2 Determine Status
-
-Apply the status determination matrix above.
-
-### 9.3 Write Evidence Summary
-
-Write a ≤200-word plain-text summary of what the Librarian did and what remains.
-
-### 9.4 Write Result File
-
-Write the assembled JSON to `packet.result_path`.
-
-Verify the write succeeded (file exists and is valid JSON after write).
-
-### 9.5 Emit Telemetry
-
-Emit `librarian-complete` event with `status` and `run_id`.
-
-### 9.6 Terminate
-
-The Closeout Librarian session ends here. No further output, no further writes.
-
----
-
-## Failure Recovery (Result Write Fails)
-
-If `packet.result_path` cannot be written:
-1. Write a minimal failure result to stderr:
-   ```text
-   CLOSEOUT_LIBRARIAN_RESULT_WRITE_FAILED: run_id=<run_id> dispatch_id=<dispatch_id> status=failure
-   ```
-2. The Foreman must detect this condition and escalate to the operator.
-3. Do not attempt to write the result to a different path.

package/dist/workspace/workspace/.polaris/skills/docs-ingest/SKILL.md

@@ -1,68 +0,0 @@
----
-name: docs-ingest
-description: Classify, route, and link documents from the raw drop zone into the canonical smartdocs/ authority structure. Docs routing only — no source code changes, no implementation execution.
-role: librarian
-role_file: .polaris/roles/librarian.md
----
-
-## Polaris Skill Bootloader
-
-**Before proceeding, you must obtain a skill packet from the Polaris runtime.**
-
-Run the following command:
-
-```
-npm run polaris -- skill packet ingest
-```
-
-- 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.**
-
----
-
-# docs-ingest
-
-Use this skill when documents need to be classified and routed into the canonical Smart Docs hierarchy.
-
-## When to use
-
-- "Ingest the docs from the last run"
-- "Classify the files in smartdocs/docs/raw/"
-- "Route pending documents into the correct authority buckets"
-- "Process ingest cluster docs-ingest-cluster-001"
-- "Dry-run docs ingest to see what would move"
-
-## How to execute
-
-1. Read `chain.md` — step order, traversal rules, authority levels, canonical target doctrine.
-2. Read `.taskchain_artifacts/docs-ingest/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.
-
-## Hard rules — what docs-ingest may do
-
-- Read documents from `smartdocs/raw/`
-- Classify documents by content analysis and front-matter
-- Route documents to correct authority directories within `smartdocs/`
-- Write provenance records alongside placed files
-- Update Polaris map entries to link docs to code areas
-- Propose doctrine candidates (route to `doctrine/candidate/`; never promote to `doctrine/active/` without user approval)
-- Emit telemetry events
-
-## Drop zone rule
-
-**All newly generated documents must be placed in `smartdocs/raw/` first.**
-
-No document may be written directly to `specs/active/`, `doctrine/active/`, `architecture/`, or `decisions/`. Every document enters through `raw/` and is promoted only after classification and approval.
-
-## Hard rules — what docs-ingest must NOT do
-
-- Write new Smart Docs to root `docs/` — `smartdocs/` is the canonical target
-- Silently promote documents to `doctrine/active/`, `specs/active/`, `architecture/`, or `decisions/`
-- Mutate source files (`src/`, tests, config)
-- Call `npm run polaris -- loop continue` or `npm run polaris -- finalize`
-- Suppress detected conflicts
-
-**Docs-ingest routes and classifies. It does not implement or promote without explicit approval.**

package/dist/workspace/workspace/.polaris/skills/docs-ingest/chain.json

@@ -1,23 +0,0 @@
-{
-  "name": "docs-ingest-chain",
-  "steps": [
-    "01-orient-ingest",
-    "02-classify-batch",
-    "03-conflict-check",
-    "04-place-and-link",
-    "05-finalize-ingest"
-  ],
-  "terminal_steps": ["05-finalize-ingest"],
-  "scope": "docs-ingest-only",
-  "forbidden_actions": [
-    "src file mutations",
-    "polaris loop continue",
-    "polaris finalize",
-    "git push",
-    "pr creation",
-    "doctrine/active/ writes without user approval",
-    "architecture/ writes without user approval",
-    "decisions/ writes without user approval",
-    "root docs/ writes for new Smart Docs"
-  ]
-}

package/dist/workspace/workspace/.polaris/skills/docs-ingest/chain.md

@@ -1,149 +0,0 @@
----
-name: docs-ingest-chain
-description: Route map for docs-ingest — step order, stop conditions, authority levels, canonical target doctrine, and artifact requirements.
----
-
-# docs-ingest chain
-
-## Authority
-
-**Polaris runtime state is authoritative. Chat reasoning is not authoritative.**
-
-Query runtime state before acting. Do not infer ingest scope or prior progress from conversation context.
-
-## CLI
-
-Always use the repo-local Polaris CLI:
-
-```
-npm run polaris -- docs ingest [--file <path>] [--batch <cluster-id>] [--dry-run]
-```
-
-Drop zone: `smartdocs/raw/` — this is the single ingest entry point.
-
-Never assume a globally linked `polaris` command exists.
-
-## Canonical Smart Docs target
-
-`smartdocs/` is the authoritative Smart Docs ingest target. There is one drop zone: `smartdocs/raw/`.
-
-- Root `docs/` is legacy/non-canonical — do not write new Smart Docs there.
-- There are no sub-raw folders (`specs/raw/`, `doctrine/raw/`, `audits/raw/` do not exist). All drops land in `smartdocs/raw/` and are routed from there.
-
-**Architectural intent:** Smart Docs exist to reduce repo-understanding token burn. Agents should move from:
-
-```
-read many files → infer architecture
-```
-
-to:
-
-```
-read Smart Docs router → read local POLARIS.md → open only necessary files
-```
-
-Smart Docs function as architectural compression, routing context, local subsystem summaries, and implementation guidance boundaries — without replacing canonical source files.
-
-## Step traversal order
-
-```text
-01-orient-ingest     ← generate run_id, emit telemetry, load batch, confirm canonical target
-02-classify-batch    ← content analysis + front-matter, assign classification per file
-03-conflict-check    ← compare against doctrine/active/ and specs/active/; halt on contradiction
-04-place-and-link    ← move files to authority buckets, write provenance, update map
-05-finalize-ingest   ← emit completion telemetry, update state, report placement summary
-```
-
-## Stop conditions
-
-**Any step:**
-- Conflict directly contradicts active doctrine → halt, report, require user resolution
-- High-authority placement attempted (`doctrine/active/`, `architecture/`, `decisions/`) without explicit approval → halt and surface for review
-- `smartdocs/` not found → halt, report missing canonical target
-- `run-start` telemetry write fails → halt
-
-**Step 03 (conflict check):**
-- Direct doctrine contradiction → halt with conflict report
-- Overlapping spec scope → flag as candidate supersede; continue with warning
-
-## Authority levels
-
-| Area | Authority | Who may write | Promotion path |
-|---|---|---|---|
-| `smartdocs/raw/` | none | any agent freely | `polaris doctrine draft` → `doctrine/candidate/` or `polaris doctrine spec-promote` → `specs/active/` |
-| `smartdocs/runtime/` | low | polaris-run, polaris-finalize | no promotion; informational only |
-| `smartdocs/specs/active/` | medium | `polaris doctrine spec-promote --approve` only | moved to `implemented/` or `superseded/` |
-| `smartdocs/doctrine/candidate/` | low | docs ingest + `polaris doctrine draft` | `polaris doctrine promote` (user-approved) |
-| `smartdocs/doctrine/active/` | high | `polaris doctrine promote` (user-approved) | `polaris doctrine deprecate` (user-approved) |
-| `smartdocs/architecture/` | high | user-approved only | explicit ADR process |
-| `smartdocs/decisions/` | high | user-approved only | explicit ADR process |
-
-## Run ID format
-
-Format: `docs-ingest-<slug>-<date>-<seq>`
-- `<slug>`: 2–4 lowercase hyphenated words from the ingest context. No issue IDs.
-- `<date>`: `YYYY-MM-DD`
-- `<seq>`: zero-padded sequential number per day (`001`, `002`, …)
-
-Example: `docs-ingest-compact-contracts-2026-05-26-001`
-
-## Telemetry
-
-Telemetry file: `.taskchain_artifacts/docs-ingest/runs/<run-id>/telemetry.jsonl` (append-only).
-
-| Event | Trigger |
-|---|---|
-| `run-start` | Begin processing |
-| `step-complete` | End of every step |
-| `docs-ingest-classified` | Each file classified |
-| `docs-ingest-conflict-detected` | Conflict found against active doctrine or spec |
-| `doctrine-candidate-proposed` | Doc routed to `doctrine/candidate/` |
-| `docs-ingest-stale-assumption` | Stale assumption annotated in front-matter |
-| `docs-ingest-complete` | Batch done |
-
-Required fields on every event: `event`, `run_id`, `timestamp`. Add `file` where applicable.
-
-## Context budget
-
-One ingest cluster per session. Default batch: 10 files. Configurable:
-
-```json
-{ "docs": { "ingestBatchSize": 10 } }
-```
-
-Stop after completing one cluster. Bootstrap packet guidance directs the next session to the next pending cluster.
-
-## Artifact authority
-
-`.taskchain_artifacts/docs-ingest/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.
-
-## Linked-skill invocation boundaries
-
-| Skill | Allowed steps | Condition |
-|---|---|---|
-| repo-analysis | 01, 02 | targeted lookup only; for code-area linking |
-
-## Execution reporting
-
-After each completed step, emit a checkpoint:
-
-```text
-**[step-name]** done | blocked | needs-input
-Changed: <files moved / provenance records written / map entries updated> or none
-Validated: <conflict checks / authority checks passed> or none
-Blockers: none | <explicit blocker>
-```
-
-### Never compressed
-
-Always write in full:
-- Conflict reports and resolution requirements
-
-- Doctrine candidate proposals
-- Stale-assumption annotations
-- Authority violation warnings
-- Final placement summary

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

@@ -1,85 +0,0 @@
----
-name: docs-ingest-step-01-orient-ingest
-description: Generate run_id, emit run-start telemetry, confirm provider status, load batch file list, and confirm canonical ingest target.
----
-
-# Step 01 — Orient ingest
-
-## Purpose
-
-Establish bounded ingest context before touching any files. Confirm what to process, confirm the canonical target exists, and confirm provider status.
-
-## Scope declarations
-
-```yaml
-allowed_files:
-  - .polaris/skills/docs-ingest/SKILL.md
-  - .polaris/skills/docs-ingest/chain.md
-  - .taskchain_artifacts/docs-ingest/current-state.json
-  - .polaris/docs-ingest/<cluster-id>.json
-  - polaris.config.json
-  - .polaris/map/index.json
-allowed_routes:
-  - CLAUDE.md
-  - smartdocs/specs/active/docs-authority-model.md
-  - .polaris/skills/docs-ingest/chain.md
-allowed_skills:
-  - repo-analysis
-expected_evidence:
-  - run_id generated
-  - run-start telemetry emitted
-  - batch file list loaded
-  - smartdocs/ confirmed present
-  - canonical target doctrine stated
-stop_rules:
-  - run-start telemetry write fails
-  - smartdocs/ not found
-  - batch cluster file missing or empty
-  - no pending clusters and no --file/--batch flags
-```
-
-## Actions
-
-0. **Generate `run_id`**:
-   - Fresh runs: `docs-ingest-<slug>-<date>-<seq>` (see `chain.md` for format rules).
-   - Resumed runs: generate new `run_id` first, emit run-start telemetry immediately (with `prior_run_id: null`), then read `current-state.json` to retrieve prior `run_id` for state continuity.
-
-1. **Emit `run-start` telemetry** — first I/O action, before any file access:
-   ```bash
-   mkdir -p .taskchain_artifacts/docs-ingest/runs/<run-id>
-   echo '{"event":"run-start","run_id":"<run-id>","prior_run_id":"<prior or null>","timestamp":"<ISO>"}' \
-     >> .taskchain_artifacts/docs-ingest/runs/<run-id>/telemetry.jsonl
-   ```
-   If this write fails: halt. Do not continue. For resumed runs, the `prior_run_id` is obtained after this emit by reading `current-state.json`.
-
-2. **Determine ingest source**:
-   - `--file <path>`: single file mode. Treat as a batch of one.
-   - `--batch <cluster-id>`: read `.polaris/docs-ingest/<cluster-id>.json` for file list.
-   - No flags: read `current-state.json` for the next pending cluster ID. If none: halt with "no pending ingest clusters — use --file or --batch, or register clusters first."
-
-3. **Confirm canonical target** — verify `smartdocs/` exists in the repo root.
-   - If not found: halt and report. Do not attempt to create it.
-   - Assert doctrine: `smartdocs/` is the only valid ingest target. Root `docs/` is legacy. New Smart Docs must not be placed there.
-   - Drop zone is `smartdocs/raw/` — the single ingest entry point. There are no sub-raw folders.
-   - If any source file already lives in `smartdocs/raw/`: reclassification only — no file move needed in step 04.
-
-4. **Load Polaris map** — read `.polaris/map/index.json` for code-area linking in step 04. If absent, note and proceed (map linking will be skipped in step 04).
-
-5. **Restate working context** in under 8 bullets:
-   - `run_id` and fresh/resumed
-   - Ingest mode (`--file` / `--batch` / pending-cluster)
-   - File list to process
-   - Canonical target confirmed: `smartdocs/`
-   - Provider status
-
-## Artifact update
-
-Update `.taskchain_artifacts/docs-ingest/current-state.json` (artifact path unchanged — skill identity is `docs-ingest`):
-- `run_id`, `status: orienting`, `current_step_id: 01-orient-ingest`
-- `files_to_process: [...]`, `updated_at: <timestamp>`
-
-Emit `step-complete` for `01-orient-ingest` to telemetry JSONL.
-
-## Next step
-
-02-classify-batch