@c4a/context-cli 0.5.29-alpha.1

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

@@ -0,0 +1,246 @@
+---
+name: compile-draft
+description: >
+  Per-Node skill of `/context:compile`. For one Node at a time, reads
+  the CLI-provided `NodeContext` (planned metadata from `align.md` +
+  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
+  `/context:compile` iterates across the confirmed align plan.
+tools:
+  - Read
+  - Bash
+---
+
+# compile-draft — write Section actions for one Node
+
+Classify raw evidence for one Node into `add / update / supersede /
+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.
+- 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.
+- Actions are candidate write actions, not final semantic decisions. If raw appears similar to existing knowledge, add only a `reconcile_hint`; semantic-reconcile may ignore it.
+- Pick Section kinds per the [Section kind priority chain](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-kinds); first match wins.
+- `kind × node.type` must satisfy the [Section mount matrix](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-mount-matrix); mismatches get rejected at write time.
+- `description` is the bottom of the chain, not the default — walk the [Description anti-abuse gates](#description-anti-abuse-gates) before emitting it.
+- Every action cites raw via `source_ref_text` (verbatim quote from the provided snippets) OR a pre-resolved `source_ref` in the [canonical form](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#source_ref-canonical-form); never fabricate a locator or cite navigation-only lines.
+- `content` ≤256 chars; long prose goes in `detail`.
+- 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.
+- 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.
+
+<reference>
+
+## Input — `NodeContext`
+
+```jsonc
+{
+  "node": {
+    "slug": "...", "type": "entity|action|concept|domain",
+    "tags": [...], "title": "...",
+    "sources": ["..."], "aliases": ["..."], "summary": "...",
+    "planned_sections": ["spec", "..."]
+  },
+  "existing": {               // present if the Node already exists
+    "sections": [
+      { "id": "section-1", "kind": "description", "content": "...",
+        "detail": "...", "status": "active|deprecated",
+        "confidence": "...", "source_ref": "src-1#anchor L10-14",
+        "refers_to_nodes": [...] }
+    ]
+  },
+  "mentions":      [ { "file": "raw/...", "line": 12, "quote": "..." } ],
+  "raw_snippets":  [ { "file": "raw/...", "line": 10,
+                       "line_range": [10, 18],
+                       "quote": "...context block...",
+                       "mention_quote": "...",
+                       "source_id": "local:billing",
+                       "snapshot_file": "raw/local/...",
+                       "block_locator_id": "h2-api",
+                       "block_hash": "sha256:...",
+                       "change_status": "changed" } ],
+  "incremental": {
+    "mode": "changed-only",
+    "status": "changed-only|full-context|unchanged",
+    "reason": "source_block_changed|unknown-input|first-compile",
+    "changed_blocks": [ { "status": "changed", "source_id": "local:billing", "block_locator_id": "h2-api" } ],
+    "unknown_inputs": [ { "scope": "compile-changes", "reason": "section-fingerprints-missing" } ]
+  }
+}
+```
+
+`mentions` = raw positions that named this Node. `raw_snippets` =
+wider context blocks around those positions, or the changed raw blocks
+selected by `context compile --changes`. Never reach outside these —
+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`
+
+```jsonc
+{
+  "target_node": "<matches node.slug>",
+  "actions": [
+    { "op": "add", "kind": "spec",
+      "content": "...", "detail": "...",
+      "confidence": "verified|confirmed|inferred|speculative",
+      "refers_to_nodes": ["..."],
+      "source_ref_text": "...",
+      "source_ref": "src-1#anchor L12-18"
+    },
+    { "op": "update", "target_section_id": "section-3",
+      "content": "...", "detail": null,    // null clears detail
+      "confidence": "...", "refers_to_nodes": null,
+      "source_ref_text": "...", "source_ref": "..." },
+    { "op": "supersede", "target_section_id": "section-5",
+      "reason": "raw published a new retention value",
+      "new": { "kind": "spec", "content": "...", "detail": "...",
+               "confidence": "...", "refers_to_nodes": ["..."],
+               "source_ref_text": "...", "source_ref": "..." } },
+    { "op": "deprecate", "target_section_id": "section-2", "reason": "..." },
+    { "op": "skip", "reason": "no new evidence in raw snippets" }
+  ]
+}
+```
+
+Optional `reconcile_hint` shape for any action:
+
+```jsonc
+{
+  "reconcile_hint": {
+    "suggested_relation": "exact_duplicate|near_duplicate|complement|conflicts|keep_separate",
+    "suggested_action": "duplicate_skip|merge_update|keep_separate|ask_user",
+    "similar_section_id": "section-3",
+    "confidence": 0.72,
+    "reason": "The new snippet is close to the existing sandbox isolation Section."
+  }
+}
+```
+
+Hints are recall/explanation aids only. The final relation/action must come
+from `context reconcile prepare` candidates and the semantic-reconcile skill.
+
+## Confidence rubric
+
+Four legal values; pick per raw evidence strength.
+
+| `confidence` | When |
+|---|---|
+| `verified` | Raw provides a directly testable / runnable / observably-validated fact (test output, metric, live check) |
+| `confirmed` | Raw explicitly states the fact in normative voice ("X must …", "the retention is N days") without running a test |
+| `inferred` | You combined ≥2 raw fragments; the derivation is load-bearing but not directly stated |
+| `speculative` | Raw only hints; the Section is a best-effort reading and may not survive review |
+
+Don't game the rubric. Compile-close flags Nodes dominated by
+`speculative` Sections.
+
+## Description anti-abuse gates
+
+Before emitting `{op: add, kind: description}`, walk three gates:
+
+1. **Atomicity**: single narrative, or multi-step / multi-row / multi-config? Multi → split into the right kinds (each step → its own `spec` / `warning`, each row → a `comparison` Section, each config → a `spec`).
+2. **Kind-precision**: is a higher-priority kind more accurate? A comparison table belongs in `comparison`; a rule with a verification method belongs in `spec`; explicit risks belong in `warning`; Q+A belongs in `faq`.
+3. **Action threshold**: multi-step fragments that clear the Action bar → emit `op: skip` with a note "evidence warrants sub-Action; re-align needed"; do not create Nodes from compile-draft.
+
+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.
+
+## 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
+Section can reference multiple Nodes (common on `comparison` /
+`decision`).
+
+## Supersede vs update
+
+| Situation | op |
+|---|---|
+| Same meaning, fixing typo / tightening prose / adding detail | `update` — same `section-N` stays active |
+| New rule replaces old rule (values / policy / spec changed) | `supersede` — old flips to `deprecated`; new gets fresh `section-N+k` |
+| Old rule removed without replacement | `deprecate` (with `reason`) |
+
+`supersede` preserves the audit trail so readers see the prior
+policy — critical for specs / decisions / principles.
+
+## FAQ attachment priority
+
+| FAQ topic | Attach to |
+|---|---|
+| About a concrete thing | That thing's Entity (Section `faq`) |
+| About a concept / mechanism | That Concept |
+| About an action / flow | That Action |
+| Cross-topic / generic workspace FAQ | Domain (fallback only) |
+
+Never manufacture a "FAQ container" Concept — it violates the
+Concept identity rules. If a FAQ cluster grows too large, a
+sub-Entity is the correct escape hatch; flag it in `decisions.notes`
+for a re-align pass.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Sanity-check the context
+
+Confirm `node.slug` is set; abort if not. Note `node.type` — it caps legal kinds per the [Section mount matrix](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-mount-matrix). If `existing.sections[]` is non-empty, read it; you need `section-N` ids for update / supersede / deprecate.
+If `incremental.status` is `unchanged`, emit one `skip` action. If it is `full-context`, continue with the full context but keep the fallback reason visible in any user-facing explanation.
+
+### Step 2 — Classify each raw snippet
+
+For each `raw_snippets[]` entry:
+
+1. Walk the [Section kind priority chain](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#section-kinds); stop at the first kind whose trigger fires.
+2. Verify the kind against the mount matrix for `node.type`. Mismatch → pick the next legal kind down the chain, or emit `skip` with a reason pointing at a better Node. Never "fall through to description" just to place evidence.
+3. If you land on `description`, walk the [Description anti-abuse gates](#description-anti-abuse-gates). Any gate fires → split or `skip`.
+
+### Step 3 — Reconcile with existing Sections
+
+For each existing Section:
+
+- Raw still supports it unchanged → emit nothing (or one summarising `skip`).
+- Raw refines without changing meaning → `update`.
+- Raw changes meaning (new spec value, reversed decision) → `supersede`.
+- Raw removes supporting evidence → `deprecate` with `reason`.
+
+### Step 4 — Build actions
+
+For each change from Steps 2-3:
+
+1. Write `content` ≤256 chars.
+2. Write `detail` for long-form; omit when `content` is self-contained. For `add` / `supersede.new`, never write `detail: null`; the CLI tolerates it as omitted, but it is not the intended output.
+3. Assign `confidence` per the [Confidence rubric](#confidence-rubric).
+4. Fill `refers_to_nodes[]` per [Glossary and refers_to_nodes](#glossary-and-refers_to_nodes).
+5. Cite evidence via `source_ref_text` (a verbatim substring from `raw_snippets[].quote` or `mentions[].quote`). Prefer a substring from the same snippet/block that supports this Section; do not cite a broad title or navigation line when the claim comes from a deeper block. The CLI resolves to the canonical form and ignores navigation headings as anchors; if you already have `(src-N, anchor, line-range)`, include `source_ref` pre-resolved per the [canonical form](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#source_ref-canonical-form).
+
+### 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.
+
+### Step 6 — Self-verify
+
+- [ ] `target_node` equals `node.slug` — if not, **Step 5**.
+- [ ] Every `add` / `supersede.new` has a legal kind × type combination — if not, **Step 2**.
+- [ ] Every `source_ref_text` appears in `raw_snippets[]` or `mentions[]` — if not, **Step 4**; replace with `skip`.
+- [ ] No `add` / `supersede.new` action contains `detail: null` — omit `detail` instead.
+- [ ] No `description` action that would fail the anti-abuse gates — if any, **Step 2**.
+- [ ] Every `update` / `supersede` / `deprecate` targets a known `section-N` — if not, **Step 3**.
+- [ ] `refers_to_nodes[]` only contains slugs from `existing` / glossary — if not, **Step 4**.
+- [ ] If the Node ends up >50% `description`, verify this is due to sparse evidence; otherwise **Step 2**. Do not create unsupported non-description Sections for ratio reasons.
+- [ ] When raw adds nothing, exactly one `op: skip` with a reason; not `actions: []`.
+- [ ] Changed-only context was not expanded by direct workspace reads — if any were used, restart from the CLI-provided NodeContext.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any, restart from the CLI-provided NodeContext.
+
+</procedures>

package/plugin/skills/context-query/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: context-query
+description: >
+  Local knowledge question answering for `/context:query`. The agent uses
+  `context query` hit/miss/select results first, supplements only with scoped
+  context-query views when needed, and answers with Node slug, Section id,
+  and source_ref citations plus explicit gaps for unsupported claims.
+  Activates when `/context:query` is invoked or when an agent needs to
+  answer a question using local Context workspace knowledge with citations.
+tools:
+  - Read
+  - Bash
+---
+
+# context-query — answer from local knowledge with CLI citations
+
+Answer a user question from the local Context workspace without reading
+workspace files directly. The CLI is the only source of local knowledge.
+
+## TL;DR — Non-negotiables
+
+- First tool call must start with `context query --intent description_search --format json --query`. Use `--scope <slug>` only when the user explicitly names a known Node/title/alias.
+- Do not Read, Glob, Grep, or Write `raw/`, `knowledge/`, `archive/`, `decisions/`, or any workspace file to answer the question.
+- Use only `context query` output as evidence. If the CLI returns `miss` or fails, report that result instead of searching files yourself.
+- Every key conclusion must cite `node_slug`, `section_id`, and `source_ref`. `source_ref` follows `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#source_ref-canonical-form`.
+- If returned entries do not support a conclusion, mark it as a gap. Do not turn missing local knowledge into a definite answer.
+- If `state` is `select`, choose a candidate only when the user's wording makes it unambiguous; otherwise ask the user which `slug` to use.
+- If recall diagnostics return `blocked: true`, `truncated: true`, or `reason: "broad_query"`, say recall was limited and ask for a narrower Node, term, version, or scope.
+- If the question names a Node title, alias, or slug, state the actual Node slug used in the answer.
+- When the first query is insufficient, supplement only with scoped query views named in the Supplemental context section or anchors from entry `refers_to_nodes`.
+- Output language follows the user's conversation language. CLI flags, JSON keys, slugs, source refs, and Section ids stay as printed.
+
+<reference>
+
+## Evidence fields
+
+Primary evidence comes from the top-level knowledge-query response:
+
+| Field | Use |
+|---|---|
+| `state` | `hit`, `miss`, or `select`; controls the next step |
+| `routing.intent` | Confirms which high-level query intent ran |
+| `routing.intent_source` | `explicit` or CLI fallback |
+| `routing.search_path` | `graph_walk`, `section_search`, `impact_graph`, or `recall` |
+| `data.entries[]` | Evidence entries used for answer claims |
+| `entry.node_slug` | Required citation field for Section entries |
+| `entry.section_id` | Required citation field for Section entries |
+| `entry.source_ref` | Required citation field for Section entries |
+| `entry.refers_to_nodes[]` | Optional supplemental anchors |
+| `data.candidates[]` | Disambiguation candidates when `state: "select"` |
+
+Supplemental context can come from:
+
+```text
+context query --intent node_search --scope <node_slug> --format json
+context query --intent impact_analysis --scope <node_slug> --format json
+context query --intent node_search --refers-to <node_slug> --format json
+```
+
+## Answer citation shape
+
+Use compact citations next to each key claim:
+
+```text
+<claim> [node_slug / section_id / source_ref]
+```
+
+If multiple Sections support the same claim, cite the strongest one or two.
+Avoid citation-only dumps: summarize what the cited Section supports.
+
+## Gap shape
+
+Use a visible gap when the CLI evidence cannot support the requested fact:
+
+```text
+Gap: local knowledge did not return evidence for <missing point>.
+```
+
+If the likely cause is stale workflow state, suggest the relevant context
+workflow (`/context:align` or `/context:compile`) only when the CLI output or
+the user's wording indicates newly captured material is not yet knowledge.
+
+</reference>
+
+<procedures>
+
+## Step 1: Query
+
+If `$ARGUMENTS` is empty or whitespace-only, ask the user for a question first;
+do not run the query.
+
+Run description search first:
+
+```bash
+context query --intent description_search --format json --query "$ARGUMENTS"
+```
+
+If the user explicitly asks for archive comparison, source cleanup audit, or
+semantic reconciliation candidates, use recall with the matching profile:
+
+- duplicate / near duplicate / dedupe → `--profile reconcile-dedupe`
+- support check / source support → `--profile reconcile-support`
+- refresh / stale source comparison → `--profile reconcile-refresh`
+
+```bash
+context query --intent recall --format json --profile reconcile-dedupe --query "$ARGUMENTS"
+```
+
+Do not use recall archive profiles for ordinary questions.
+
+## Step 2: Parse and gate
+
+Parse JSON before answering.
+
+- If the command fails, report the CLI failure and stop.
+- If `state` is `miss`, report no local knowledge hit and stop.
+- If `state` is `select`, use `data.candidates[]` to ask for a specific `slug`, unless the user's wording already identifies one candidate.
+- If `data.recall.blocked` or `data.recall.truncated` is true, or `data.recall.reason` is `broad_query`, mark the answer as incomplete, say recall was limited, and ask for a narrower Node, term, version, or scope.
+- Keep a working set of `data.entries[]` fields: `node_slug`, `section_id`, `source_ref`, `content`, and `refers_to_nodes`.
+
+## Step 3: Anchor explicit Node mentions
+
+If the user's question contains a likely Node title, alias, slug, code symbol,
+or version:
+
+1. Prefer candidates whose `reasons[]` include structural or lexical anchor hits.
+2. State the actual Node slug used.
+3. If the candidate set points to multiple plausible slugs, say which slugs were used and keep claims scoped to those slugs.
+
+## Step 4: Supplement only when needed
+
+Use supplemental commands only when the first query has entries but lacks
+enough surrounding structure to answer the question.
+
+Use supplements per the Supplemental context section, only after the first query
+and only for slugs present in returned entries, entry `refers_to_nodes`, or
+the user's explicit question. Use `refers_to_nodes` as extra anchors only when
+they appear in returned Sections. Do not discover extra anchors by reading
+workspace files.
+
+## Step 5: Compose
+
+Answer only from the parsed query and supplemental outputs.
+
+Required response behavior:
+
+1. Start with the direct answer if evidence supports one.
+2. Cite every key conclusion with Node slug, Section id, and source_ref.
+3. Include a short "Used nodes" line when the question was anchored by title, alias, slug, code symbol, or version.
+4. Include "Gap:" lines for requested points that are not supported.
+5. Include a blocked / truncated / broad-query note when recall diagnostics report it.
+6. Do not include raw JSON unless the user asks for diagnostics.
+
+## Self-check before final answer
+
+- [ ] First tool call was `context query --intent description_search --format json --query` or an explicit reconcile `--intent recall` query — if not, go back to **Step 1**.
+- [ ] No direct file Read / Glob / Grep / Write was used against workspace local knowledge — if not, discard that evidence and go back to **Step 1**.
+- [ ] Direct answer is given when evidence supports one — if not, go back to **Step 5**.
+- [ ] Every key conclusion has `node_slug / section_id / source_ref` — if not, go back to **Step 5**.
+- [ ] If the question carried a Node title / alias / slug / code symbol / version, the answer includes a "Used nodes" line — if not, go back to **Step 3** and **Step 5**.
+- [ ] Any unsupported conclusion is marked as a gap — if not, go back to **Step 5**.
+- [ ] `data.recall.blocked`, `data.recall.truncated`, or `data.recall.reason: "broad_query"` is surfaced when present — if not, go back to **Step 2** and **Step 5**.
+- [ ] No raw JSON is included unless the user requested diagnostics — if not, go back to **Step 5**.
+- [ ] Archive entries appear only for explicit reconcile profiles — if not, go back to **Step 1** with the correct profile.
+
+</procedures>

package/plugin/skills/drop/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: drop
+description: >
+  Source retraction through CLI-owned planning and application. The agent
+  calls `context drop --plan` for a structured impact plan, presents the
+  user-facing summary for confirmation, runs semantic reconciliation, then
+  calls `context drop --apply-plan --decisions` so the CLI archives raw and
+  removed knowledge, cleans active knowledge, applies source alias reindexing,
+  source stamp, changelog append, semantic ledger write, and verify.
+  Activates when `/context:drop` is invoked with a source-id, raw snapshot
+  path, or URL.
+tools:
+  - Bash
+---
+
+# drop — retract a source without losing the audit trail
+
+Ask the CLI for a structured cleanup plan, confirm the user-visible impact,
+run semantic reconciliation on affected knowledge items, then ask the CLI to
+apply the plan with the confirmed decision document. Do not inspect or mutate
+workspace files directly.
+
+`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
+
+- Plan + semantic prepare/review + apply are CLI-owned. The agent only presents the plan, asks semantic questions when required, and waits for confirmation.
+- Drop removes affected raw / unsupported knowledge from the active workspace and stores them under `archive/` for restore/audit.
+- Do not Read / Glob / Grep / Write anything under `WORKSPACE_DIR`; all impact analysis and mutation must go through `context drop --plan`, `context reconcile prepare --mode drop`, `context reconcile review`, and `context drop --apply-plan --decisions`.
+- `context drop --plan <source-id|raw-path|url> --format json` resolves source-id, computes affected topics / knowledge items, and reports alias reindex impact.
+- `context drop --apply-plan <plan-file> --decisions <decisions-file> --reason "<text>" --yes` archives affected active content, consumes semantic decisions, removes unsupported Sections / empty Nodes from active knowledge, applies source alias reindexing, writes the semantic ledger, source stamp, changelog append, and verify.
+- User confirmation required unless `--yes` was passed; abort on any non-`y` answer without writing. `--yes` does not skip semantic `ask_user` questions.
+- Confirmation prose follows `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/user-question-contract.md`: describe affected topics and claims, not source-ref mechanics.
+- Source evidence, section, and verify rule meanings stay anchored to `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md`.
+- Output language: impact plan + report match the user's language; CLI commands, flag names, source-ids, comment attributes stay English.
+
+<reference>
+
+## Plan fields
+
+The JSON plan has:
+
+| Field | Meaning |
+|---|---|
+| `source_id` | Canonical source id resolved from user input |
+| `resolved_from.kind` | `source-id`, `snapshot-path`, or `url` |
+| `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 |
+| `unaffected_references[]` | Topic relationships that mention affected topics but are not source evidence |
+| `summary` | Counts for confirmation and changelog |
+
+## User-facing impact summary shape
+
+```
+Affected: N topics · M knowledge items
+
+  <topic title>
+    "short claim preview" → remove from active knowledge and archive
+    "short claim preview" → keep, supported by another source document
+  <topic title>
+    "short claim preview" → remove from active knowledge and archive
+
+Proceed? [y/N]
+```
+
+Keep the internal node slug, Section id, and source-ref patch data in your
+working notes for Step 4; show them only if the user asks for implementation
+details.
+
+## CLI shapes
+
+```
+context drop --plan <source-id|raw-path|url> --format json
+context reconcile prepare --mode drop --drop-plan <plan-file> --format json
+context reconcile review --context <context-file> --decisions <decisions-file> --format json
+context drop --apply-plan <plan-file> --decisions <decisions-file> --reason "<text>" --yes
+```
+
+The apply command writes a source-specific archive under `archive/sources/`,
+moves affected raw out of active `raw/`, consumes semantic decisions for
+reanchor / remove_unsupported / split_then_reanchor, removes unsupported
+Sections / empty Nodes from active `knowledge/`, flips the source registry entry to
+`status: dropped`, stamps `drop_reason` + `dropped_at` + `archive_path`,
+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.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Parse arguments
+
+From `$ARGUMENTS`: `<source-id|raw-path|url>` (required), `--reason <text>` (optional), `--yes` (optional). If the target is missing, stop and ask for the source id or raw snapshot path. If the reason is missing but the user's wording gives a clear reason, infer a concise reason such as `用户主动撤回`; otherwise collect it before Step 4.
+
+### Step 2 — Ask CLI for a plan
+
+Run `context drop --plan <source-id|raw-path|url> --format json`. Do not inspect
+workspace files yourself. If the CLI reports source-not-found or
+source-already-dropped, relay the error and stop.
+
+### Step 3 — Present the impact plan
+
+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
+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.
+
+### Step 4 — Reconcile affected knowledge
+
+Write the exact plan JSON to a temporary file outside `WORKSPACE_DIR`, then run:
+
+```
+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
+from `ask_user` into one of `reanchor`, `remove_unsupported`, or
+`split_then_reanchor` before continuing. Do not let `--yes` bypass this step.
+
+### Step 5 — Apply the plan
+
+Write the exact plan JSON and confirmed semantic decision document to temporary
+files outside `WORKSPACE_DIR`, then call:
+
+```
+context drop --apply-plan <plan-file> --decisions <decisions-file> --reason "<text>" --yes
+```
+
+Do not call `context mdrive section ...` or `context mdrive node ...` for the
+standard drop flow; `drop --apply-plan --decisions` owns cleanup, ledger write,
+and verify.
+
+### Step 6 — Report
+
+The apply command already verifies. Run `context source get <source-id>` and
+report in the user's language: topics affected, knowledge items marked
+archived/removed from active knowledge, source alias reindex count, archive
+path, changelog timestamp.
+
+### Step 7 — Self-verify
+
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any was used, restart from **Step 2** with CLI-only flow.
+- [ ] `context drop --plan` succeeded before asking the user — if not, **Step 2**.
+- [ ] `context reconcile prepare --mode drop` was run from the exact drop plan — if not, **Step 2**.
+- [ ] `context reconcile review` returned zero `questions[]` before apply; if any question remains, ask the user and regenerate the decisions document.
+- [ ] User confirmed unless `--yes` was passed — if not, abort without writing.
+- [ ] `context drop --apply-plan` exited 0 — if not, surface the CLI error and stop.
+- [ ] `context source get <source-id>` shows the source as dropped — if not, surface the mismatch.
+- [ ] The reported source entry includes `archive_path` — if missing, surface the mismatch.
+
+</procedures>