@lsctech/polaris 0.3.21 → 0.3.23

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/01-load-cluster-context.md

@@ -1,78 +0,0 @@
----
-name: closeout-librarian-step-01
-description: Read packet, load cluster evidence, and build the work inventory for this reconciliation session.
----
-
-# Step 01 — Load Cluster Context
-
-## Purpose
-
-Build a complete picture of what the cluster accomplished. This is the foundation for all
-subsequent reconciliation steps. Nothing is written in this step.
-
-## Actions
-
-### 1.1 Read and Validate Packet
-
-Read the packet from the path provided in the dispatch prompt.
-
-Validate required fields:
-- `role` must be `"closeout-librarian"`
-- `run_id`, `dispatch_id`, `cluster_id` must be present and non-empty
-- `completed_children` must be a non-empty array
-- `result_path` must be present
-- `allowed_write_paths` must be present
-
-If validation fails: write a minimal failure result to `result_path` and terminate.
-
-### 1.2 Load Child Summaries
-
-For each entry in `packet.child_summaries`:
-1. Read the compact-return result at `child_summary.compact_return_path` (if present)
-2. Read the cognition note at `child_summary.cognition_note_path` (if present)
-3. Note `child_summary.changed_files` — the primary file inventory for this cluster
-
-Build a combined `all_changed_files` list (deduplicated) across all children.
-
-### 1.3 Load Folder Cognition Context
-
-For each entry in `packet.polaris_md_paths`:
-1. Read `polaris_md` (current POLARIS.md for this folder)
-2. Read `summary_md` (current SUMMARY.md, if path provided and file exists)
-3. Read `cognition_index` (archive index, if path provided and file exists)
-
-Note which folders have pending cognition notes (from `packet.cognition_notes`).
-
-### 1.4 Build Work Inventory
-
-Produce an internal inventory (not written to disk):
-
-```yaml
-work_inventory:
-  cluster_id: <from packet>
-  completed_children: [<ids>]
-  all_changed_files: [<deduplicated list>]
-  affected_folders: [<from packet.affected_folders>]
-  pending_cognition_notes: [<paths>]
-  docs_candidate_for_ingestion: [<from packet.smartdocs_raw_paths>]
-  polaris_md_files: { <folder>: <current content> }
-  summary_md_files: { <folder>: <current content or null> }
-```
-
-### 1.5 Load Run Report
-
-Read the run report at `packet.run_report_path` (if present). This provides a structured
-summary of what work was done.
-
-### 1.6 Emit Telemetry
-
-Emit `librarian-start` event (if telemetry path provided).
-
-## Completion Criteria
-
-- Packet validated
-- All available child summaries loaded
-- All available folder cognition loaded
-- Work inventory built
-
-Proceed to step 02.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/02-drift-reconciliation.md

