@c4a/context-cli 0.5.29-alpha.2 → 0.5.29-beta.17

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

@@ -0,0 +1,409 @@
+---
+name: skill-compile-draft
+description: >
+  Packaged skill invoked by `/context:compile`; not a user slash command. For one Node at a time, reads
+  the CLI-provided `NodeContext` (planned metadata, raw snippets, and
+  existing Sections if any), classifies every raw fragment into a Section
+  kind via the priority chain, writes content + detail + `source_refs[]`,
+  and emits a compile draft JSON document. The CLI
+  validates the actions via `context compile --draft <slug> --input - --plan`.
+  Activates when `/context:compile` iterates across the confirmed align plan.
+tools:
+  - Bash
+---
+
+# skill-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. Finish the current Node's draft quality checks before the caller moves to another Node's review/apply loop.
+- Agent emits JSON only; no markdown, no direct workspace file writes. The caller passes the JSON to `context compile --draft <slug> --input - --plan --prepare`; the CLI stores workflow payloads. `--save-input` is only for an explicit debug scratch copy.
+- Default compile sends changed-only NodeContext. Treat `raw_snippets[]` as the complete evidence boundary; never use direct workspace file tools to expand it.
+- Use `raw_snippet_indexes.citation_eligible` as the citeable evidence set; `raw_snippet_indexes.context_only` and every secondary shared snippet are background only. `request_full_text` may expose full secondary text for inspection, but it does not make that snippet citation-eligible. If a secondary shared block is needed as evidence, emit `pending_ownership_challenge` or `structure_challenge`; do not cite it. If the NodeContext is too large and only citation handles are needed, ask the caller to use `context compile --source-refs <slug> --format json` and cite from `citation_refs[]`; do not slice the saved NodeContext with ad-hoc scripts.
+- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect or preprocess `WORKSPACE_DIR`, `.context`, NodeContext scratch files, or `/tmp` workflow artifacts.
+- 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.
+- `incremental.locator_only_changes[]` entries have `agent_action: "none"` and `handled_by: "compile-close"`; do not emit draft actions for those Sections unless the same Section also has a real `changed_blocks[]` content change.
+- Actions are candidate write actions, not final semantic decisions. If raw appears similar to existing knowledge, add only a `reconcile_hint`; the semantic reconcile procedure may ignore it.
+- For `node.type: "action"`, use `node.action_gate` as the compile boundary. Actor, goal/outcome, repeatability, answerability, trigger, step, and phase claims must come from cited `raw_snippets[]` or structured `action_gate.inference_sources`; if `trigger_blocks` is empty, do not invent a trigger.
+- For `node.type: "domain"`, treat `node.domain_gate` as grouping metadata only. It can explain why child Nodes belong under the Domain, but it is not evidence for a Section unless the same fact appears in citation-eligible raw snippets.
+- Note snippets are captured conversation material. `raw_snippets[].note_intent`, `anchored_to[]`, and `revision_kind` are prioritization hints only: they may suggest update / supersede / complement / skip, but they never authorize a write without semantic review.
+- Source support passing is not completion. Before emitting, estimate coverage from the provided `raw_snippets[]`: if there are 3+ citation-eligible snippets, a one-action draft is valid only when the later snippets are duplicates, navigation, placeholders, or continuations of the same fact. Small dense docs still need multiple actions when later snippets state distinct capabilities, constraints, examples, risks, FAQ, or usage notes. Large manuals/design docs should compile to several orthogonal actions in the same draft. Do not switch into "speed mode" because the first action validates; coverage is part of the draft task.
+- Pick `kind` from the form of the cited raw block: code / config / command sample → `example`; verifiable rule with a check method → `spec`; stable invariant, design rule, or core mechanism → `principle`; ≥2 subjects × ≥2 dimensions → `comparison`; explicit risk or caveat → `warning`; Q+A pair → `faq`; real incident with timeline → `incident`; versioned change record → `changelog`. Reach `description` only when none of those forms fit — narrative that defines an entity, explains a mechanism, or summarises a stance. First matching form wins.
+- `kind × node.type` must satisfy the CLI Section mount matrix; mismatches get rejected at write time. When the strongest kind is blocked by mount matrix, fall to the next legal kind whose form actually fits — do not collapse to `description` just because it mounts everywhere, and do not invent thin precision (e.g. one-line `spec`) just to avoid `description` either. See [Description anti-abuse gates](#description-anti-abuse-gates) for the classification checks at the description boundary.
+- Every write action cites raw via `source_refs[]`, choosing values from `raw_snippets[].source_ref`. Use a single-element array for one citation. Treat each source ref as an opaque citation token; never fabricate, parse, dereference, or cite navigation-only blocks as evidence for a content Section.
+- `content` ≤256 chars; long prose goes in `detail`. If a cited raw sentence is already short, single-line, and readable, use it with `content_mode: "extract"` instead of asking AI to summarize it. Do not compress 200 readable characters into a 180-character paraphrase just to make it look rewritten.
+- `detail` is not an evidence echo field. Do not copy raw evidence into `detail`, do not prefix detail with labels such as `原文:`, and do not use detail only to show the raw quote. Raw evidence is traceable through `source_refs[]`.
+- For `example` Sections, if the cited raw snippet contains command / config / code fences, keep `content` as a short summary and preserve the relevant fenced block in `detail`; do not collapse copyable examples into prose-only summaries unless semantic review asks the user and the user accepts that compression.
+- Preserve documentation/reference URL blocks. If a cited raw block is primarily links (官网 / docs / reference / related links), create a small `description` Section such as "相关链接" and put every URL in `detail`; do not drop link-only evidence just because it is not prose.
+- 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, existing Sections, or the current align plan; 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.
+- If a note or raw snippet was reviewed and should intentionally not write active knowledge, emit `skip` with `source_refs[]` from that exact snippet. This lets semantic review record `reviewed_no_write`; a bare skip is only for deterministic no-op cases such as unchanged input or navigation-only context.
+- Any Node may legitimately compile to no Sections when the provided snippets contain only navigation (`Parent` / `Children` / `Related` / `Relations`) or placeholder text that explicitly says no detailed content is available. Emit `skip`; do not turn align summaries, parent/child lists, sibling links, or placeholders into `description` Sections. The align graph and Node metadata preserve structure; active Sections need citation-eligible content.
+- FAQ collections attach to the most specific finalized Node (Entity → Action → Domain fallback); never create a standalone FAQ container.
+- Output language: `content`, `detail`, Node-facing summaries, and user-facing draft explanations follow `NodeContext.generation_policy.language` when present; otherwise match the raw material. Preserve product names, code identifiers, CLI flags, slugs, `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
+- Stable output: keep action order aligned with evidence order, keep object fields in the documented schema order, omit empty optional fields, and do not add current timestamps, random ids, scratch paths, or host paths. Fixed rules and schema come from this skill; only the current NodeContext should vary between repeated Node draft calls.
+
+<reference>
+
+## Input — `NodeContext`
+
+```jsonc
+{
+  "node": {
+    "slug": "...", "type": "entity|action|domain",
+    "tags": [...], "title": "...",
+    "sources": ["..."], "aliases": ["..."], "summary": "...",
+    "planned_sections": ["spec", "..."],
+    "action_gate": {
+      "actor_blocks": ["b0002"],
+      "trigger_blocks": [],
+      "goal_blocks": ["b0003"],
+      "step_blocks": ["b0004"],
+      "outcome_blocks": ["b0005"],
+      "repeatability_or_plan_blocks": ["b0006"],
+      "inference_sources": {
+        "actor": { "source_type": "explicit-block", "evidence_blocks": ["b0002"], "rationale": "..." },
+        "outcome_or_goal": { "source_type": "explicit-block", "evidence_blocks": ["b0003"], "rationale": "..." },
+        "repeatability_or_plan": { "source_type": "explicit-block", "evidence_blocks": ["b0006"], "rationale": "..." },
+        "answerability": { "source_type": "ref-node", "ref_nodes": ["..."], "rationale": "..." }
+      }
+    },
+    "domain_gate": {
+      "scope_blocks": ["b0001"],
+      "child_refs": ["..."],
+      "grouping_reason": "..."
+    }
+  },
+  "generation_policy": {
+    "language": "Chinese",
+    "source": "workspace.language",
+    "applies_to": ["node.title", "node.summary", "section.content", "section.detail", "user_facing_report"],
+    "instruction": "Generate knowledge titles, summaries, Section content/detail, and user-facing reports in Chinese; preserve product names, code identifiers, CLI flags, source_ref tokens, slugs, and quoted evidence exactly when needed."
+  },
+  "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@ab12cd34ef56",
+        "refers_to_nodes": [...] }
+    ]
+  },
+  // Default NodeContext does not expose raw file paths. Copy raw_snippets[].source_ref
+  // into draft source_refs[]; identify blocks via source_id + block_locator_id (or block_hash).
+  "mentions":      [ { "line": 12, "quote": "...", "source_id": "local:billing", "block_locator_id": "h2-api" } ],
+  "raw_snippets":  [ { "line": 10,
+                       "line_range": [10, 18],
+                       "source_ref": "src-1#api L10-18@ab12cd34ef56",
+                       "quote": "...context block...",
+                       "mention_quote": "...",
+                       "source_type": "local|feishu|note",
+                       "source_id": "local:billing",
+                       "note_intent": "revision|decision|brainstorm",
+                       "anchored_to": [{ "node_slug": "...", "section_id": "section-1" }],
+                       "revision_kind": "replace|clarify|...",
+                       "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" } ],
+    "locator_only_changes": [ { "source_id": "local:billing", "agent_action": "none", "handled_by": "compile-close", "affected_sections": ["section-3"] } ],
+    "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 --scan-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.
+When `source_type` is `note`, the snippet came from `context capture --note`.
+Use `note_intent`, `anchored_to[]`, and `revision_kind` to decide which
+existing Section to compare first. They are routing hints, not proof that the
+note should be written as active knowledge.
+`node.sources[]` are the only sources that can be cited as `src-N`.
+`node.context_sources[]` may contribute `raw_snippets[]` for comparison or
+background, but they are context-only and must not be cited unless the CLI has
+also placed that source in `node.sources[]`.
+`node.action_gate` is present only for finalized Action Nodes. Use it to avoid
+inventing process semantics: write triggers only when `trigger_blocks` or cited
+raw explicitly provide them; write actor / outcome / repeatability claims only
+from cited raw or the matching structured `inference_sources` entry. If
+`answerability` depends on `ref_nodes`, use `refers_to_nodes[]` or a local link
+hint instead of describing another Node's internals.
+`node.domain_gate` is present only for finalized Domain Nodes. It is grouping
+metadata for scope and children; do not turn `grouping_reason` into a Section
+unless citation-eligible raw snippets state the same claim.
+
+## Output — Compile Draft JSON
+
+```jsonc
+{
+  "schema_version": "compile.draft.v2",
+  "target_node": "<matches node.slug>",
+  "actions": [
+    { "op": "add", "kind": "spec",
+      "content": "...", "detail": "...",
+      "refers_to_nodes": ["..."],
+      "source_refs": ["src-1#api L10-14@ab12cd34ef56"],
+      "content_mode": "extract",
+      "basis_spans": [
+        { "source_ref": "src-1#api L10-14@ab12cd34ef56" }
+      ]
+    },
+    { "op": "update", "target_section_id": "section-3",
+      "content": "...", "detail": null,    // null clears detail
+      "refers_to_nodes": null,
+      "source_refs": ["src-1#api L18-21@cd34ef56ab78"],
+      "content_mode": "minimal_paraphrase",
+      "paraphrase_reason": "fragment_fix",
+      "basis_spans": [
+        { "source_ref": "src-1#api L18-21@cd34ef56ab78" }
+      ] },
+    { "op": "supersede", "target_section_id": "section-5",
+      "reason": "raw published a new retention value",
+      "new": { "kind": "spec", "content": "...", "detail": "...",
+               "refers_to_nodes": ["..."],
+               "source_refs": ["src-1#limits L30-34@ef56ab78cd90"],
+               "content_mode": "extract",
+               "basis_spans": [
+                 { "source_ref": "src-1#limits L30-34@ef56ab78cd90" }
+               ] } },
+    { "op": "deprecate", "target_section_id": "section-2", "reason": "..." },
+    { "op": "skip", "reason": "no new evidence in raw snippets" },
+    { "op": "skip", "reason": "reviewed; intentionally not written",
+      "source_refs": ["src-1#note L4-8@ab12cd34ef56"] },
+    { "op": "structure_challenge",
+      "challenge_id": "ch_0001",
+      "kind": "missing_action_node",
+      "node_slug": "<matches node.slug>",
+      "action_tag": "rollout-runbook",
+      "summary": "The cited evidence is a repeatable procedure.",
+      "source_ref": "src-1#ops L40-55@cd34ef56ab78",
+      "reason": "Align must review structure before compile writes process prose." },
+    { "op": "structure_challenge",
+      "challenge_id": "ch_0002",
+      "kind": "wrong_shared_block_split",
+      "node_slug": "<matches node.slug>",
+      "unresolved_target": "rollout-runbook",
+      "reason": "The finalized shared block split leaves this Node with only secondary, non-citable evidence." },
+    { "op": "pending_ownership_challenge",
+      "challenge_id": "och_0001",
+      "node_slug": "<matches node.slug>",
+      "block_id": "b0032",
+      "requested_role": "shared",
+      "reason": "A visible context_only or secondary shared block contains facts that need citation." }
+  ]
+}
+```
+
+`source_refs[]` values are copied from `raw_snippets[].source_ref`; a single
+citation is still written as a single-element array. Submitting singular
+`source_ref` or quoted-evidence fields is rejected with canonical repair hints.
+Every Section write (`add`, `update` with content/detail/source refs, and
+`supersede.new`) must include `content_mode` plus `basis_spans[]`. Use
+`content_mode: "extract"` when the cited raw sentence already fits the
+single-line content contract and you keep the original sentence order. If you reorder
+sentences, merge sentences with new punctuation, or consolidate bullets, use
+`content_mode: "minimal_paraphrase"` with the matching `paraphrase_reason`. Use `content_mode: "minimal_paraphrase"` only
+when direct extract would be malformed, too broad, duplicated, or needs
+multi-span consolidation; include `paraphrase_reason`.
+Do not mark sentence 1 + sentence 3 from the same evidence block as
+`extract`; non-contiguous copies are `minimal_paraphrase` even when every word
+came from raw evidence.
+`structure_challenge` and `pending_ownership_challenge` do not write Sections;
+the CLI stores them as workflow payloads and close exposes them as debt until
+align resolution handles them. Supported structure challenge kinds include
+`missing_action_node`, `extra_action_node`, `wrong_shared_block_split`,
+`missing_depends_on_edge`, and `wrong_parent`.
+
+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 semantic reconcile decisions.
+
+## Confidence rubric
+
+Four legal values; pick per raw evidence strength.
+
+| `confidence` | When |
+|---|---|
+| `verified` | Raw shows the fact already happened or held — recorded run output, observed metric value, incident timestamp, benchmark result, or explicit "ran X, got Y" log. Executable form alone is not enough; without execution evidence, downgrade to `confirmed`. |
+| `confirmed` | Raw states the fact in normative voice or as a documented spec / config / example, without showing the run that confirmed it. This is the default for code blocks, configuration samples, feature lists, and design rules. |
+| `inferred` | You combined ≥2 raw fragments into a load-bearing conclusion that no single fragment states. |
+| `speculative` | Raw only hints; the Section is a best-effort reading that may not survive review. |
+
+Don't game the rubric. Compile-close flags Nodes dominated by `speculative` Sections, and a Node whose Sections are uniformly `verified` despite raw containing only specs / samples is the symptom of a misread rubric, not strong evidence.
+
+## Description anti-abuse gates
+
+`description` is the kind for narrative claims that do not match any other form. Before locking in `kind: description` for a snippet, run three classification checks against the cited block:
+
+1. **Atomicity**: single narrative, or multi-step / multi-row / multi-config? Multi → split into the right kinds — each step into its own `spec` / `warning`, each row into a `comparison` Section, each config block into `example` (sample) or `spec` (constraint with a check method).
+2. **Kind-precision**: does a higher-priority kind fit better? A comparison table belongs in `comparison`; a verifiable rule belongs in `spec`; a stable design rule, core mechanism, or "X is the key to Y" claim belongs in `principle`; a code / config / command block belongs in `example`; explicit risks belong in `warning`; a Q+A pair belongs in `faq`; a real incident with timeline belongs in `incident`.
+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 this skill.
+
+A Node whose raw is genuinely narrative — definitions, summaries, plain prose without enumerations or normative wording — legitimately ends with description-dominant output. The smell fires the other way: when raw contained enumerations, normative rules, or code blocks, and the draft collapsed them to `description`. Redraft from Step 2 in that case, not from a percentage threshold.
+
+Navigation-only exception: if a Node's evidence is only a child list, relation navigation, sibling link, parent pointer, or placeholder wording, emit `skip`. The Node remains useful through align graph edges, `## Contains` / `## Related`, and metadata; a navigation-only snippet is not evidence for a `description` claim. The Node `summary` is metadata for context and listings, not a Section or a required lead paragraph.
+
+## 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 preserves explicit
+cross-Node references for query answers and citations without rewriting
+the claim. Slugs come from existing Sections, the context glossary, or Nodes already declared by the current align plan; never invent one. A
+Section can reference multiple Nodes (common on `comparison` /
+`decision`).
+If the CLI returns `compile-missing-refers-to-node`, treat it as advisory:
+add the suggested slug only when the Section actually depends on that Node;
+otherwise leave the draft unchanged and rely on the cited `source_ref`.
+
+## 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 mechanism or term | The matching Entity |
+| About an action / flow | That Action |
+| Cross-topic / generic workspace FAQ | Domain (fallback only) |
+
+Never manufacture a FAQ container Node. 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 CLI 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.
+Estimate coverage from the provided `raw_snippets[]` before writing actions. Treat "the first quote is supported" as only a validation result, not a completion signal.
+
+If `node.type` is `action`, inspect `node.action_gate` before classification:
+
+- `step_blocks` / `phase_blocks` / cited step snippets can produce `spec` or `example` Sections for procedure content.
+- `actor_blocks`, `goal_blocks`, `outcome_blocks`, and `repeatability_or_plan_blocks` can support concise `description` / `spec` Sections when the same source refs are citation-eligible.
+- Empty `trigger_blocks` means no trigger was finalized; write goal or applicability if supported, but do not add a trigger sentence.
+- `inference_sources.answerability.ref_nodes` should become `refers_to_nodes[]` when the current Section depends on those Nodes; do not summarize those Nodes' facts here.
+
+If `node.type` is `domain`, inspect `node.domain_gate` only to understand scope and child grouping. It does not authorize new Section facts by itself.
+
+Coverage self-check:
+
+1. Count citation-eligible, non-navigation snippets and group them by `block_locator_id` heading prefix.
+2. For 3-11 such snippets, read each snippet once. If later snippets are distinct facts, emit separate actions before moving to the next Node. Do not stop after one supported description just because the file is short.
+3. For roughly 12+ citation-eligible snippets or 5+ distinct locator areas, plan multiple Sections in this single draft. Large manuals/design docs usually need several orthogonal actions.
+4. This is not a quota: skip duplicates, navigation-only blocks, placeholders, and unsupported fragments. The goal is coverage of distinct source-backed knowledge, not maximum Section count.
+5. If `context reconcile prepare` returns `compact-source-low-coverage` or `dense-source-low-coverage`, revise the same draft to cover the suggested uncovered evidence candidates before review/apply. Do not treat those warnings as ignorable polish.
+
+### Step 2 — Classify each raw snippet
+
+For each `raw_snippets[]` entry:
+
+1. If `source_type` is `note` and `anchored_to[]` names this Node or Section, compare it against the target first. A revision/decision note usually becomes `update`, `supersede`, `add` as complement, or `skip`; do not create a new Node from the note title here. If the note says not to modify active knowledge yet, or the correct outcome is no-write after review, use `skip` with `source_refs[]` containing the note's `raw_snippets[].source_ref` so the semantic ledger can record it as reviewed.
+2. If the snippet only contains navigation or placeholder evidence (`Parent` / `Children` / `Related` / `Relations`, sibling links, "no detailed content", etc.), emit `skip`. Do not create a Section whose content is just "Children: ..." or "Related: ..." and do not summarize facts that are not present in the snippet.
+3. Walk the Section kind priority chain from the TL;DR classification rule; stop at the first kind whose trigger fires.
+4. 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.
+5. If you land on `description`, walk the [Description anti-abuse gates](#description-anti-abuse-gates). Any gate fires → split or `skip`.
+
+For dense documents, group nearby snippets by their `block_locator_id` heading prefix and write one action per coherent fact group. Repeated `#` headings inside one source are often internal chapters of the current Node; keep them as Sections unless the raw evidence establishes a separate durable Node identity.
+
+### Step 3 — Reconcile with existing Sections
+
+For each existing Section:
+
+- Raw still supports it unchanged → emit nothing (or one summarising `skip`).
+- Raw clarifies or rephrases 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. Split the cited block into `content` and `detail` so the Section is independently addressable in retrieval. `content` (≤256 chars) carries the Section's identity — for `example` / `spec` / `incident` that is the load-bearing identifiers the cited block hinges on (command name, key flags, field names, distinguishing values, mode names, error codes); for `principle` / `description` / `decision` / `comparison` / `warning` / `faq` / `changelog` it is the claim itself in raw's own terms. If the raw sentence already fits this shape, keep it as an extract instead of summarizing it. `detail` carries active knowledge that cannot fit in `content`, especially copyable code/config/URL/table material. Prefer splitting prose into separate supported Sections over storing a raw prose quote in `detail`. Do not put the raw evidence itself into `detail` as a "source copy"; the rendered Section already carries source_ref, and the CLI can resolve the raw evidence from that token.
+2. Keep `content` and `detail` faithful to the cited raw terms: do not introduce acronyms, abbreviations, translations, or aliases that do not appear in the cited raw snippet unless raw itself defines the equivalence or the user confirms it later during semantic review.
+3. If the cited block contains documentation/reference URLs, preserve them in `content` or `detail`. Link-only blocks are still useful knowledge; use `kind: description` with a concise "相关链接" identity when no more specific kind applies.
+4. Omit `confidence` for ordinary confirmed claims. Assign `confidence` per the [Confidence rubric](#confidence-rubric) only when the evidence is not confirmed.
+5. Fill `refers_to_nodes[]` per [Glossary and refers_to_nodes](#glossary-and-refers_to_nodes).
+6. Cite evidence with `source_refs[]`, picking values from `raw_snippets[].source_ref`. When one Section summarizes contiguous multi-block evidence, list every relevant source ref in order under `source_refs[]`; the CLI verifies that the refs can collapse to one canonical citation token. If the evidence is non-contiguous or contains separable claims, split the draft into separately cited actions instead of stretching one action across unrelated blocks. For `skip`, include `source_refs[]` only when the skip represents reviewed no-write material; omit evidence for purely deterministic no-ops such as unchanged input. Never submit singular `source_ref` or quoted-evidence fields; the CLI rejects them.
+7. Add the extractive contract to every Section write: `content_mode`,
+   `basis_spans[]`, and `paraphrase_reason` when `content_mode` is
+   `minimal_paraphrase`. Each `basis_spans[]` entry contains only
+   `source_ref`; the CLI resolves cited text and computes the audit basis
+   internally. When one short basis span is already a valid `content`, choose
+   `content_mode: "extract"`.
+8. If evidence implies a missing Action, missing `depends_on`, wrong parent, or
+   needed ownership upgrade from `context_only`, emit the corresponding
+   challenge action instead of forcing the content into a Section.
+   `pending_ownership_challenge.requested_role` is `owned` or `shared`.
+
+Rendered knowledge uses the short claim as the visible blockquote and renders
+`detail` as a collapsed Details block under that claim. A reader should be able
+to understand the Section from `content` first; `detail` is supporting active
+knowledge, not a hidden evidence copy.
+
+### Step 5 — Emit the JSON
+
+Emit one compile draft JSON document for the caller to pass to `context compile --draft <slug> --input - --plan --prepare`. 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 action's `source_refs[]` entries appear in `raw_snippets[].source_ref` for this NodeContext, and no action carries singular `source_ref` or quoted-evidence fields — if not, **Step 4**; pick the right source ref, split non-contiguous claims, or use `skip` only when raw has no write-worthy fact.
+- [ ] Every Section write has `content_mode` and `basis_spans[]`; every
+      `minimal_paraphrase` has `paraphrase_reason` — if not, **Step 4**.
+- [ ] Short, readable, single-line evidence was not rewritten just for style. If it already fits `content`, switch to `content_mode: "extract"` — if not, **Step 4**.
+- [ ] `content` does not add new hard terms, acronyms, abbreviations, translations, URLs, code literals, versions, or aliases absent from the cited raw snippet — if it does, either use the raw wording, move the extra explanation into a user-confirmed decision later, or **Step 4**.
+- [ ] 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 citation-eligible raw URL block is either preserved in a Section or intentionally skipped with evidence and reason; if not, **Step 4**.
+- [ ] Dense raw material was not collapsed into one broad Section. If `raw_snippets[]` spans many locator areas and only one write action exists, return to **Step 2** unless the remaining snippets are duplicates, navigation-only, or already covered by existing Sections.
+- [ ] Every `update` / `supersede` / `deprecate` targets a known `section-N` — if not, **Step 3**.
+- [ ] `refers_to_nodes[]` only contains slugs from `existing` / glossary / current align plan — if not, **Step 4**.
+- [ ] When the Node ended description-dominant, verify raw was genuinely narrative (no enumerations, no normative wording, no code/config blocks). If raw contained any of those forms and they were collapsed to `description`, redo classification from **Step 2**. Do not invent unsupported precision Sections for ratio reasons.
+- [ ] When raw adds nothing, exactly one `op: skip` with a reason; not `actions: []`.
+- [ ] When raw only has navigation/placeholder evidence, use `skip`; do not add a low-value Section from `Parent` / `Children` / `Related` / `Relations` lines.
+- [ ] When `skip` means "reviewed but intentionally not written", it includes `source_refs[]` from the relevant note/raw snippet so review can persist no-write status.
+- [ ] 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.
+- [ ] No ad-hoc script or shell file traversal was used against `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts — if any, restart from the CLI-provided NodeContext.
+
+</procedures>

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

@@ -0,0 +1,184 @@
+---
+name: skill-context-query
+description: >
+  Packaged skill invoked by `/context:query`; not a user slash command. The agent uses
+  `context query` hit/miss/select results first, supplements only with scoped
+  query views when needed, and answers with Node slug, Section id,
+  and compact node/section 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:
+  - Bash
+---
+
+# skill-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 evidence-bearing tool call should be the ordinary default query: `context query "$ARGUMENTS"`. One optional `context query --intent orientation` or empty `context query` call may run before it when this conversation has no usable workspace map; orientation is only for choosing a better query/scope and is never evidence for the answer.
+- 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 the returned `node` and `section` handles. Default query output intentionally omits source provenance; do not invent or parse source locators.
+- If returned entries do not support a conclusion, mark it as a gap. Do not turn missing local knowledge into a definite answer.
+- If the output asks for a narrower scope or shows multiple candidate slugs, choose one only when the user's wording makes it unambiguous; otherwise ask the user which `slug` to use.
+- If the output reports a broad, blocked, or truncated recall, follow that diagnostic: ask for a narrower Node, term, version, or scope; when entries are returned but truncated, answer from those entries and state the result is not exhaustive.
+- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts.
+- 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, output column names, slugs, and Section ids stay as printed.
+
+<reference>
+
+## Evidence Shape
+
+Primary evidence comes from the default `context query` output. Treat each
+returned row as a small evidence card.
+
+| Column / text | Use |
+|---|---|
+| `node` | Required citation handle for Section rows |
+| `section` | Required citation handle for Section rows |
+| `kind` | Section kind; use it to avoid overstating description/spec/warning content |
+| `content` | Evidence text for answer claims |
+| `refers_to_nodes` | Optional supplemental anchors when present |
+| `slug` | Candidate handle when the output is asking you to choose a Node |
+| `message` | Miss, broad-query, blocked, or narrowing guidance |
+
+Supplemental context can come from:
+
+```text
+context query --intent node_search --scope <slug>
+context query --intent impact_analysis --scope <slug>
+context query --intent node_search --refers-to <slug>
+```
+
+## Answer citation shape
+
+Use compact citations next to each key claim:
+
+```text
+<claim> [node / section]
+```
+
+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.
+
+If the current conversation has no useful workspace map and the user's question
+is broad, ambiguous, or asks what can be queried, run one orientation pass before
+the first evidence query:
+
+```bash
+context query --intent orientation
+```
+
+Empty `context query` returns the same orientation map.
+
+Orientation returns directly queryable slug/title structure and one query
+template. Use it only to choose a scope or show the user what can be queried.
+Do not answer from orientation output. Do not cite orientation output.
+
+If the user already asked a concrete question but this conversation has no
+workspace map, you may run `context query --intent orientation` (or empty `context query`) and the first
+ordinary `context query "$ARGUMENTS"` concurrently. Use the evidence
+query for the answer; use orientation only for scoped follow-up if the first
+query is insufficient.
+
+Run the ordinary query first:
+
+```bash
+context 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 --profile reconcile-dedupe --query "$ARGUMENTS"
+```
+
+Do not use recall archive profiles for ordinary questions.
+
+## Step 2: Read and gate
+
+Read the command output before answering.
+
+- If the command fails, report the CLI failure and stop.
+- If the output says `miss` or no local knowledge matched, report no local knowledge hit and stop.
+- If the output shows candidate slugs instead of evidence rows, ask for a specific `slug`, unless the user's wording already identifies one candidate.
+- If the output reports broad or blocked recall, stop and ask for a narrower Node, term, version, or scope before treating missing candidates as evidence of absence.
+- If the output reports truncated recall, answer from the returned evidence when entries exist, mark coverage as non-exhaustive, and ask for narrowing only if the user needs a complete inventory.
+- Keep a working set of returned rows with `node`, `section`, `kind`, `content`, and non-empty `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 exact slug, title, or alias matches from the query result.
+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 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 and Section id.
+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 / broad-query note when recall hints require narrowing, or a truncated/non-exhaustive note when returned evidence is only a subset.
+
+## Self-check before final answer
+
+- [ ] First evidence-bearing tool call was ordinary `context query "$ARGUMENTS"` or an explicit reconcile `--intent recall` query. If an orientation command ran first or concurrently, it was only `context query --intent orientation` or empty `context query`, and an evidence-bearing `context query` command ran before answering — 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**.
+- [ ] No ad-hoc script or shell file traversal was used against `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts — 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 / section` — 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**.
+- [ ] Recall diagnostics are handled: broad/blocked asks for narrowing; truncated with entries answers with a non-exhaustive note — if not, go back to **Step 2** and **Step 5**.
+- [ ] Archive entries appear only for explicit reconcile profiles — if not, go back to **Step 1** with the correct profile.
+
+</procedures>