@lsctech/polaris 0.1.0 → 0.1.3

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

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

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

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

@@ -0,0 +1,23 @@
+{
+  "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

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

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

package/dist/workspace/workspace/.polaris/skills/docs-ingest/steps/02-classify-batch.md

@@ -0,0 +1,87 @@
+---
+name: docs-ingest-step-02-classify-batch
+description: Read each file in the batch, inspect front-matter and content signals, and assign exactly one classification from the docs-authority-model.
+---
+
+# Step 02 — Classify batch
+
+## Purpose
+
+Assign each file to exactly one classification. Classification determines target directory, authority level, and whether user approval is required before placement.
+
+## Classification table
+
+| Class | Target path | Authority | Approval required |
+|---|---|---|---|
+| `runtime-summary` | `smartdocs/runtime/summaries/` | low | no |
+| `run-report` | `smartdocs/runtime/run-reports/` | low | no |
+| `spec-raw` | `smartdocs/raw/` | none | no |
+| `spec-active` | `smartdocs/specs/active/` | medium | yes |
+| `audit-finding` | `smartdocs/audits/findings/` | medium | no |
+| `doctrine-candidate` | `smartdocs/doctrine/candidate/` | low | no |
+| `architecture` | `smartdocs/architecture/` | high | yes |
+| `decision` | `smartdocs/decisions/` | high | yes |
+| `deprecated-noise` | `smartdocs/runtime/generated/` | low | no |
+
+## Classification process (per file)
+
+1. Read the document.
+2. Check for explicit Polaris front-matter (`status`, `authority`, `issue`, `classification`). If present and unambiguous: assign classification with **confidence: high**.
+3. Otherwise infer from content signals and assign a confidence level:
+   - Contains Polaris architectural assertions or "how things should work" → `doctrine-candidate`
+   - Structured spec with headings (Spec ID, Status, Purpose, etc.) → `spec-raw`
+   - Active spec governing in-flight work referencing an open issue → `spec-active` (flag for approval)
+   - Run output, telemetry summaries, session notes → `runtime-summary`
+   - Structured run output with metrics → `run-report`
+   - Contains `FINDING:` markers or audit-style analysis → `audit-finding`
+   - ADR-style decision record → `decision` (flag for approval)
+   - Architectural diagrams or structural design context → `architecture` (flag for approval)
+   - Low-signal, transient, or auto-generated content → `deprecated-noise`
+4. Assign a confidence level per file:
+   - **high**: explicit front-matter present, or content matches exactly one signal with no ambiguity
+   - **low**: multiple signals match, or content is sparse/unclear
+5. Routing by confidence:
+   - **high confidence** → auto-place to the classified target in step 04 (no pause, no user input required — except `spec-active`, `architecture`, `decision` which always require approval regardless of confidence)
+   - **low confidence** → route to `smartdocs/raw/` as holding area; record reason in telemetry
+6. When confidence cannot be determined: default to **low** and route to `smartdocs/raw/`.
+
+## Approval-required classifications
+
+For `spec-active`, `architecture`, and `decision`: do not route automatically regardless of confidence. Surface for user confirmation before step 04 proceeds for those files. Emit:
+
+```text
+**needs-input**: <n> file(s) classified as approval-required (<classes>).
+Proposed placements:
+  <file> → <target> [confidence: high|low]
+Confirm placement before step 04 proceeds for these files.
+```
+
+High-confidence, non-approval-required files proceed to step 03 immediately without pause.
+Low-confidence files are routed to `smartdocs/raw/` and noted in the step 05 summary.
+
+## Scope declarations
+
+```yaml
+allowed_files:
+  - source files in the batch (read only)
+  - smartdocs/specs/active/docs-authority-model.md (reference)
+expected_evidence:
+  - every file in batch assigned a classification and confidence level
+  - approval-required files surfaced before step 04
+  - low-confidence files routed to smartdocs/raw/ with telemetry note
+  - high-confidence non-approval files proceed automatically
+stop_rules:
+  - file cannot be read
+```
+
+## Artifact update
+
+Update `current-state.json`:
+- `current_step_id: 02-classify-batch`
+- `classifications: { "<file>": { "class": "<class>", "target": "<path>", "confidence": "high|low", "approval_required": true|false, "auto_place": true|false } }`
+
+Emit `docs-ingest-classified` telemetry event per file.
+
+## Next step
+
+03-conflict-check