@@ -1,157 +0,0 @@
----
-name: closeout-librarian-step-02
-description: Run formal drift reconciliation checklist to detect and record repository memory drift.
----
-
-# Step 02 — Drift Reconciliation
-
-## Purpose
-
-Implementation complete does not equal run complete. After every completed run, the Librarian
-must perform a formal drift reconciliation to ensure repository memory accurately reflects
-the current state of the route.
-
-This step detects and records drift observations. It does not resolve drift inline —
-resolution is a separate task if needed.
-
-## Drift Observation Types
-
-The following drift observation types are recognized:
-
-| Type | Description |
-|---|---|
-| `summary_outdated` | SUMMARY.md no longer describes current reality |
-| `canon_mismatch` | POLARIS.md does not match actual route structure or behavior |
-| `route_guidance_outdated` | Worker guidance or constraints in POLARIS.md are stale |
-| `missing_documentation` | Required documentation is absent for changed code |
-| `invalid_reference` | Links or canonical references point to non-existent or moved content |
-
-## Checklist
-
-Run this checklist in order. For each item, assess whether drift exists and record observations.
-
-### 2.1 Review Worker Results
-
-Review the work inventory from step 01:
-
-1. Examine `work_inventory.all_changed_files` — what code actually changed
-2. Review child summaries for behavioral changes, dependency changes, or architectural shifts
-3. Compare actual changes against existing POLARIS.md and SUMMARY.md descriptions
-
-**Questions:**
-- Did behavior change in a way not reflected in POLARIS.md?
-- Did dependencies change (added, removed, updated)?
-- Did architecture or responsibilities shift?
-- Are there new capabilities not documented?
-
-**If drift detected:** Record observation type (`canon_mismatch`, `route_guidance_outdated`, or `missing_documentation`).
-
-### 2.2 Review Medic Results (if applicable)
-
-If Medic ran in this cluster:
-
-1. Read all Medic charts created in this run (from `packet.medic_chart_paths`)
-2. Review drift observations recorded in chart metadata (`drift_observations` field)
-3. Note any reusable knowledge revealed by the charts
-
-**Questions:**
-- Did Medic detect drift not visible from worker results alone?
-- Did a chart reveal a pattern that should be captured in route cognition?
-- Are there chart relationships that indicate recurring issues?
-
-**If drift detected:** Medic already recorded observations in the chart. Librarian must address
-these in subsequent reconciliation steps (03–04).
-
-**If Medic did not run:** Skip this section.
-
-### 2.3 Review POLARIS.md Accuracy
-
-For each affected folder in `work_inventory.affected_folders`:
-
-1. Read the current POLARIS.md content
-2. Compare against the actual state of the folder after cluster changes
-3. Verify: route purpose, responsibilities, architecture, constraints, guidance
-
-**Questions:**
-- Does POLARIS.md still describe the route accurately?
-- Are there stale statements about removed capabilities?
-- Are new capabilities or constraints missing?
-- Is the architecture description current?
-
-**If drift detected:** Record observation type (`canon_mismatch` or `route_guidance_outdated`).
-
-### 2.4 Review SUMMARY.md Currency
-
-For each affected folder with a SUMMARY.md:
-
-1. Read the current SUMMARY.md content
-2. Verify the Current State and Route Health sections reflect reality
-3. Check if Recent Treatments needs updating
-
-**Questions:**
-- Does SUMMARY.md still describe the current state?
-- Is the Route Health status accurate?
-- Are there known issues or improvement opportunities not captured?
-
-**If drift detected:** Record observation type (`summary_outdated`).
-
-### 2.5 Review Canonical References
-
-For each SUMMARY.md with a `canonical_docs` block:
-
-1. Verify each referenced path exists
-2. Confirm references are still relevant to the route
-3. Check for missing important references
-
-**Questions:**
-- Do any canonical references point to non-existent files?
-- Are there important docs missing from the canonical list?
-- Are references still navigation-relevant or have they become obsolete?
-
-**If drift detected:** Record observation type (`invalid_reference` or `missing_documentation`).
-
-### 2.6 Chart Linking Requirement (when Medic ran)
-
-If Medic ran in this cluster:
-
-1. Identify all charts created in this run (from `packet.medic_chart_paths`)
-2. For each chart, create a concise entry in the affected folder's SUMMARY.md under `## Recent Treatments`
-3. Format: `CHART-YYYY-MM-DD-NNN — <brief one-line summary of treatment>`
-
-**This is a required action when Medic ran.**
-
-Example:
-```markdown
-## Recent Treatments
-
-CHART-2026-06-04-001 — Worker result validation failure repaired and verified.
-CHART-2026-06-05-003 — Chart schema validation failure fixed and regression test added.
-```
-
-**If Medic did not run:** Skip this section.
-
-## Output
-
-Build the following internal structure for use in subsequent steps:
-
-```yaml
-drift_reconciliation:
-  medic_ran: <true|false>
-  charts_created: [<chart_ids>]
-  drift_observations: [
-    { type: "<observation_type>", target: "<file or description>", severity: "<low|medium|high>" },
-    ...
-  ]
-  chart_links_required: <true if Medic ran>
-  charts_linked: [<chart_ids linked in SUMMARY.md>]
-```
-
-This structure is passed to steps 03–04 for reconciliation action.
-
-## Completion Criteria
-
-- All checklist items completed
-- Drift observations recorded (if any)
-- Chart linking requirement acknowledged (if Medic ran)
-
-Proceed to step 03.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/03-reconcile-polaris-md.md

