@c4a/context-cli 0.5.29-alpha.1 → 0.5.29-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.29-alpha.1",
+  "version": "0.5.29-alpha.2",
   "type": "module",
   "bin": {
     "context": "./cli.js"

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts. CLI does mechanical work; agent drives compile/drop via skill protocols.",
-  "version": "0.5.29-alpha.1",
+  "version": "0.5.29-alpha.2",
   "author": {
     "name": "c4a"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.5.29-alpha.1",
+  "version": "0.5.29-alpha.2",
   "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into source-traced local knowledge, query with citations, and govern source updates.",
   "author": {
     "name": "c4a"

package/plugin/commands/capture.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(context:*, brew:*, curl:*, sh:*, scoop:*, choco:*, lark-cli:
 <!--
 This command has no companion skill. Its protocol (argument routing +
 missing-dependency install flow) lives inline here per the slash-command
-length exemption in packages/context-cli/CLAUDE.md.
+length exemption for self-contained slash commands.
 -->
 
 ## Your task

package/plugin/commands/compile.md

@@ -6,16 +6,15 @@ allowed-tools: Read, Bash(context:*)
 
 <!--
 This command is slightly over the 30-line default because it carries
-the default-mode vs `--plan`-mode mode comparison inline; per the
-multi-mode exemption in packages/context-cli/CLAUDE.md, the mode
-contrast belongs here rather than split across skill references.
+the default-mode vs `--plan`-mode comparison inline; the mode contrast
+belongs here rather than split across skill references.
 The agent protocol itself still delegates to the compile-draft /
 compile-close skills.
 -->
 
 ## Your task
 
-Synthesise the align plan into the workspace `knowledge/` directory. The agent produces `CompileDraftAgentOutput` per Node; the CLI writes everything. Workspace reads go through `context workspace`; workflow writes go through `context compile` / `context mdrive`, never through direct file tools.
+Synthesise the align plan into the workspace `knowledge/` directory. The agent produces compile draft JSON per Node; the CLI writes everything. Workspace reads go through `context workspace`; workflow writes go through `context compile` / `context mdrive`, never through direct file tools.
 
 Modes:
 
@@ -28,20 +27,30 @@ Preflight:
 
 1. Run `context workspace locate --format json` and use `ctxDir` from that JSON as `WORKSPACE_DIR`. In embedded layout it is the `.context/` directory; in root layout it is the current knowledge repo root. Use `WORKSPACE_DIR/output/...` and `WORKSPACE_DIR/knowledge/...` below; do not assume `.context/...`.
 2. Require `output/align.md` + `output/bind.yaml`; check them with `context workspace list output --format json`. If missing, tell the user to run `/context:align` and stop.
-3. Run `context doctor`; output-align group must be green. Incremental cache group warnings are informational here; only output-align errors block compile. Run `context mdrive workspace stats --format json` and `context source list --format json` and record the before counts.
+3. Run `context doctor`; output-align group must be green. Incremental cache group warnings are informational here; only output-align errors block compile. Run `context mdrive workspace stats --format json`, `context source list --format json`, and `context status --format json`; record the before counts and `STATUS.semantic.refreshed_source_pending_compile.source_ids[]`.
 4. Read `output/align.md` with `context workspace read output/align.md --format text`. Record Nodes in the order they appear in `frontmatter.nodes[]` — do NOT re-sort.
 5. Run `context compile --changes --format json` and parse the JSON as `COMPILE_WORKSET`.
-   - If `COMPILE_WORKSET.reason` is `no-changed-nodes`, report `no changed nodes`; stop before reading `compile-draft`, running any draft command, or running close.
+   - If `COMPILE_WORKSET.reason` is `no-changed-nodes` and there are no refreshed sources pending compile, report `no changed nodes`; stop before reading `compile-draft`, running any draft command, or running close.
    - If `COMPILE_WORKSET.status` is `unknown-input`, continue conservatively using the Nodes listed in `COMPILE_WORKSET.nodes`; keep the `unknown_inputs[]` reasons in the final report.
    - Otherwise process only `COMPILE_WORKSET.nodes`, preserving the `frontmatter.nodes[]` order. Per-Node `processing <slug>` echoes must match this order.
 
+Review stdin rule: `context reconcile review` accepts at most one `-` input. If either the prepared context or the decisions document is passed through stdin, write the other payload to a temporary scratch file outside `WORKSPACE_DIR`, or reuse a durable CLI scratch file. Valid shapes are `context reconcile review --context - --decisions <scratch-file> --format json` or `context reconcile review --context <prepare-file> --decisions - --format json`; never pass `-` to both flags in the same command.
+
+Refreshed-source loop:
+
+1. If `STATUS.semantic.refreshed_source_pending_compile.source_ids[]` is non-empty, process each source id before the per-Node draft loop.
+2. Run `context reconcile prepare --mode refresh --source <source-id> --format json`. Feed that JSON to `${CLAUDE_PLUGIN_ROOT}/skills/semantic-reconcile/SKILL.md`.
+3. Pass the skill output to `context reconcile review`, following the review stdin rule above: one input may be `-`, the other must be a scratch file. Resolve questions exactly like the per-Node loop.
+4. Default mode only: run `context reconcile apply --input <confirmed-decisions>`. In `--plan` mode, stop after review and report the not-written refresh decisions.
+5. After all refreshed sources are applied in default mode, run `context compile --changes --format json --ignore-source <source-id>` with one `--ignore-source` flag for each refresh-applied source. Use that filtered result for the per-Node loop. This does not rebuild section fingerprints early; it only removes Nodes whose remaining changed blocks came entirely from sources already handled by refresh reconciliation. If a Node still has changed blocks from other sources, unknown inputs, or full-context reasons, keep it in the ordinary per-Node loop.
+
 Per-Node loop:
 
-1. For every workset Node, run `context compile --context <slug> --changed-only --save-output`. Use the JSON stdout as the NodeContext for the draft skill. When the workset requires full context, the CLI returns `incremental.status: "full-context"` with the `unknown_inputs[]` reasons while still using the changed-only entrypoint. The CLI stores the durable context scratch copy under `output/`. Do not expand the context with direct file tools; the NodeContext is the evidence boundary.
+1. For every workset Node, run `context compile --context <slug> --changed-only --save-output`. If the refreshed-source loop applied any source, append the same `--ignore-source <source-id>` flags used for the filtered workset. Use the JSON stdout as the NodeContext for the draft skill. When the workset requires full context, the CLI returns `incremental.status: "full-context"` with the `unknown_inputs[]` reasons while still using the changed-only entrypoint. The CLI stores the durable context scratch copy under `output/`. Do not expand the context with direct file tools; the NodeContext is the evidence boundary.
 2. Read `${CLAUDE_PLUGIN_ROOT}/skills/compile-draft/SKILL.md` and follow its procedures; keep the emitted draft JSON/YAML in memory.
 3. Pass the draft to `context compile --draft <slug> --input - --save-input --plan`. This validates schema, source refs, and mount matrix without touching `knowledge/`. On CLI rejection, read the error verbatim, fix the draft via the skill's self-verify, and retry up to 3 times.
 4. Run `context reconcile prepare --mode compile --node <slug> --draft WORKSPACE_DIR/output/compile.<slug>.draft.yaml --format json`. Feed that JSON to `${CLAUDE_PLUGIN_ROOT}/skills/semantic-reconcile/SKILL.md`.
-5. Pass the skill output to `context reconcile review --context <prepare-file-or-stdin> --decisions <decisions-file-or-stdin> --format json`. If questions are returned, ask the user in business language and rewrite unresolved `ask_user` items into final actions before applying.
+5. Pass the skill output to `context reconcile review`, following the review stdin rule above: one input may be `-`, the other must be a scratch file. If questions are returned, ask the user in business language and convert unresolved `ask_user` items into final actions before applying.
 6. Default mode only: run `context reconcile apply --input <confirmed-decisions>`. This writes active knowledge, verifies, and records `decisions/semantic.yaml`. In `--plan` mode, stop after review and report the not-written decisions.
 7. Persistent failure → stop and surface the full rejection list; never edit rendered files to bypass.
 
@@ -60,7 +69,7 @@ Never use Read / Glob / Grep / Write against `WORKSPACE_DIR`; use `context works
 For large draft payloads, feed stdin directly into the `context compile` command with a heredoc. Do not pipe a heredoc through another command and do not redirect generated content into workspace files:
 
 ```bash
-context compile --draft billing-api --input - --save-input <<'JSON'
+context compile --draft billing-api --input - --save-input --plan <<'JSON'
 {
   "target_node": "billing-api",
   "actions": [
@@ -75,8 +84,8 @@ Final report contract (default mode):
 - Report in the user's conversation language.
 - Keep a stable structure with these semantic sections; translate section headings into the user's conversation language instead of copying these English labels verbatim:
   1. Completion headline.
-  2. Per-Node writes table with one row per Node in align frontmatter order. Columns: Node title or slug, type, and add / update / supersede / deprecate counts. Include skipped count only when non-zero.
-  3. Close stage with `context compile --close` result, final node/section totals, verify status, changelog stamp, incremental counts (`recompiled`, `locator_updates`, `rebuilt`), section fingerprint rebuild count, and archive directory for compile scratch files when present.
+  2. Semantic apply table. Include refreshed-source rows first in source-id order when the refreshed-source loop ran, then one row per Node in align frontmatter order. Columns: target (source id or Node title/slug), type (`refresh` or Node type), and the `context reconcile apply --format json` counts: `applied`, `skipped`, `merged`, `superseded`, `kept_separate`, and `questions_resolved`. Include `reanchored`, `removed_unsupported`, and `split_then_reanchored` only when non-zero.
+  3. Close stage with `context compile --close` result, final node/section totals, verify status, changelog stamp, incremental counts (`recompiled`, `locator_updates`, `rebuilt`), section fingerprint rebuild count, and archive directory for compile scratch files when present. Do not use close output as the semantic apply summary; aggregate the per-Node `context reconcile apply` results from Step 6.
   4. Before/after status diff table with at least total nodes, node counts by type, total sections, and last compile time.
   5. Knowledge files as clickable markdown links. Use absolute path targets without `file://`, for example `[knowledge/entity/vmok.md](/abs/path/.context/knowledge/entity/vmok.md)`. Include `_index.md`, `changelog.md`, and every Node article returned by `context mdrive node list --format json`. Use the path relative to `WORKSPACE_DIR` as the link label.
   6. Optional next step only when there is a concrete useful follow-up (for example recapture stale material or run `/context:align` to revise structure).

package/plugin/commands/extract.md

@@ -1,5 +1,5 @@
 ---
-description: "Debug helper: run @c4a/extract against a path and print the ExtractionResult (no files written)."
+description: "Debug helper: run extraction against a path and print structured results (no files written)."
 argument-hint: "<path> [--format json|jsonl|pretty]"
 allowed-tools: Bash(context:*)
 ---

package/plugin/commands/init.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(context:*)
 <!--
 This command has no companion skill. Its protocol (the focus multi-choice
 UX before `context init` runs) lives inline here per the slash-command
-length exemption in packages/context-cli/CLAUDE.md.
+length exemption for self-contained slash commands.
 -->
 
 ## Your task

package/plugin/commands/purge.md

@@ -10,6 +10,10 @@ Purge the workspace archive. This is destructive: it deletes all restorable
 artifacts under `archive/` that were created by `context drop --apply-plan`.
 It does not modify active `raw/` or active `knowledge/`.
 
+It does not delete `output/archive/`. Compile/align scratch archives are kept
+under the output lifecycle so prior agent inputs remain inspectable; clean them
+manually or via a future output-retention policy, not with `context purge`.
+
 Run `context purge $ARGUMENTS`. If `--yes` is absent, the CLI prints a summary
 and asks for confirmation. Relay that summary in the user's language and do not
 try to inspect `archive/` yourself.

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

@@ -71,6 +71,19 @@ edges:
 decisions:
   notes: |
     <brief rationale + demotions + unresolved questions>
+  new_candidates:
+    - slug: <accepted-node-slug>
+      mentions:
+        - file: <raw-file>
+          line: <line-number>
+          quote: <verbatim raw quote>
+  demotions:
+    - heading: <candidate or heading that was not promoted>
+      outcome: kept as Section | merged into <slug> | ignored as navigation
+      mentions:
+        - file: <raw-file>
+          line: <line-number>
+          quote: <verbatim raw quote>
   ambiguous: [ ... carried from scan + discovered re-routes ... ]
   orphans:   [ ... carried from scan ... ]
 ```
@@ -84,7 +97,8 @@ 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.
+   fields yourself. Ask the user only when future user-visible lookup or
+   organization 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
@@ -115,6 +129,11 @@ For each `new_candidates[]` from `output/align.scan-decisions.json`:
 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).
+6. For every candidate you promote into `nodes[]`, copy its raw `mentions[]`
+   into `decisions.new_candidates[]` under the final `slug`. For every
+   candidate or heading you do not promote, add `decisions.demotions[]` with
+   the raw mention and the outcome. These are review evidence, not new
+   summaries.
 
 ### Step 4 — Enumerate edges
 
@@ -133,6 +152,8 @@ Emit the [AlignRenderInput shape](#alignrenderinput-shape) as YAML for the calle
 - [ ] 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**.
+- [ ] Every promoted new candidate has `decisions.new_candidates[].mentions[]` copied from scan evidence — if not, **Step 3**.
+- [ ] Every demoted candidate/heading has `decisions.demotions[]` with raw mentions — 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**.

package/plugin/skills/align-scan/references/data-model.md

@@ -325,7 +325,7 @@ Warnings don't block; errors flip exit to 2.
 | Code | Level | Meaning | Minimum fix |
 |---|---|---|---|
 | `dropped-source-reference` | error | Node `sources[]` lists a dropped source | Run `/context:drop` to complete cleanup; it uses `context mdrive node update` to remove the id |
-| `dangling-source-alias` | error | Section `src-N` past end of `sources[]` | Re-run `context compile --draft <slug>` with correct `source_ref` |
+| `dangling-source-alias` | error | Section `src-N` past end of `sources[]` | Re-run `context compile --draft <slug> --plan` with correct `source_ref` |
 | `sourceless-node` | warning | Node `sources[]` is empty after cleanup | Keep only if intentionally orphaned by `/context:drop`; otherwise re-anchor or add a source via `context mdrive node update` |
 | `body-ad-hoc-heading` | error | Node body has a heading the parser reads as a nested Node | Re-run `/context:compile` so the draft loop moves that content into Sections |
 | `invalid-section-mount` | error | Kind × Node type mismatch | Re-run `/context:compile`; or deprecate via `context mdrive section deprecate` |

package/plugin/skills/align-scan/references/user-question-contract.md

@@ -45,7 +45,8 @@ edges, slugs, and source references.
 | Two products / systems / ideas might be alternatives, dependency, or merely co-mentioned | Yes | If unclear and no user answer, keep only the shared parent; no direct relationship |
 | A stale source conflicts with a newer active source | Yes | Keep both candidates and ask which claim is current |
 | A source is being dropped and a claim has no replacement evidence | No | Mark the claim as no longer supported |
-| A source is being dropped and another source appears to support the same claim, but the match is inferred | Usually no; show it in the impact plan | Move support to the surviving source and mark the confidence as inferred |
+| A source is being dropped and another source explicitly supports the same claim | No | Move support to the surviving source and mark the confidence based on evidence strength |
+| A source is being dropped and another source only appears to support the claim by inference | Yes | Do not silently re-anchor; ask the user or mark the claim as unsupported |
 | A proposed rename changes the user's vocabulary | Yes | Keep the original title / alias |
 | A section kind, edge type, source-ref, or file layout choice is required | No | Agent maps from the user's intent to the model |
 
@@ -53,32 +54,34 @@ edges, slugs, and source references.
 
 ### Align: standalone topic or detail
 
-Context: "I found several Vmok subsections such as 'Core capabilities',
-'Scenarios', and 'Integration example'. The decision is whether people will
-search these directly later."
+Context: "I found several payment runtime subsections such as 'Isolation
+model', 'Retry policy', and 'Integration example'. The decision is whether
+people will search these directly later."
 
-Question: "How should these Vmok subsections be organized?"
+Question: "How should these payment runtime subsections be organized?"
 
 Choices:
 
-- "Keep them as parts of Vmok" — choose this if people normally read them
-  while looking at Vmok.
+- "Keep them as parts of payment runtime" — choose this if people normally
+  read them while looking at payment runtime.
 - "Make them separate searchable entries" — choose this if people will ask
-  for "Vmok integration example" or "Vmok scenarios" directly.
+  for "payment retry policy" or "payment runtime integration example" directly.
 - "Keep only the strongest one separate" — choose this when only one
   subsection deserves direct lookup.
 
 ### Align: relationship meaning
 
-Context: "Vmok and Garfish appear near each other in the source documents, but
-the text does not clearly say how they relate."
+Context: "Portal Shell and Plugin Runtime appear near each other in the source
+documents, but the text does not clearly say how they relate."
 
-Question: "What is the business relationship between Vmok and Garfish?"
+Question: "What is the business relationship between Portal Shell and Plugin
+Runtime?"
 
 Choices:
 
 - "Comparable alternatives" — people may compare them or choose one.
-- "Vmok is based on Garfish" — Vmok needs Garfish or builds on it.
+- "Portal Shell is based on Plugin Runtime" — Portal Shell needs Plugin
+  Runtime or builds on it.
 - "Same area, no direct relationship" — both belong under the same broader
   topic, but there is no direct link.
 
@@ -100,7 +103,8 @@ Choices:
 
 - "Only navigation" — use them to understand relationships, not as content.
 - "Preserve the explanation" — keep the useful prose in the relevant topic.
-- "Not sure" — keep a short summary for now.
+- "Not sure" — keep only raw-backed prose in the relevant topic and flag the
+  uncertainty in the summary.
 
 ### Align: old or conflicting source
 
@@ -151,5 +155,5 @@ Choices:
 | "Keep as Section or promote to Concept?" | "Will people search this as its own topic, or only read it inside the parent topic?" |
 | "Choose related_to / depends_on / no edge." | "Are these alternatives, does one build on the other, or are they only in the same area?" |
 | "3 raw files all have Relations blocks. Drop or keep as Section?" | "I found repeated related-links sections. They look like navigation, so I will treat them as structure and not copy them as content." |
-| "Re-anchor section-3 from src-1 to src-2?" | "Another source still supports this claim, so I will keep it but mark the support as inferred." |
-| "Rename slug vmok-core-capability?" | "Should readers see this as 'Vmok core capabilities', or do you prefer another title?" |
+| "Re-anchor section-3 from src-1 to src-2?" | "Another source explicitly supports this claim, so I will keep it; if the support is only inferred, I will ask before changing it." |
+| "Rename slug payment-retry-policy?" | "Should readers see this as 'payment retry policy', or do you prefer another title?" |

package/plugin/skills/compile-draft/SKILL.md

@@ -6,8 +6,8 @@ description: >
   raw snippets from `bind.yaml` + existing Sections if any), classifies
   every raw fragment into a Section kind via the priority chain, writes
   content + detail + confidence + `source_ref_text`, and emits a
-  `CompileDraftAgentOutput` JSON. The CLI applies the actions via
-  `context compile --draft <slug> --input <file>`. Activates when
+  compile draft JSON document. The CLI validates the actions via
+  `context compile --draft <slug> --input <file> --plan`. Activates when
   `/context:compile` iterates across the confirmed align plan.
 tools:
   - Read
@@ -22,7 +22,7 @@ deprecate / skip` actions; emit JSON; the CLI performs every write.
 ## TL;DR — Non-negotiables
 
 - One Node per invocation — `target_node` MUST equal `node.slug`; no cross-Node writes.
-- Agent emits JSON only; no markdown, no direct workspace file writes. The caller passes the JSON to `context compile --draft <slug> --input -`; the caller adds `--save-input` when a durable scratch copy is needed.
+- Agent emits JSON only; no markdown, no direct workspace file writes. The caller passes the JSON to `context compile --draft <slug> --input - --plan`; the caller adds `--save-input` when a durable scratch copy is needed.
 - Default compile sends changed-only NodeContext. Treat `raw_snippets[]` as the complete evidence boundary; never use direct workspace file tools to expand it.
 - If `incremental.status` is `full-context`, draft from the full fallback and preserve the `unknown_inputs[]` reasons in any abort/retry explanation.
 - The CLI may deterministically skip unchanged output or update locator-only evidence before writing. Do not force rewrites to bypass fingerprint skip.
@@ -35,6 +35,7 @@ deprecate / skip` actions; emit JSON; the CLI performs every write.
 - For `add` and `supersede.new`, omit optional fields when empty; do not emit `detail: null`. `detail: null` only has "clear existing detail" meaning on `update`.
 - `refers_to_nodes[]` only carries slugs present in the context's glossary or existing Sections; never invent one.
 - `supersede` is for semantic replacement; `update` is for typo / wording fixes; `deprecate` needs a `reason`; `skip` is the honest default when raw adds nothing.
+- Domain containers may legitimately compile to no Sections. If their raw snippets only contain navigation (`Parent` / `Children` / `Related` / `Relations`) or placeholder text that explicitly says no detailed content is available, emit `skip`; do not turn the align summary or placeholder into a `description` Section.
 - FAQ collections attach to the most specific Node (Entity → Concept → Action → Domain fallback); never a standalone "FAQ Concept" container.
 - Output language: `content` / `detail` match the raw material; user-facing abort/retry explanations match the user's conversation language; kind / confidence / slug identifiers / `source_ref` format stay English.
 
@@ -85,7 +86,7 @@ they are the evidence floor.
 `source_id` is the source registry id, such as `local:billing`; `src-N`
 aliases only appear inside `source_ref` strings.
 
-## Output — `CompileDraftAgentOutput`
+## Output — Compile Draft JSON
 
 ```jsonc
 {
@@ -154,13 +155,18 @@ Before emitting `{op: add, kind: description}`, walk three gates:
 
 If the resulting Node has >50% `description` Sections, treat it as a quality smell: redraft only when the raw snippets actually support more precise Section kinds. Sparse Nodes may legitimately end with one concise `description` or a `skip`; do not invent thin `spec` Sections just to improve the ratio.
 
+Domain container exception: if a Domain's evidence is only a child list,
+relation navigation, or placeholder wording, emit `skip`. The Domain page can
+still be useful via `## Contains` and graph edges created from align; a
+navigation-only snippet is not evidence for a new `description` claim.
+
 ## Glossary and `refers_to_nodes`
 
 When raw mentions a name that overlaps the workspace glossary, put
 that name's slug in `refers_to_nodes[]` for the Section that discusses
-it — do NOT substitute it into the prose. This is how cross-Node
-retrieval works ("which Sections mention React?"). Slugs come from
-the context's existing Sections + glossary; never invent one. A
+it — do NOT substitute it into the prose. This preserves explicit
+cross-Node references for query answers and citations without rewriting
+the claim. Slugs come from the context's existing Sections + glossary; never invent one. A
 Section can reference multiple Nodes (common on `comparison` /
 `decision`).
 
@@ -227,7 +233,7 @@ For each change from Steps 2-3:
 
 ### Step 5 — Emit the JSON
 
-Emit one `CompileDraftAgentOutput` document for the caller to pass to `context compile --draft <slug> --input -` (or `context compile --draft <slug> --input - --save-input` when a durable scratch copy is needed). No markdown wrapper, no leading prose, no trailing commentary.
+Emit one compile draft JSON document for the caller to pass to `context compile --draft <slug> --input - --plan` (or `context compile --draft <slug> --input - --save-input --plan` when a durable scratch copy is needed). No markdown wrapper, no leading prose, no trailing commentary.
 
 ### Step 6 — Self-verify
 

package/plugin/skills/drop/SKILL.md

@@ -47,11 +47,14 @@ The JSON plan has:
 | `affected_nodes[]` | Topics whose source list contains the dropped source |
 | `affected_nodes[].sections[]` | Knowledge items that require semantic reconciliation before the source is dropped |
 | `affected_nodes[].reindex_sections[]` | Knowledge items whose internal source alias will be renumbered after the source is removed |
-| `affected_nodes[].will_be_sourceless` | Topic may be archived if it has no remaining active content after cleanup |
-| `affected_graph_edges[]` | Explicit graph edges that will be removed because one endpoint leaves active knowledge |
+| `affected_nodes[].will_be_sourceless` | Topic has no remaining source ids after cleanup |
+| `affected_nodes[].will_be_empty` | Topic has no remaining Section/body/children/contains after cleanup and may be archived even if another source id remains |
+| `affected_graph_edges[]` | Explicit graph edges that will be removed if one endpoint is archived by apply |
 | `unaffected_references[]` | Topic relationships that mention affected topics but are not source evidence |
 | `summary` | Counts for confirmation and changelog |
 
+If a non-domain Node would keep an active source id but lose all of its own Sections while still carrying child Nodes, contains links, or body text, do not rely on verify to catch it after mutation. Produce a semantic reanchor/split decision that preserves a supported Section, or expect `drop --apply-plan` to reject before writing.
+
 ## User-facing impact summary shape
 
 ```
@@ -88,6 +91,9 @@ appends a `[drop]` line to `knowledge/changelog.md`, records
 `decisions/semantic.yaml`, and runs verify. It exits
 non-zero if the source-id is unknown, already dropped, plan shape is invalid,
 the plan is stale, semantic decisions are unresolved/invalid, or verify reports errors.
+In drop mode, `remove_unsupported` means physical removal from active knowledge
+after the archive captures the before snapshot; compile/refresh apply uses the
+same action name for Section deprecation.
 
 </reference>
 
@@ -108,8 +114,9 @@ source-already-dropped, relay the error and stop.
 Render the [User-facing impact summary shape](#user-facing-impact-summary-shape)
 from the plan JSON in the user's language. Make clear that dropping a source
 removes listed content from active knowledge but keeps it restorable under
-`archive/` until `context purge`. Mention graph edge cleanup when
-`affected_graph_edges[]` is non-empty. Include the reason that will be stamped; if
+`archive/` until `context purge`. Mention conditional graph edge cleanup when
+`affected_graph_edges[]` is non-empty; these edges are removed only if the
+endpoint leaves active knowledge after reconciliation. Include the reason that will be stamped; if
 it is still unknown, ask for the reason before continuing. If `--yes`, log
 "auto-confirmed per --yes" and continue. Otherwise wait for `y`; abort on
 anything else without writing.
@@ -125,7 +132,7 @@ context reconcile prepare --mode drop --drop-plan <plan-file> --format json
 Invoke `${CLAUDE_PLUGIN_ROOT}/skills/semantic-reconcile/SKILL.md` with that
 prepare payload. Save its decision document outside `WORKSPACE_DIR`, then run
 `context reconcile review --context <context-file> --decisions <decisions-file> --format json`.
-If review returns any `questions[]`, ask the user and rewrite those decisions
+If review returns any `questions[]`, ask the user and convert those decisions
 from `ask_user` into one of `reanchor`, `remove_unsupported`, or
 `split_then_reanchor` before continuing. Do not let `--yes` bypass this step.
 

package/plugin/skills/semantic-reconcile/SKILL.md

@@ -44,23 +44,46 @@ decisions:
       source_ref: "src-2#runtime L12-14"
       source_ref_text: "sandboxing to avoid state pollution"
     rationale: "The new evidence refines the same claim."
-    user_confirmation:
-      required: true
-      question_type: merge_confirmation
 ```
 
 ## Action Rules
 
-| action | Required fields |
-|---|---|
-| `duplicate_skip` | `target` |
-| `merge_update` | `target`, `proposed.content`, `proposed.source_ref` |
-| `supersede` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref` |
-| `reanchor` | `target`, `proposed.source_ref`, `proposed.confidence` |
-| `remove_unsupported` | `target` |
-| `keep_separate` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref` |
-| `split_then_reanchor` | `target`, `proposed.sections[]` |
-| `ask_user` | `user_confirmation.required: true` |
+| action | Required fields | Validation |
+|---|---|---|
+| `duplicate_skip` | `target` | Exact duplicate or already-applied no-op only. |
+| `merge_update` | `target`, `proposed.content`, `proposed.source_ref`, `proposed.source_ref_text` when present in prepare | Final content must be supported by one raw line range; `proposed.kind`, when present, must match target kind. |
+| `supersede` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref`, `proposed.source_ref_text` when present in prepare | New Section claim must be supported by one raw line range. |
+| `reanchor` | `target`, `proposed.source_ref`, `proposed.confidence` | Use only when target content is still supported by the new source. |
+| `remove_unsupported` | `target` | Use when no active source supports the target claim in this mode. |
+| `keep_separate` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref`, `proposed.source_ref_text` when present in prepare | New orthogonal claim must be supported by one raw line range. |
+| `split_then_reanchor` | `target`, `proposed.sections[]` with each Section carrying `kind`, `content`, `source_ref`, and `source_ref_text` when present in prepare | Each split Section must be independently supported by its cited raw line range. |
+| `ask_user` | `user_confirmation.required: true` | Use only when business meaning or support cannot be decided from prepared evidence. |
+
+For `merge_update`, `supersede`, `keep_separate`, and
+`split_then_reanchor`, the final Section content must be lexically supported by
+the cited raw line range in `proposed.source_ref`. Preserve
+`proposed.source_ref_text` from the prepared context when it is present; it is
+the human-readable evidence text the CLI used to derive the canonical
+`source_ref`. Content should retain the raw evidence's key domain terms,
+numbers, code literals, and named entities. Do not turn sparse raw evidence
+into a broad summary, and do not cite a title, `Relations`, `Parent`,
+`Children`, or `Related` navigation line as the only support for a substantive
+claim.
+
+The support gate exists to prevent orphan claims and false evidence links, not
+to optimize retrieval. Prefer preserving a precise raw-backed claim over
+rewriting content into a smoother summary. If a useful reader summary would
+combine multiple evidence ranges, choose `split_then_reanchor` or `ask_user`
+instead of forcing it into one `source_ref`.
+
+Final executable decisions must not carry `user_confirmation.required: true`.
+Use that flag only on `action: ask_user` items that still require user input.
+
+`remove_unsupported` has mode-specific write behavior. In compile/refresh
+apply it deprecates the target Section so the unsupported claim remains visible
+as inactive history. In drop apply it physically removes the Section from active
+knowledge after `archive/sources/.../knowledge/before/` captures the pre-drop
+file. Use the same action only when this mode-specific outcome is intended.
 
 </reference>
 
@@ -82,7 +105,7 @@ decision as a prior only and continue judging.
 Classify each item:
 
 - Exact same claim already active -> `exact_duplicate` + `duplicate_skip`.
-- Same claim with safer wording and one supporting source -> `strong_equivalent` or `near_duplicate` + `merge_update`.
+- Same claim with a raw-supported correction or refinement from one supporting source -> `strong_equivalent` or `near_duplicate` + `merge_update`.
 - Additional but separate boundary -> `complement` + `keep_separate`.
 - New material replaces old rule -> `supersedes` + `supersede`.
 - Direct contradiction -> `conflicts` + `ask_user`.