@c4a/context-cli 0.5.29-alpha.1

package/plugin/skills/align-finalize/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: align-finalize
+description: >
+  Third skill of `/context:align`. Reconciles `WORKSPACE_DIR/output/align.propose.yaml`
+  with the user's `WORKSPACE_DIR/output/align.user-decisions.yaml`, applies every pick
+  (ambiguous / orphan / accept-reject / addition / rename), re-validates
+  the tree against identity / establishment / tag / mount / layout rules,
+  and writes the final AlignRenderInput YAML. The CLI renders
+  `WORKSPACE_DIR/output/align.md` and binds raw mentions to `WORKSPACE_DIR/output/bind.yaml`.
+  Activates after the user has reviewed `align.propose.md` and written
+  their decisions file.
+tools:
+  - Read
+  - Bash
+---
+
+# align-finalize — apply user decisions, emit the final plan
+
+Reconcile propose YAML with user-decisions YAML, settle every
+ambiguity, and produce the final `AlignRenderInput`. The CLI does
+all rendering.
+
+`WORKSPACE_DIR` is provided by the caller from `context workspace locate --format json` (`ctxDir`). It is `.context/` in embedded layout and the repository root in root layout.
+
+## TL;DR — Non-negotiables
+
+- Inputs must both exist: `output/align.propose.yaml` (CLI render) + `output/align.user-decisions.yaml` (user pick), read through `context workspace read`. Missing → stop and say which one.
+- Output: final `AlignRenderInput` passed to `context align --finalize -`; add `--save-input` when the caller wants a durable scratch copy.
+- Respect user decisions literally; a demoted candidate does not appear in `nodes[]` even if you disagreed during propose.
+- `type` values are closed to `domain / entity / action / concept` (see [Node types](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#node-types)); reject anything else rather than silently mapping.
+- Domain hard rule: no Node sits inline under a Domain file; every child of a Domain is a standalone root (see [Layout rules](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#layout-rules)).
+- `planned_sections[]` must satisfy the [Section mount matrix](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-mount-matrix) for each Node's type.
+- Slugs reuse across loops for `existing` / `modified`; new slugs only for `new`; user rename decisions carry through verbatim.
+- Every edge endpoint references a slug in `nodes[]`; no dangling edges.
+- No cycles across `contains` + `refines`; user-decision-induced cycles reject with the cycle path.
+- User decisions are business-intent answers; map them back to the closed model yourself instead of asking follow-up questions with model terms.
+- Output language: user-facing prose and `decisions.notes` match the user's language; slug / tag / type / edge values stay English.
+
+<reference>
+
+## User-decisions shape
+
+```yaml
+decisions:
+  ambiguous:
+    - phrase: "..."
+      choice: A                         # A / B / other
+      custom: { ... }                    # optional for "other"
+  orphans:
+    - slug: "..."
+      choice: deprecate                  # deprecate | keep | modify | supersede
+      new_status: deprecated
+      valid_until: <date>
+      supersede_with: <slug>              # when choice=supersede
+  new_candidates:
+    - name: "..."
+      choice: accept                     # accept | reject | reclassify
+      reclassify: { type: ..., tags: [...] }
+      rename: <new-slug>                  # optional
+  additions:
+    - name: "..."
+      suggested_type: ...
+      suggested_tags: [...]
+```
+
+Missing sections = "no change from propose". Read tolerantly.
+
+## Action establishment recheck
+
+User decisions can drop an Action below its establishment bar (e.g.
+rejecting a sub-Action leaves the parent with a single Section
+intent). After applying all decisions, re-verify every `action` Node
+against [Node establishment thresholds](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#node-establishment-thresholds). Below bar → leave the Node in place (the user made the call) but flag the weakness in `decisions.notes`. The caller's next `context doctor` pass (run at the end of `/context:align`) surfaces the note via the output-align diagnostic group, giving the user a chance to reopen the decision on the next loop.
+
+## Alias carry-through
+
+For every `new` Node, carry over the aliases the raw called it by
+(derived from scan mentions) so the close-time glossary build picks
+them up. Without aliases, later retrieval misses language variants.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Load inputs
+
+Read `output/align.propose.yaml` and `output/align.user-decisions.yaml` in full with `context workspace read <path> --format text`. Build a `decisions` lookup keyed by slug / phrase / name. If either file is missing, stop and name it.
+
+### Step 2 — Apply `new_candidates` decisions
+
+For each propose `new` candidate:
+
+- `accept` → keep in the plan.
+- `reject` → drop from the plan; its mentions still show in `bind.yaml` as unbound raw.
+- `reclassify` → swap `type` + `tags`; re-check tags per the [Entity tag groups](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#entity-tag-groups) and concept gate rules.
+- `rename` → change `slug` / `title`; propagate to every edge + parent pointer.
+
+### Step 3 — Apply `ambiguous` decisions
+
+Pick the matching candidate per the user's `choice`; drop the others. `custom` branches go through Step 2's `reclassify` path.
+
+### Step 4 — Apply `orphans` decisions
+
+- `keep` → `status: existing`, no change.
+- `deprecate` → `status: orphan` + copy `new_status` / `valid_until`.
+- `modify` → `status: modified` + record intent in `decisions.notes`.
+- `supersede` → `status: orphan` on the old slug + add a new Node for the supersession target from `supersede_with`.
+
+### Step 5 — Apply `additions`
+
+For every user addition, run it through the same gates as propose ([establishment](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#node-establishment-thresholds), [tag rules](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#entity-tag-groups), [concept gate](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#concept-three-test-gate)). Gate failure → surface to the caller; the user needs to revise. Do not silently drop.
+
+### Step 6 — Fill and verify `planned_sections[]`
+
+Carry propose's hint when set; extend from raw evidence only with kinds that satisfy the [Section mount matrix](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-mount-matrix) for the Node's type. Drop mismatches and note them in `decisions.notes`.
+
+### Step 7 — Layout + cycle check
+
+- Confirm no Node carries a `contains_parent` that would require inline nesting under a Domain (see [Layout rules](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#layout-rules)).
+- Run a cycle check over `contains` + `refines`. Any cycle → reject with the offending path in the output; do not auto-break.
+
+### Step 8 — Write the final input
+
+Emit the confirmed `AlignRenderInput` shape (same shape as align-propose's output) for the caller to pass to `context align --finalize -` (or `context align --finalize - --save-input` when a durable scratch copy is needed). Return control to the caller.
+
+### Step 9 — Self-verify
+
+- [ ] Every `type` is one of the four closed values — if not, **Step 2/3/5**.
+- [ ] Every `entity` has ≥1 A/B tag — if not, **Step 2/3/5**.
+- [ ] Every `action` cleared the establishment bar OR carries a `decisions.notes` override — if not, **Step 2**.
+- [ ] Every `planned_sections[]` entry is legal for the Node type — if not, **Step 6**.
+- [ ] No Node sits inline under a Domain — if any, **Step 7**.
+- [ ] No cycles — if any, **Step 7**.
+- [ ] Every edge endpoint appears in `nodes[]` — if not, **Step 8**.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any, restart with `context workspace` / `context mdrive` commands.
+
+</procedures>

package/plugin/skills/align-propose/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: align-propose
+description: >
+  Second skill of `/context:align`. Reads the align-scan decisions file +
+  the existing `knowledge/` contains tree from `context mdrive query
+  --contains-tree --format json`, assembles a candidate Node tree, validates every candidate
+  against identity / establishment / tag / Edge rules, marks each node
+  new / existing / modified / orphan, and writes an AlignRenderInput
+  YAML. The CLI renders `WORKSPACE_DIR/output/align.propose.md` + `.yaml` for the user
+  to review. Activates when align-scan decisions are on disk and the
+  pipeline needs a reviewable tree before align-finalize.
+tools:
+  - Read
+  - Bash
+---
+
+# align-propose — assemble a reviewable Node tree
+
+Promote classified mentions into a contains-rooted tree with explicit
+Edges, applying the identity / establishment / tag rules. Output is
+pure YAML; the CLI does the rendering.
+
+`WORKSPACE_DIR` is provided by the caller from `context workspace locate --format json` (`ctxDir`). It is `.context/` in embedded layout and the repository root in root layout.
+
+## TL;DR — Non-negotiables
+
+- Input: `output/align.scan-decisions.json` read through `context workspace read` + the current contains tree from `context mdrive query --contains-tree --format json`.
+- Output: an `AlignRenderInput` passed to `context align --propose -`; add `--save-input` when the caller wants a durable scratch copy.
+- Every candidate carries a `status` (see [Status markers](#status-markers)); `new` is never the default.
+- Entity candidates pass [Entity tag groups](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#entity-tag-groups); re-route false Entities per [False-Entity smell](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#false-entity-smell).
+- Action candidates clear [Node establishment thresholds](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#node-establishment-thresholds); below-bar demote to Section suggestions.
+- Concept candidates pass the [Concept three-test gate](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#concept-three-test-gate); failures demote.
+- Edges come from the five logical types only (see [Edge types](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#edge-types)); `refers_to_nodes` is a Section field, not an Edge.
+- No `contains` edge from a Domain to a Node that would nest inline — Domain children are always standalone files (see [Layout rules](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#layout-rules)).
+- No cycles in `contains` + `refines`.
+- Slugs are kebab-case, ≤60 chars, stable across loops.
+- User review questions follow `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/user-question-contract.md`: ask for business intent, never storage mechanics.
+- Output language: user-facing prose and `decisions.notes` match the user's language; slugs / tag / type / edge values stay English.
+
+<reference>
+
+## Status markers
+
+| marker | When to use |
+|---|---|
+| `existing` | Exact slug / title match in workspace AND raw does not contradict the glossary entry |
+| `new` | No existing Node; raw material justifies creating it |
+| `modified` | Matches an existing Node AND raw adds information (new Sections incoming, or raw flips a decision) |
+| `orphan` | Existing Node whose raw footprint says sunset / deprecated / superseded; user decides deprecate / keep / supersede |
+
+## AlignRenderInput shape
+
+```yaml
+workspace: <workspace-name>
+nodes:
+  - slug: <kebab-case>
+    type: domain | entity | action | concept
+    tags: [...]
+    title: <human title>
+    sources: [<source-id>, ...]
+    aliases: [...]
+    summary: <optional one-liner>
+    status: new | existing | modified | orphan
+    contains_parent: <slug, optional>
+    planned_sections: [description, spec, warning]
+edges:
+  - type: contains | depends_on | realizes | refines | related_to
+    from: <slug>
+    to: <slug>
+    note: <optional>
+decisions:
+  notes: |
+    <brief rationale + demotions + unresolved questions>
+  ambiguous: [ ... carried from scan + discovered re-routes ... ]
+  orphans:   [ ... carried from scan ... ]
+```
+
+## User-review shape
+
+The CLI renders the proposal to `align.propose.md`. Shape your output
+so the caller can ask a small number of business-intent questions. The
+user should never need to know the internal Node / Section / Edge model.
+
+1. **Same thing or separate topic?** Pre-resolve with the identity tests.
+   Surface only hard cases in `decisions.ambiguous[]`.
+2. **Standalone lookup or parent detail?** Set the internal parent / demotion
+   fields yourself. Ask the user only when future retrieval behavior is unclear.
+3. **Business relationship?** Ask only when raw evidence leaves multiple
+   plausible meanings, such as alternatives vs dependency vs co-location.
+4. **Validity change?** Ask when old and new source documents conflict about
+   what readers should trust now.
+5. **Navigation-only duplication?** Do not ask. Repeated "Related links",
+   "References", and similar blocks are handled as structure unless they carry
+   new business prose.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Load inputs
+
+1. Read `output/align.scan-decisions.json` with `context workspace read output/align.scan-decisions.json --format text`.
+2. Run `context mdrive query --contains-tree --format json` and use the returned `nodes[]` + `edges[]` as the current workspace skeleton. `contains` edges encode both same-file heading children and cross-file `## Contains` links; do not rebuild the tree with Glob + Read.
+
+### Step 2 — Seat `existing_nodes`
+
+Copy every `existing` entry into `nodes[]` with its current parent pointer from the tree. Set `status: existing`, or `modified` if new mentions imply incoming Sections. Do not re-parent without explicit raw evidence.
+
+### Step 3 — Promote new candidates
+
+For each `new_candidates[]` from `output/align.scan-decisions.json`:
+
+1. Check [Node establishment thresholds](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#node-establishment-thresholds). Below bar → skip the Node; record a Section demotion in `decisions.notes`.
+2. For `entity`, verify tags per the data-model reference. Neither-group hits → re-route via [False-Entity smell](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#false-entity-smell) into `decisions.ambiguous[]`.
+3. For `concept`, run the [Concept three-test gate](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#concept-three-test-gate). Any ❌ → demote; do not emit.
+4. Pick `contains_parent` from the scan's `suggested_parent` or a matching existing Domain.
+5. Fill `planned_sections[]` only where raw clearly justifies kinds that fit the target type per the [Section mount matrix](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-mount-matrix).
+
+### Step 4 — Enumerate edges
+
+One `edges[]` entry per `contains` edge in the tree. Add `depends_on` / `realizes` / `refines` / `related_to` only where raw explicitly justifies the relationship AND both endpoints appear in `nodes[]`. Never emit `refers_to_nodes`-style edges. Run a cycle check over `contains` + `refines`; reject any cycle.
+
+### Step 5 — Carry ambiguous and orphans
+
+Copy `scan.ambiguous[]` into `decisions.ambiguous[]` plus any discoveries from Step 3 re-routes. Copy `scan.orphans[]` into `decisions.orphans[]`. Do not make deprecation calls yourself; the user decides in the next gate.
+
+### Step 6 — Write the proposal input
+
+Emit the [AlignRenderInput shape](#alignrenderinput-shape) as YAML for the caller to pass to `context align --propose -` (or `context align --propose - --save-input` when a durable scratch copy is needed). Return control to the caller; the caller renders `align.propose.md` + `.yaml`.
+
+### Step 7 — Self-verify
+
+- [ ] Every `entity` has ≥1 A/B tag — if not, **Step 3**.
+- [ ] Every `action` clears the establishment bar OR is demoted — if not, **Step 3**.
+- [ ] Every `concept` passes the three-test gate — if not, **Step 3**.
+- [ ] No cycles in `contains` + `refines` — if any, **Step 4**.
+- [ ] No `refers_to_nodes` edges — if any, **Step 4**.
+- [ ] No `new` slug collides with an existing slug — if any, treat as `modified` in **Step 3**.
+- [ ] `decisions.ambiguous[]` + `decisions.orphans[]` carried through — if not, **Step 5**.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any, restart with `context workspace` / `context mdrive` commands.
+
+</procedures>

package/plugin/skills/align-scan/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: align-scan
+description: >
+  First skill of `/context:align`. Reads `WORKSPACE_DIR/output/align.scan.yaml` + the
+  workspace glossary, inspects the raw outlines/full raw evidence, classifies
+  raw material into existing / new / ambiguous / orphan, and writes a
+  structured JSON decisions file for align-propose to consume. The CLI only
+  provides weak candidate seeds and deterministic context; semantic
+  classification is the agent's job. Activates when `/context:align` starts,
+  or when an agent has raw material ready and needs a first-cut candidate list before the
+  structural proposal step.
+tools:
+  - Read
+  - Bash
+---
+
+# align-scan — classify raw material
+
+Classify raw material in `WORKSPACE_DIR/output/align.scan.yaml` against the
+workspace glossary. The scan file is a context package, not a final classifier:
+`new_candidates[]` are weak seeds and `raw_outlines[]` is the main reading map.
+Output one JSON payload; no markdown.
+
+`WORKSPACE_DIR` is provided by the caller from `context workspace locate --format json` (`ctxDir`). It is `.context/` in embedded layout and the repository root in root layout.
+
+## TL;DR — Non-negotiables
+
+- Output is JSON only; the CLI owns every rendered markdown file.
+- Input is `WORKSPACE_DIR/output/align.scan.yaml` produced by `context align --scan`; scan v2 is structural-first and deliberately avoids semantic type guesses.
+- Read `raw_outlines[]` for every scanned raw file. When the outline or previews are insufficient, read the full raw file with `context workspace read <path> --format text`.
+- Treat `scan.new_candidates[]` as weak seeds only. `semantic_type: "unresolved"` / `classification_required: true` means the CLI intentionally did not classify it.
+- `type` is one of `domain / entity / action / concept` (see [Node types](references/data-model.md#node-types)); nothing else.
+- Every `entity` candidate carries ≥1 tag from group A or B (see [Entity tag groups](references/data-model.md#entity-tag-groups)).
+- Every candidate has ≥1 `mention` with `{file, line, quote}` (quote ≤180 chars); no fabrication.
+- Glossary hits become `existing`, not new candidates (see [Glossary](references/data-model.md#glossary)).
+- Relational titles ("X affects Y", "Y-side of X", "X migration") are not Entities — re-route via [False-Entity smell](references/data-model.md#false-entity-smell).
+- Raw file paths in the scan are relative to `WORKSPACE_DIR`; read raw evidence only with `context workspace read <path>`. Never use Read / Glob / Grep against workspace files.
+- Save the decisions file only with `context align --save-scan-decisions -`; do not touch `knowledge/`, raw files, or cache files.
+- Output language: user-facing prose matches the user's conversation language; JSON keys / slug / tag values stay English.
+
+<reference>
+
+## Output schema (agent decisions)
+
+This is the JSON you write with `context align --save-scan-decisions -`.
+It is not the raw CLI scan schema. In `output/align.scan.yaml`,
+`scan.new_candidates[]` may omit `suggested_type` / `suggested_tags`;
+the agent must fill them after reading raw evidence. When a candidate has
+`semantic_type: "unresolved"` and `classification_required: true`, that is the
+expected scan-v2 shape, not an error.
+
+```jsonc
+{
+  "scan_version": 2,
+  "workspace": "<workspace-name from scan>",
+  "existing_nodes": [
+    { "slug": "...", "type": "entity|action|concept|domain",
+      "confirmed_mentions": [ { "file": "...", "line": 12, "quote": "..." } ] }
+  ],
+  "new_candidates": [
+    { "name": "<human title>", "suggested_slug": "<kebab-case>",
+      "suggested_type": "entity|action|concept|domain",
+      "suggested_tags": ["lib"],
+      "confidence": "high|medium|low",
+      "mentions": [ { "file": "...", "line": 45, "quote": "..." } ],
+      "suggested_parent": "<slug>",
+      "suggested_realizes": "<slug>",
+      "notes": "<optional>"
+    }
+  ],
+  "ambiguous": [
+    { "phrase": "...",
+      "candidates": [
+        { "kind": "existing", "slug": "..." },
+        { "kind": "new", "name": "...", "suggested_type": "...", "suggested_tags": [] }
+      ],
+      "mentions": [ ... ],
+      "reroute_as": "<optional: Section on target-slug>"
+    }
+  ],
+  "orphans": [ { "slug": "...", "reason": "...", "mentions": [ ... ] } ],
+  "decisions": { "notes": "<free-form rationale>" }
+}
+```
+
+## Confidence calibration
+
+| `confidence` | When |
+|---|---|
+| `high` | Multiple direct mentions + clear integration signal (authoritative "X is our X library" prose) |
+| `medium` | ≥2 mentions OR a single authoritative mention (section heading) |
+| `low` | Single peripheral mention; prefer `ambiguous` over a low-confidence `new` |
+
+</reference>
+
+<procedures>
+
+### Step 1 — Read the scan
+
+Read `output/align.scan.yaml` with `context workspace read output/align.scan.yaml --format text`
+and verify `scan_version: 2` (legacy `scan_version: 1` is readable). If missing, stop and tell the user to run `context align --scan` first.
+Skim `glossary[]` to remember the existing slug + alias set.
+For `scan_version: 2`, first inspect `incremental`:
+
+- `structure_changed[]` and `new_sources[]` are the only reasons to classify structure.
+- `content_changed_only[]` means compile work, not align work; do not create candidates from those sources.
+- `skipped_sources[]` are unchanged; do not classify them.
+- `unknown_sources[]` cannot be treated as unchanged. Return control to the caller with the reason unless the caller chose a full scan.
+
+When source context is needed, run `context workspace read <path> --format text` where
+`<path>` comes from `raw_files_scanned[]` or `mentions[].file`; for example,
+`raw/local/2026-04-25-vmok.md`. Do not attempt to read only `2026-04-25-vmok.md`
+from the current directory, and do not use the Read tool against `WORKSPACE_DIR`.
+
+Then inspect every `raw_outlines[]` entry:
+
+- `headings[]` shows the full H1-H6 shape so H3/H4 content is not ignored.
+- `relation_lines[]` shows protocol-like navigation hints. Treat them as structure, not content claims, unless the surrounding raw prose adds a business claim.
+- `relation_hints[]` is the structured version of those navigation lines (`parent` / `children` / `related` / `relations` plus link targets). Use it to preserve explicit raw links, but do not infer semantic type from it.
+- `evidence_blocks[]` gives short previews for all parsed blocks. If a candidate decision depends on text outside the preview, read the full raw file through `context workspace read`.
+
+### Step 2 — Promote `existing_nodes`
+
+Copy every `scan.existing_nodes[]` entry into `output.existing_nodes[]`
+with its `confirmed_mentions`. If any raw quote contradicts the
+glossary summary (sunset / replaced), also emit an `orphan` entry;
+never silently drop.
+
+### Step 3 — Classify raw material
+
+Use `scan.new_candidates[]` as a seed list, then check `raw_outlines[]` and full raw evidence before deciding. A new Node can come from a seed, a heading visible only in `raw_outlines[]`, or a repeated/raw-supported concept discovered while reading the full source. Conversely, a seed can be demoted to a Section or ignored as navigation.
+
+For each potential topic:
+
+1. Match against glossary per [Glossary](references/data-model.md#glossary). A hit moves the item to `existing_nodes`.
+2. Pick `suggested_type` per [Node types](references/data-model.md#node-types). Use [Entity vs Concept test](references/data-model.md#entity-vs-concept-test) when torn between entity and concept.
+3. For `entity`, pick tags per [Entity tag groups](references/data-model.md#entity-tag-groups). If neither group has a legal tag, route via [False-Entity smell](references/data-model.md#false-entity-smell) into `ambiguous`; do not force a tag.
+4. Map any deprecated tag from the raw to its canonical form per [Deprecated tags](references/data-model.md#deprecated-tags).
+5. Assign `confidence` per [Confidence calibration](#confidence-calibration).
+6. Record demoted headings / seeds in `decisions.notes` so align-propose can explain why they became Sections or navigation instead of Nodes.
+
+### Step 4 — Carry ambiguities and orphans
+
+For each `scan.ambiguous[]`, fill in a best-guess `suggested_type + suggested_tags` on the `new`-side candidates so align-propose can render them. Do not resolve ambiguities here — the user owns that decision. Copy `scan.orphans[]` through; add discoveries from Step 2.
+
+### Step 5 — Save the JSON
+
+Pass one UTF-8 JSON document to `context align --save-scan-decisions -`.
+No markdown wrapper, no leading prose.
+
+### Step 6 — Self-verify
+
+- [ ] Every `new_candidates[]` entry has ≥1 mention — if not, back to **Step 3**.
+- [ ] Every `entity` `new_candidates[]` has an A or B tag — if not, **Step 3** (re-route via False-Entity smell).
+- [ ] Every `ambiguous[]` entry has a candidate that is either `existing` OR a fully-typed `new` — if not, **Step 4**.
+- [ ] Output is pure JSON — if any markdown leaked, **Step 5**.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any, restart with `context workspace` commands.
+
+Return control to the caller; do not invoke subsequent skills yourself.
+
+</procedures>