@@ -1,93 +0,0 @@
----
-name: closeout-librarian-step-03
-description: Update affected POLARIS.md files to accurately reflect the current state of each folder after the completed cluster.
----
-
-# Step 03 — Reconcile POLARIS.md
-
-## Purpose
-
-Each affected folder's POLARIS.md must accurately describe the current reality of that folder.
-This step performs actual reconciliation — not append-only notes.
-
-## What POLARIS.md Represents
-
-A folder's POLARIS.md is a living operational guide. It should describe:
-- Current capabilities (what this folder does now)
-- Current architecture (how it is structured now)
-- Current responsibilities (what owns what)
-- Current constraints (what is forbidden)
-- Current folder state (what is present and what is not)
-
-POLARIS.md is NOT a changelog. Do not append "added in cluster POL-123". Replace stale
-statements with current truth.
-
-## When to Update
-
-Update a folder's POLARIS.md when ALL of the following are true:
-1. Files in that folder were changed by the completed cluster.
-2. The changes materially affect the folder's responsibilities, architecture, or constraints.
-3. The current POLARIS.md content is factually wrong or incomplete as a result.
-
-Do NOT update for: formatting fixes, test additions without behavior change,
-internal refactors that leave operational guidance still accurate.
-
-## When NOT to Update
-
-- The folder was not touched by any child in this cluster.
-- The changes are in sub-packages that have their own POLARIS.md.
-- The existing POLARIS.md correctly describes the outcome of the changes.
-
-## Actions
-
-For each folder in `work_inventory.affected_folders`:
-
-### 3.1 Assess the Impact
-
-1. Identify which files in this folder were changed (from `work_inventory.all_changed_files`).
-2. Read the current POLARIS.md content for this folder (from `work_inventory.polaris_md_files`).
-3. Read the cognition notes for this folder (from `work_inventory.pending_cognition_notes`).
-4. Cross-reference with child summaries and run report to understand what changed.
-
-### 3.2 Determine Required Changes
-
-For each stale or missing statement in POLARIS.md:
-- If a capability was added: add it to the appropriate section.
-- If a capability was changed: update the statement in place.
-- If a capability was removed: remove the statement.
-- If a constraint was added: add to constraints section.
-- If a constraint was lifted: remove it.
-- If architecture changed: update the architecture description.
-
-**Reconciliation principle:** The resulting POLARIS.md must describe the folder as it
-exists AFTER the cluster completed. Read the code if necessary to confirm the current state.
-
-### 3.3 Confidence Threshold
-
-Assess confidence (0.0–1.0) in the proposed update:
-- `≥ 0.85`: Apply the update.
-- `0.70–0.84`: Apply with a note in the result that confidence was moderate.
-- `< 0.70`: Skip the update for this folder, record as a blocker in the result.
-
-Low confidence triggers: ambiguous changed_files, contradictory notes, minimal diff context.
-
-### 3.4 Write
-
-If the assessment confirms an update is needed and confidence is sufficient:
-1. Verify the POLARIS.md path is in `packet.allowed_write_paths`.
-2. Write the full updated content (not a patch — full file replacement).
-3. Record in the running `polaris_md_updates` list for the result.
-
-If the path is in `packet.prohibited_write_paths`, record as a blocker and skip.
-
-## Output
-
-Running list for step 09:
-```yaml
-polaris_md_updates: [
-  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
-  ...
-]
-```
-
-Proceed to step 04.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/04-reconcile-summary-md.md

@@ -1,106 +0,0 @@
----
-name: closeout-librarian-step-04
-description: Refresh SUMMARY.md to reflect current project state after the completed cluster.
----
-
-# Step 04 — Reconcile SUMMARY.md
-
-## Purpose
-
-SUMMARY.md files serve as continuation artifacts, project snapshots, and handoff documents.
-A future session loading SUMMARY.md must be able to continue work immediately without
-replaying history.
-
-The goal is that SUMMARY.md reflects the current state of the project AFTER this cluster,
-not a log of what happened.
-
-## What SUMMARY.md Represents
-
-- Current understanding of the system (what is true now)
-- Canonical references to active specs and doctrine
-- Architecture snapshots that are no longer in flux
-- Handoff context for continuation sessions
-
-SUMMARY.md is NOT:
-- A changelog
-- A history of execution events
-- A list of completed issues
-
-## When to Update
-
-Update a folder's SUMMARY.md when:
-- Linked specs or doctrine changed significantly (new authoritative documents promoted)
-- Canon relationships changed (new spec supersedes old; architecture changed)
-- Architecture meaning changed in ways not captured by POLARIS.md
-- Current understanding described in SUMMARY.md is now stale or contradicted by completed work
-
-Do NOT update for: ephemeral execution events, minor bug fixes, test additions without
-behavior change, changes that do not affect the reader's understanding.
-
-## Reconciliation Principles
-
-### Remove Stale Information
-
-Identify statements in SUMMARY.md that are contradicted by the completed work.
-Remove or replace them. Do not preserve stale content by appending "as of cluster X".
-
-### Replace Superseded Information
-
-When a spec or decision that SUMMARY.md references has been superseded, update the reference
-to point to the current authority.
-
-### Preserve Current Understanding
-
-Retain content that accurately describes current reality. Preservation is not append — it is
-selection of what remains true.
-
-### Root-level SUMMARY.md
-
-The root-level SUMMARY.md (if in `packet.affected_folders`) must reflect the overall project
-state after this cluster. This is the primary continuation artifact for the whole project.
-Give it higher priority than folder-level SUMMARY.md files.
-
-## Actions
-
-For each folder in `work_inventory.affected_folders` that has a SUMMARY.md:
-
-### 4.1 Assess Staleness
-
-1. Read the current SUMMARY.md (from `work_inventory.summary_md_files`).
-2. Cross-reference with completed work: changed specs, new capabilities, new constraints.
-3. Identify sections that are stale, contradicted, or superseded.
-4. Identify new information that should be captured (architecture snapshots, spec promotions).
-
-### 4.2 Refresh
-
-Produce the updated SUMMARY.md content:
-1. Remove sections that are no longer accurate.
-2. Update references to specs and doctrine that changed.
-3. Add brief architecture notes for significant new capabilities (if they help future sessions).
-4. Ensure the document still reads as a coherent current-state snapshot, not a list of events.
-
-**Constraint:** SUMMARY.md updates must not exceed `packet.constraints.max_summary_addition_lines`
-net new lines per folder (default: 50 lines). "Net new" means final line count minus original line count. Replacements (same or fewer lines) do not count toward this limit.
-
-### 4.3 Write
-
-1. Verify the SUMMARY.md path is in `packet.allowed_write_paths`.
-   If not allowed, skip this file and record in `summary_md_updates` with `action: "path_not_allowed"`.
-2. Write the full updated content.
-3. Record in the running `summary_md_updates` list.
-
-If no update is needed, record no-change for this folder using `action: "no_change"`.
-
-## Output
-
-Running list for step 09:
-```yaml
-summary_md_updates: [
-  { file: "<path>", action: "update", change_summary: "<≤50 words>" },
-  { file: "<path>", action: "no_change" },
-  { file: "<path>", action: "path_not_allowed" },
-  ...
-]
-```
-
-Proceed to step 05.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/05-doc-ingestion.md

@@ -1,114 +0,0 @@
----
-name: closeout-librarian-step-05
-description: Inspect documentation associated with completed work. Ingest, promote, archive, or skip.
----
-
-# Step 05 — Documentation Ingestion
-
-## Purpose
-
-The Librarian inspects documentation associated with the completed cluster and determines
-what action each document requires. Implementation work frequently produces accompanying
-documentation that has not yet been formally ingested into the SmartDocs authority hierarchy.
-
-## Document Sources to Inspect
-
-1. **`packet.smartdocs_raw_paths`** — raw documents in `smartdocs/raw/` that may be
-   related to completed work
-2. **Documents referenced in child summaries** — specs, analyses, or plans linked by children
-3. **Documents referenced in run report** — related planning/analysis docs
-4. **Cognition notes** (`packet.cognition_notes`) — worker notes from this cluster
-
-## Ingestion Decision Matrix
-
-For each candidate document:
-
-| Condition | Action |
-|---|---|
-| Document is a spec for implemented behavior, not yet in `specs/active/` | Ingest → `smartdocs/specs/active/` |
-| Document is a one-time analysis, no ongoing authority | Archive → `smartdocs/raw/` (keep in place, mark as analyzed) |
-| Document is a postmortem or lessons-learned | Keep raw, record in result |
-| Document is obsolete (superseded by newer spec) | Archive or deprecate |
-| Document is doctrine candidate (stable, widely applicable) | Ingest → `smartdocs/doctrine/candidate/` (NOT `doctrine/active/` — requires operator) |
-| Document is unrelated to completed work | Skip |
-| Document already promoted (in `specs/active/` or `doctrine/active/`) | Skip |
-
-## Promotion Boundaries
-
-**The Closeout Librarian may promote to:**
-- `smartdocs/specs/active/` (specifications for implemented behavior)
-- `smartdocs/` classification tiers (raw → candidate)
-
-**The Closeout Librarian may NOT promote to:**
-- `smartdocs/doctrine/active/` — requires explicit operator approval
-- `smartdocs/architecture/` — requires explicit operator approval
-
-When a document warrants `doctrine/active` promotion, record it in the result as a
-promotion recommendation for operator review.
-
-## Frontmatter Requirements
-
-When ingesting a document into `smartdocs/specs/active/`:
-1. Ensure the document has valid YAML frontmatter.
-2. Required fields: `kind`, `status`, `source`, `created`.
-3. Add or update: `status: active`, `created: <ISO date>`.
-4. Do not modify the document body.
-
-When creating a provenance file (`.provenance.json`):
-```json
-{
-  "promoted_from": "<source path>",
-  "promoted_at": "<ISO date>",
-  "promoted_by": "closeout-librarian",
-  "run_id": "<packet.run_id>",
-  "cluster_id": "<packet.cluster_id>"
-}
-```
-
-## Cognition Note Archival
-
-After POLARIS.md, drift reconciliation, and SUMMARY.md reconciliation is complete, move all resolved pending
-cognition notes from `packet.cognition_notes` to archive:
-- Source: `.polaris/cognition/pending/<folder-slug>/<file>`
-- Destination: `.polaris/cognition/archive/<folder-slug>/<file>`
-- Update `cognition-index.json` for the folder
-
-## Actions
-
-### 5.1 Enumerate Candidates
-
-Build a list of candidate documents from all sources (raw paths, child summaries, run report).
-Deduplicate. Exclude already-promoted documents.
-
-### 5.2 Classify Each Candidate
-
-Apply the decision matrix above. Assign one of: `ingest`, `promote`, `archive`, `skip`.
-
-### 5.3 Execute Ingestion
-
-For each document classified as `ingest` or `promote`:
-1. Verify target path is in `packet.allowed_write_paths`.
-2. Copy/move to target location.
-3. Update or add frontmatter.
-4. Create provenance file.
-5. Record in `docs_ingested` list.
-
-For each document classified as `archive`:
-1. No file move required (raw docs stay in place).
-2. Record in `docs_archived` list with reason.
-
-### 5.4 Archive Cognition Notes
-
-Move all pending cognition notes in `packet.cognition_notes` to archive.
-Update `cognition-index.json` for each affected folder.
-
-## Output
-
-Running lists for step 09:
-```yaml
-docs_ingested: [{ source_path, target_path, action: "ingest"|"promote", reason }]
-docs_archived: [{ source_path, target_path: null, action: "archive", reason }]
-cognition_archived: [{ note_path, archive_path }]
-```
-
-Proceed to step 06.

package/dist/workspace/workspace/.polaris/skills/closeout-librarian/steps/06-link-validation.md

@@ -1,128 +0,0 @@
----
-name: closeout-librarian-step-06
-description: Validate markdown links, YAML references, and cognition references. Repair where possible.
----
-
-# Step 06 — Link Validation
-
-## Purpose
-
-Documentation changes and promotions in steps 03–05 may create or expose broken links.
-This step validates references across affected documentation and repairs them where possible.
-
-## Scope of Validation
-
-Validate links only in files that were written or affected during this session:
-- POLARIS.md files updated in step 03
-- SUMMARY.md files updated in step 04
-- Documents ingested in step 05
-- Provenance files created in step 05
-
-Do NOT validate the entire repository. Scope is limited to files touched by this session.
-
-## Link Types to Validate
-
-### Markdown Links
-
-```markdown
-[text](path)
-[text](path#anchor)
-```
-
-Validate that the target path exists relative to the document location.
-
-### Wiki-style Links
-
-```markdown
-[[document-name]]
-[[folder/document]]
-```
-
-Validate that the referenced document exists in `smartdocs/`.
-
-### YAML Frontmatter References
-
-```yaml
-depends_on:
-  - foreman-worker-architecture.md
-supersedes: old-spec.md
-related:
-  - worker-session-contract.md
-```
-
-Validate that referenced files exist in their expected locations.
-
-### Promotion References
-
-When a document was promoted from `smartdocs/raw/` to `smartdocs/specs/active/`, any
-existing references to the raw location (in files written this session) should be updated
-to point to the new canonical location.
-
-### Cognition References
-
-In SUMMARY.md files, references to cognition notes or archive entries should resolve
-correctly after archival in step 05.
-
-## Repair Heuristics
-
-### Broken Relative Path
-
-If a relative path is wrong but the target file exists at a different relative path:
-1. Compute the correct relative path.
-2. Update the link.
-3. Record as repaired.
-
-### Promoted Document Reference
-
-If a link points to `smartdocs/raw/<file>` and the file was promoted to
-`smartdocs/specs/active/<file>` in step 05:
-1. Update the link to the new canonical path.
-2. Record as repaired.
-
-### Unrepairable Links
-
-A link is unrepairable when:
-- The target file does not exist anywhere in the repository.
-- The link is ambiguous (multiple matching targets).
-- The link is to an external URL (do not modify external links).
-
-Record unrepairable links in the result and continue. Do not fail the session over
-unrepairable links.
-
-## Actions
-
-### 6.1 Collect Links
-
-For each file written in steps 03–05, extract all link references (markdown, YAML, wiki).
-
-### 6.2 Validate Each Link
-
-Check whether the target exists. Classify as: valid, broken-repairable, broken-unrepairable,
-external (skip).
-
-### 6.3 Repair
-
-For each broken-repairable link:
-1. Verify the source file is in `packet.allowed_write_paths`.
-2. Apply the repair (update the link in the file).
-3. Record in `links_repaired`.
-
-### 6.4 Record Results
-
-Build the link validation report for step 09.
-
-## Output
-
-```yaml
-link_validation_report:
-  total_checked: <n>
-  valid: <n>
-  broken: <n>
-  repaired: <n>
-  unrepairable: ["<path>: <description>", ...]
-```
-
-Unrepairable links are added to the session blockers list with `resolution_required: false`
-(informational only — they do not block the Librarian commit).
-
-Proceed to step 07.