@c4a/context-cli 0.5.35-beta.1 → 0.5.36-beta.1

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

@@ -2,7 +2,7 @@
 name: skill-compile-close
 description: >
   Packaged skill invoked by `/context:compile`; not a user slash command. Runs after every draft
-  iteration. Triggers `context compile --close`, which in one invocation
+  iteration. Triggers `context compile close`, which in one invocation
   refreshes locator-only evidence, canonicalizes source refs, compacts and verifies the final workspace,
   rebuilds the knowledge index, appends a changelog
   entry, rebuilds section fingerprints + incremental cache, and
@@ -25,18 +25,18 @@ command. It does not hand-edit rendered knowledge.
 
 ## TL;DR — Non-negotiables
 
-- CLI-driven. `context compile --close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. Use the command's stdout + exit code; that's the close's full output.
+- CLI-driven. `context compile close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. Use the command's stdout + exit code; that's the close's full output.
 - **Agent NEVER edits rendered knowledge from the close stage.** The CLI is the sole writer for articles, the index, and the changelog. If verify reports an error here, route it back, not around:
   - Content / Section issues (`invalid-section-mount`, `body-ad-hoc-heading`, `dangling-source-alias`) → user re-runs `/context:compile` (draft loop fixes its own Section actions; the close stage does not patch)
   - Structural issues (`contains-cycle`, `edge-dangling-node`, `duplicate-slug`, `invalid-node-type`, `domain-same-file-child`) → user runs `/context:align` to revise the plan
   - Source issues (`dropped-source-reference`) → user runs `/context:drop <id>` to complete the drop
 - Exit 0 → summarise node/section totals, verify, `recompiled`, `locator_updates`, `rebuilt`, fingerprint rebuild count, archive status / archived file count, and any `ready_with_debt` coverage warnings when printed; then stop.
 - Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not hand-open the affected rendered article.
-- Coverage warning choice: `ready_with_debt` means close succeeded and unresolved coverage remains visible. First inspect `context workflow show --payload coverage-candidates --view coverage-summary --token-budget 2000 --unwrap --format json`; use each group's neutral `available_actions[]` and narrow with `--view coverage --type <issue-type>` or `--node <slug>` when needed. You may either continue with the warning recorded, or run an uncovered-only repair/skip round. If all unresolved candidates are intentionally excluded for the same reason, use `context compile --coverage-skip-unresolved --coverage-disposition-node <slug> --reason "<reason>"`; otherwise inspect `context schema coverage-disposition`.
+- Coverage warnings are CLI-owned diagnostics. `ready_with_debt` means close succeeded and unresolved coverage remains visible; report the warning and follow returned coverage view commands / `available_actions[]` only if the user chooses a repair or skip round.
 - Materialized knowledge means either a CLI-written knowledge article, or an explicit no-write placeholder from align: `planned_sections: []` plus source/context/graph support. A compile skip action records reviewed evidence, but it does not by itself materialize an arbitrary finalized Node.
-- Never re-run `context compile --draft` from close to paper over verify failures. Draft failures belong in the draft loop.
+- Never re-run `context compile draft` from close to paper over verify failures. Draft failures belong in the draft loop.
 - Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, knowledge files, or `/tmp` workflow artifacts.
-- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `compile --close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
+- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `context compile close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
 - LLM-assisted repair (`--fix-with-llm`) is not available in the current release.
 - Output language: summary prose matches the user's language; CLI output, issue codes, file paths stay as printed.
 - Successful close archives CLI scratch artifacts through the output lifecycle and rebuilds the user-level incremental cache. Current align state is internal CLI state, not a file protocol. The CLI owns this lifecycle — the agent must not move, delete, or archive workspace output files by hand.
@@ -44,7 +44,7 @@ command. It does not hand-edit rendered knowledge.
 
 <reference>
 
-## Stages inside `context compile --close`
+## Stages inside `context compile close`
 
 Close is one in-process command with one exit code:
 
@@ -63,17 +63,17 @@ Close is one in-process command with one exit code:
 | Outcome | Agent action |
 |---|---|
 | Exit 0, 0 issues | Summarise those counts in the user's language: Nodes touched; Sections added / updated / superseded / deprecated / skipped; `recompiled`; `locator_updates`; `rebuilt`; verify green. Stop. |
-| Exit 0, warnings only | Summarise + list warnings verbatim. For coverage warnings, name both choices: continue with `ready_with_debt`, or run an uncovered-only repair/skip round through `context compile --coverage-skip-unresolved` or `context schema coverage-disposition`. Stop. |
+| Exit 0, warnings only | Summarise + list warnings verbatim. For coverage warnings, surface the CLI-returned coverage view commands / `available_actions[]` instead of inventing a local decision matrix. Stop. |
 | Exit 2, Section / content issue | Surface the full issue list; point the user at re-running `/context:compile` (the draft loop owns Section writes). Do NOT Edit the affected rendered article. |
 | Exit 2, `compile-close-finalized-node-missing-knowledge` | If the missing Node has real citation evidence, point the user at `/context:compile` for that Node. If it is intentionally navigation-only or placeholder-only, point the user at `/context:align` to make it explicit no-write with `planned_sections: []` and context-only/ignored relation or placeholder blocks. |
 | Exit 2, structural issue (cycle, duplicate slug, `invalid-node-type`, `domain-same-file-child`) | Surface the full issue list; point the user at `/context:align` to revise structure. Do not re-run compile. |
 | Exit 2, `dropped-source-reference` | Surface the source-id; point the user at `/context:drop <id>` to complete the drop cleanup. |
 
-The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile --close` for the error→command mapping.
+The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile close` for the error→command mapping.
 
 ## Changelog entry shape
 
-`context compile --close` appends one markdown list item per run to
+`context compile close` appends one markdown list item per run to
 the changelog with aggregate counts — not a multi-line
 block:
 
@@ -90,7 +90,7 @@ item convention (see the drop skill for the exact shape).
 
 ### Step 1 — Invoke close
 
-Run `context compile --close`. The caller (typically `/context:compile`) may have already invoked it; check for existing output before re-running.
+Run `context compile close`. The caller (typically `/context:compile`) may have already invoked it; check for existing output before re-running.
 
 ### Step 2 — Interpret
 
@@ -118,12 +118,8 @@ Summarise in the user's language:
 
 Stop. Do not auto-invoke follow-on commands.
 
-### Step 5 — Self-verify
+### Step 5 — Final guardrails
 
-- [ ] `context compile --close` ran exactly once per close call — if not, **Step 1**.
-- [ ] If exit 2, every error is surfaced to the user with a re-entry command (compile / align / drop); no silent ignores — **Step 3**.
-- [ ] No agent-hand edits to rendered knowledge — if any, revert; the close stage is read-only for knowledge content.
-- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR`; CLI-owned output archival is allowed.
-- [ ] No ad-hoc script or shell file traversal was used against `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts.
+Run close once, surface every error with its re-entry command, and never inspect or edit rendered knowledge outside the CLI.
 
 </procedures>

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

@@ -5,8 +5,8 @@ description: >
   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` + optional `summary` + `source_refs[]`,
-  and emits a compile draft JSON document. The CLI
-  validates the actions via `context compile --draft <slug> --input - --plan`.
+  and emits a compile draft JSON document for the caller to submit to the current envelope's
+  `next_action.command`.
   Activates when `/context:compile` iterates across the confirmed align plan.
 tools:
   - Bash
@@ -19,20 +19,21 @@ Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update`
 ## 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.
-- Evidence boundary: treat `raw_snippets[]` as complete. Only `raw_snippet_indexes.citation_eligible` may be cited; `context_only` and secondary-shared snippets are background. `request_full_text` may expose full visible evidence text for inspection, including primary evidence; read returned page text from `request_full_text.pages[].text`. Long blocks are paged, so follow `request_full_text.pages[].next_command` when `has_more` is true; `raw_snippets[].quote` mirrors the same page text beside citation metadata, and it does not change citation eligibility. If a secondary-shared or `context_only` block holds facts that need citation, emit `pending_ownership_challenge` or `structure_challenge` — see [references/structural-challenges.md](references/structural-challenges.md). Never `grep` / `sed` / `jq` / `cat` / `head` raw `--format json` stdout or workflow scratch files in `/tmp` or `.context/.cache/` to recover a token. Instead: for the digest of any workflow payload use `context workflow show --payload <name> --digest-only --format text` (prints just the digest); for substructure use explicit semantic views such as `context compile --context <slug> --view source-refs --token-budget 2000 --format json`, `context workflow show --payload node-context --view source-refs --token-budget 2000 --unwrap --format json`, or `context workflow show --payload prepare --view issues --unwrap --format json`; follow returned `how_to_explore[]` when the view is truncated. For write commands that take `--payload-digest`, omit the flag entirely and let the CLI auto-resolve the latest payload for the current workflow scope.
+- Agent emits JSON only; no markdown, no direct workspace file writes. The caller submits the JSON to the current envelope's `next_action.command`; the CLI validates and stores workflow payloads.
+- Evidence boundary: treat the CLI-provided NodeContext and evidence views as complete. Cite only refs surfaced in `citable_source_refs[]` or `raw_snippet_indexes.citation_eligible`; treat `supporting_context_refs[]`, `context_only`, and secondary-shared snippets as background. `request_full_text` may expose visible text for inspection through the narrow text view (`context compile context <slug> --request-full-text <block_id> --view text --format json`), and it does not change citation eligibility. If supporting/context-only evidence is needed as a citation, emit `pending_ownership_challenge` or `structure_challenge` — see [references/structural-challenges.md](references/structural-challenges.md). Never `grep` / `sed` / `jq` / `cat` / `head` raw `--format json` stdout or workflow scratch files in `/tmp` or `.context/.cache/`; use semantic views and follow returned `next_command` / `how_to_explore[]`. For write commands that take `--payload-digest`, omit the flag unless the CLI explicitly asks for a stale guard.
 - Actions are candidate write actions, not final semantic decisions; `context reconcile prepare` re-derives near-duplicate / conflict / merge relations from `candidates[]` on its own. Op naming is scoped by schema: compile-draft `actions[]` already targets Sections, so Section lifecycle ops are verb-only (`add`, `update`, `supersede`, `deprecate`, `skip`). Do not use align-style names such as `add_section`, `write_section`, or `propose_section`.
 - 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` by the [Section Kind Canon](#section-kind-canon), also exposed as `section_kind_priority` in `context schema compile-draft`. First matching form wins. A `decision` needs at least two surfaced alternatives plus a reason; bare "we use X because Y" is `spec`. Reach `description` only after every more specific kind fails.
+- Pick `kind` from the CLI's `context schema compile-draft` contract, especially `section_kind_priority` and the mount matrix. First matching form wins. A `decision` needs at least two surfaced alternatives plus a reason; bare "we use X because Y" is `spec`. Reach `description` only after every more specific kind fails.
+- `node.planned_sections[]` is an align-time scaffold hint, not a hard completion gate. Prefer a planned kind when the evidence fits; if a source-backed stronger kind differs, emit it and let the CLI warning guide review.
 - `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.
 - Use `content` for the Section text the reader should see. It may be long and may contain URLs, tables, commands, config, or code fences. Add `summary` for long content or when it helps readers/query output; omit it when content is short. Summary quality checks are warning hints only, not schema or evidence failures. The CLI rejects retired fields (`body`, `detail`, `raw`, singular `source_ref`, quoted-evidence) with canonical repair hints — read those hints rather than memorising the blacklist. Omit optional fields when empty.
-- Preserve documentation/reference URL blocks. If a citation-eligible raw block is primarily links (官网 / docs / reference / related links), create a small `description` Section such as "相关链接" and keep every URL in `content`; do not drop link-only evidence just because it is not prose. If the URL block is only `context_only`, keep it as background and emit an ownership/structure challenge instead of citing it.
+- Preserve literals required by the CLI. When source-refs or scaffold output lists `required_preserved_literals[]`, keep those URL, code identifier, `source_ref`, or `block_id` literals visible in the relevant `content`, `summary`, skip reason, or repair challenge. Do not rely on memorized URL rules; let CLI literal fields and citation diagnostics define what must be preserved.
 - `refers_to_nodes[]` only carries slugs present in the context's glossary, existing Sections, or the current align plan; never invent one.
 - `skip` is the honest default when raw adds nothing. Bare `skip` (no `source_refs[]`) is only for deterministic no-ops such as unchanged input or pure navigation. When a snippet was reviewed and intentionally not written, emit `skip` with `source_refs[]` from that snippet so semantic review can record `reviewed_no_write`.
 - 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: Node-facing summaries and user-facing draft explanations follow `NodeContext.generation_policy.language` when present; otherwise match the raw material. Draft `content` is source-bound: prefer the cited source language when it differs from the workspace language, and do not translate quoted English facts into Chinese just to satisfy workspace language. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
+- Output language: Node-facing summaries and user-facing draft explanations follow `NodeContext.generation_policy.language` when present; otherwise match the raw material. Section `summary` may follow either the workspace language or the source-bound `content` language; do not rewrite it only to switch languages. Draft `content` is source-bound: prefer the cited source language when it differs from the workspace language, and do not translate quoted English facts into Chinese just to satisfy workspace language. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
 - Stable output: keep action order aligned with evidence order — that ordering is the only stability concern the CLI cannot enforce. The CLI rejects unknown fields (timestamps, random ids, host/scratch paths) and canonicalises stored payloads; fixed rules and schema come from this skill, so only the current NodeContext should vary between repeated Node draft calls.
 
 ## Edge cases — consult references when:
@@ -54,7 +55,7 @@ Canonical shape: `context schema node-context --format yaml` (or `--format json`
 
 Boundary recap (rules not captured by the schema enums):
 
-- `mentions[]` are raw positions that named this Node; `raw_snippets[]` are the wider context blocks around those positions, or the changed raw blocks selected by `context compile --scan-changes`. These two arrays are the evidence floor — never reach outside them.
+- `mentions[]` are raw positions that named this Node; `raw_snippets[]` are the wider context blocks around those positions, or the changed raw blocks selected by `context compile scan`. These two arrays are the evidence floor — never reach outside them.
 - `node.sources[]` are the only sources that may be cited as `src-N`. `node.context_sources[]` contribute `raw_snippets[]` for comparison or background only and must not be cited unless the CLI has also placed that source in `node.sources[]`.
 - `source_id` is the source registry id (e.g. `local:billing`); `src-N` aliases only appear inside `source_ref` strings — copy `raw_snippets[].source_ref` verbatim into draft `source_refs[]`.
 
@@ -68,57 +69,15 @@ Main-path ops are **`add`** and **`skip`**. A typical new Section action is `{ o
 
 `source_refs[]` values are copied verbatim from `raw_snippets[].source_ref`; a single citation is still a single-element array. When one Section summarises contiguous multi-block evidence, list only the source refs the `content` actually consumes. If the CLI reports `compile-source-refs-auto-narrowed`, it safely reduced an over-wide citation; removed refs are still uncovered, so add separate actions for distinct knowledge or leave them to an evidence-carrying `skip`. Preserve raw wording in `content` when it is already clear. Preserving a cited prose/bullet list as the Section's user-facing content is allowed when that list is the actual knowledge; the anti-pattern is copying raw text only as traceability or lexical-score padding. For `example` Sections that cite command / config / code fences, include the relevant fenced block in `content`.
 
-## Section Kind Canon
-
-Walk this priority chain and stop at the first form that fits:
-
-```
-example -> comparison -> faq -> incident -> changelog ->
-decision -> spec -> warning -> principle -> description
-```
-
-| kind | Use when | `content` should contain | Positive / negative boundary |
-|---|---|---|---|
-| `example` | fenced code, config, or command sample | what the sample does plus the full snippet when useful | `<AppProvider />` sample or `bun run build`; plain "wrap with AppProvider" is `description` |
-| `comparison` | at least two subjects across at least two dimensions | compared subjects, dimensions, and table/matrix | `X vs Y vs Z` table; "two options have tradeoffs" is `description`; "choose X over Y" is `decision` |
-| `faq` | one explicit question-answer pair | question plus answer | Q/A block; an "X FAQ collection" is several `faq` Sections on X, not a container Node |
-| `incident` | happened event with time, impact, and root cause / handling | time, severity/impact, root cause, timeline/actions | dated outage postmortem; "risk may happen" is `warning` |
-| `changelog` | version/date plus change description | version, change type, migration notes if present | `v1.2.0 added X`; "X supports Y" without version is `spec` or `description` |
-| `decision` | text surfaces at least two alternatives plus a reason | selected option, alternatives, reason, impact | "choose async rather than sync because..."; bare "use X because..." is `spec` |
-| `spec` | verifiable behavior, threshold, default, limit, or check method | object, condition, value/constraint | retry max 3; vague "consider concurrency" is `principle` or `description` |
-| `warning` | factual risk, caveat, or negative consequence | trigger condition and consequence | "without warmup first 30s timeout"; "don't change config" without consequence is too vague |
-| `principle` | stable design invariant / philosophy with no check method and no choice action | invariant and reason | "single way to write UI"; retry max 3 is `spec`; "choose X over Y" is `decision` |
-| `description` | fallback definition, overview, or plain narrative | definition, purpose, scope, distinction | only after the nine kinds above fail; do not use it to hide lists, rules, tables, samples, risks, or decisions |
-
-Mount matrix:
-
-| kind | domain | entity | action |
-|---|:---:|:---:|:---:|
-| `description` | yes | yes | yes |
-| `spec` | no | yes | yes |
-| `warning` | yes | yes | yes |
-| `principle` | yes | yes | no |
-| `decision` | yes | yes | yes |
-| `incident` | no | yes | yes |
-| `example` | no | yes | no |
-| `changelog` | no | yes | no |
-| `comparison` | no | yes | no |
-| `faq` | yes | yes | yes |
-
-When the strongest kind is not mountable on this Node type, choose the next legal kind that the evidence truly supports, or `skip` with a structural challenge reason. Do not force `description` just because it mounts everywhere.
-
-## 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. |
+## Section Kind Choice
+
+Use `context schema compile-draft --view minimal --format json` (or yaml) for the current legal kind list, priority order, and mount matrix. This skill adds only semantic guardrails:
+
+- Stop at the first kind whose source-backed form fits.
+- Do not choose `description` to hide lists, rules, tables, samples, risks, choices, or Q+A evidence that has a more precise kind.
+- When the strongest kind is not mountable on this Node type, choose the next legal kind that the evidence truly supports, or `skip` with a structural challenge reason.
 
-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.
+Confidence is optional. Omit it for ordinary confirmed claims; set it only when the evidence is clearly verified, inferred, or speculative according to the schema enum.
 
 ## Description anti-abuse gates
 
@@ -159,20 +118,14 @@ Check edge case conditions from the routing table at the top of this skill. If a
 
 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.
 
-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.
+Use the CLI-provided citation-eligible snippets and diagnostics as the coverage contract. Distinct source-backed facts should become distinct actions or evidence-carrying skips; duplicates, navigation-only blocks, placeholders, and unsupported fragments can be skipped. If later CLI diagnostics report low coverage, repair the same draft through the returned `next_action`.
 
 ### Step 2 — Classify each raw snippet
 
 For each `raw_snippets[]` entry:
 
 1. 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.
-2. Walk the Section kind priority chain from [Section Kind Canon](#section-kind-canon); stop at the first kind whose trigger fires.
+2. Pick kind using [Section Kind Choice](#section-kind-choice); stop at the first kind whose trigger fires.
 3. 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.
 4. If you land on `description`, walk the [Description anti-abuse gates](#description-anti-abuse-gates). Any gate fires → split or `skip`.
 
@@ -188,9 +141,10 @@ For each classified snippet:
    - `source_support` is a lexical diagnostic, not the final semantic judge. Do not stuff raw text into `content` just to raise matched-term counts.
    - There is no separate default `evidence-echo` warning. Treat "echo" as an anti-pattern: raw copied only to show basis/evidence, while `source_ref` already provides traceability.
    - For `description` / `spec`, a concise summary plus the cited bullet list is acceptable when the bullets are the useful user-facing knowledge. It becomes echo only when the copied text is not meant to be read as active knowledge.
-3. If `content` is longer than 200 characters, add `summary`. Summary is LLM-authored reader/query aid: one plain paragraph, no Markdown, about `content.length / 10`, minimum 10 characters, recommended maximum 120. The CLI reports missing, long, short, or formatted summaries as warning hints only; it does not auto-generate them and does not treat them as evidence failures. `source_support` hard-term matching checks `content` (and legacy `detail` when present), not `summary`; keep summaries faithful to `content`, but do not copy raw-only keywords into `summary` for lexical scoring.
-4. If the cited block contains documentation/reference URLs, preserve them in `content`. Link-only blocks are still useful knowledge; use `kind: description` with a concise "相关链接" identity when no more specific kind applies.
-5. Omit `confidence` for ordinary confirmed claims. Assign `confidence` per the [Confidence rubric](#confidence-rubric) only when the evidence is not confirmed.
+   - For `example` Sections that cite a code, config, or command fence, keep `content` centered on the cited fenced block. Put framing prose such as "basic configuration example" in `summary`, or cite a separate prose block in a separate action when that prose is itself source-backed knowledge.
+3. For long `content`, add `summary` when it helps readers or query output. Summary is LLM-authored reader/query aid: one plain paragraph, no Markdown, and should stay compact. The CLI only reports advisory hints for missing summaries on long content, Markdown/multi-paragraph formatting, or clearly overlong summaries; it does not enforce a content-length ratio and does not treat summary quality as an evidence failure. `source_support` hard-term matching checks `content` (and legacy `detail` when present), not `summary`; keep summaries faithful to `content`, but do not copy raw-only keywords into `summary` for lexical scoring.
+4. Preserve `required_preserved_literals[]` from the CLI evidence view. For link-heavy citation-eligible evidence, keep the listed URLs in `content` when the action writes knowledge; for supporting-only literals, keep them in the repair/challenge context instead of citing them.
+5. Omit `confidence` for ordinary confirmed claims. Assign it only when the evidence is clearly verified, inferred, or speculative according to the schema enum.
 6. Fill `refers_to_nodes[]` per [Glossary and refers_to_nodes](#glossary-and-refers_to_nodes).
 7. Cite evidence with `source_refs[]`, picking values from `raw_snippets[].source_ref`. When one Section summarizes contiguous multi-block evidence, list only the source refs consumed by that Section content; the CLI verifies that the refs can collapse to one canonical citation token and may auto-narrow over-wide citations. 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.
 
@@ -198,15 +152,8 @@ Rendered knowledge starts with optional `c4a:summary`, then the active `content`
 
 ### Step 4 — 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 5 — Self-verify
+Emit one compile draft JSON document for the caller to submit to the current envelope's `next_action.command`. No markdown wrapper, no leading prose, no trailing commentary.
 
-- [ ] Every action's `target_node` equals `node.slug`, with a legal `kind × node.type` combination and `content` + optional `summary` + `source_refs[]` only (no singular `source_ref`, no `body` / `detail` / `raw`, no quoted-evidence or extractive-contract fields, no new terms absent from the cited raw). If not, return to **Step 2** for kind/mount-matrix issues, otherwise **Step 3**.
-- [ ] Every `description` action survives the [Description anti-abuse gates](#description-anti-abuse-gates). If not, **Step 2** to split or `skip`.
-- [ ] Coverage matches evidence density: dense raw with one broad action returns to **Step 2** unless remaining snippets are duplicates / navigation / placeholders / already covered. Citation-eligible URL blocks are either preserved or `skip`-with-evidence.
-- [ ] `skip` semantics: bare `skip` only for deterministic no-op (unchanged input or pure navigation); reviewed-no-write `skip` carries `source_refs[]` from the cited snippet. When raw adds nothing, exactly one `op: skip` with a reason — not `actions: []`. If not, **Step 3**.
-- [ ] If any edge case condition applies (action/domain Node, note snippets, existing Sections, non-changed-only incremental, or structural defect), the relevant reference's Self-verify items were also satisfied.
-- [ ] NodeContext was the only evidence source — no Read / Glob / Grep / Write / ad-hoc script or shell file traversal against `WORKSPACE_DIR`, `.context`, `/tmp` workflow artifacts, or CLI `--format json` stdout. If any was used, restart from the CLI-provided NodeContext.
+Before returning, ensure `target_node` matches `node.slug`, fields conform to `context schema compile-draft`, `required_preserved_literals[]` are preserved or carried into an evidence-backed skip/repair challenge, and NodeContext was the only evidence source.
 
 </procedures>

package/plugin/skills/skill-compile-draft/references/structural-challenges.md

@@ -62,7 +62,7 @@ Supported `structure_challenge.kind` values: `missing_action_node`, `extra_actio
 }
 ```
 
-Different `kind` values demand different sub-fields. The CLI returns `agent_hints[].correct_shape` on shape errors; follow that hint rather than guessing.
+Different `kind` values demand different sub-fields. On shape errors, follow the CLI's top-level diagnostics / `expected_shape` / returned repair `next_action` instead of guessing. `agent_hints[]`, when present, is only a cutover mirror and must not be the source of truth.
 
 ## What these are NOT
 

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

@@ -1,9 +1,9 @@
 ---
 name: skill-compile-judge
 description: >
-  Packaged skill invoked by `/context:compile`; not a user slash command. Consumes the full compile prepare payload,
-  judges each draft action's source support and relation to listed candidates,
-  and emits a compile.judge-decisions.v1 document for `context reconcile review`.
+  Packaged skill invoked by `/context:compile`; not a user slash command. Consumes the budget-safe compile prepare summary
+  and candidate detail views, judges each draft action's source support and relation to listed candidates,
+  and emits a compile.judge-decisions.v2 document for `context reconcile review`.
 tools:
   - Bash
 ---
@@ -16,9 +16,10 @@ decisions only; the CLI reviews, applies, and writes every workspace change.
 
 ## TL;DR — Non-negotiables
 
-- Input is the full compile prepare payload. Compact summaries are only a pointer; if needed, load the full payload with the `workflow_payload.show_command` from `context compile --draft ... --prepare`.
+- Invoke this skill only when the caller's top-level envelope has `next_action.kind: "review_reconcile_decisions"` or the prepare payload contains `judge_handoff`. If the active envelope asks for `patch_compile_draft`, `continue_compile_cycle`, or another action, stop and follow that `next_action.command` instead.
+- Input is the budget-safe compile prepare summary. For items with candidates, load only that item's candidate detail view with `context workflow show --payload prepare --view candidates --item-id <item-id> --unwrap --format json`.
 - Do not inspect workspace storage directly or run ad-hoc scripts to reconstruct candidates. Use only `items[]`, `evidence[]`, `source_support` diagnostics, `candidates[]`, `previous_decisions[]`, and `judge_handoff`.
-- Output exactly one JSON or YAML document with `schema_version: "compile.judge-decisions.v1"` and `decisions[]`.
+- Output exactly one JSON or YAML document with `schema_version: "compile.judge-decisions.v2"` and `decisions[]`.
 - Keep one decision per prepared `item_id`, preserving prepare order.
 - For support, output `support_verdict: supported | weak | unsupported` plus `support_reason`.
 - For relation, output `relation_verdict: new | duplicate | supersede | conflict | merge_into` plus `relation_reason`.
@@ -35,7 +36,7 @@ decisions only; the CLI reviews, applies, and writes every workspace change.
 ## Output Shape
 
 ```yaml
-schema_version: "compile.judge-decisions.v1"
+schema_version: "compile.judge-decisions.v2"
 mode: compile
 decisions:
   - item_id: claim-001
@@ -50,7 +51,7 @@ decisions:
 For a relation against an existing candidate:
 
 ```yaml
-schema_version: "compile.judge-decisions.v1"
+schema_version: "compile.judge-decisions.v2"
 mode: compile
 decisions:
   - item_id: claim-002
@@ -80,10 +81,11 @@ decisions:
 
 <procedures>
 
-### Step 1 — Load Full Prepare Payload
+### Step 1 — Load Prepare Summary And Candidate Details
 
-If the caller gave compact prepare output, use its workflow payload command to
-load the full `prepare` payload. Do not infer missing candidates from memory.
+Use the caller-provided compact prepare output. For every item with candidates,
+load its candidate detail view before judging relation. Do not infer missing
+candidates from memory or bypass the candidate detail view.
 
 ### Step 2 — Judge Support
 
@@ -101,7 +103,7 @@ candidate list is empty, emit `new` with an empty compared list and
 
 ### Step 4 — Emit Judge Decisions
 
-Return only the `compile.judge-decisions.v1` document. The caller passes it
+Return only the `compile.judge-decisions.v2` document. The caller passes it
 directly to `context reconcile review --decisions -`.
 
 </procedures>

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

@@ -127,7 +127,7 @@ the user's wording indicates newly captured material is not yet knowledge.
 
 <procedures>
 
-## Step 1: Classify problem intent
+### Step 1 — Classify Problem Intent
 
 Determine what the user is trying to learn. Choose the appropriate command from the Query Route table above.
 
@@ -155,7 +155,7 @@ Determine what the user is trying to learn. Choose the appropriate command from
   - Action: Run `context query --intent recall --profile <reconcile-*> --query "..."`
   - ❌ Never use for ordinary questions
 
-## Step 2: Execute query & interpret response
+### Step 2 — Execute Query And Interpret Response
 
 Run the command from Step 1. Read the CLI output carefully.
 
@@ -174,7 +174,7 @@ Run the command from Step 1. Read the CLI output carefully.
 - ✓ **`node_view` says `visible: complete` / `visibility.complete=true`** → Do not run `section_search` merely to check completeness; use `section_search` only when you need keyword narrowing or ranking inside the Node
 - ✓ **Entries returned** → Proceed to Step 3
 
-## Step 3: Compose answer from returned structure
+### Step 3 — Compose Answer From Returned Structure
 
 Use only the returned Node/Section structure and content. Do not synthesize beyond what was returned.
 
@@ -206,7 +206,7 @@ To dive deeper into any system, ask me for more details or let me know which Nod
 **Why show structure first?** Even when you know keywords, structure queries reveal the full landscape.
 Agents should explore Nodes first, then use section_search for details within a chosen Node.
 
-## Step 4: Explore further (if user requests)
+### Step 4 — Explore Further When Requested
 
 Once Node scope is clear, user may ask for deeper exploration.
 

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

@@ -19,7 +19,7 @@ only; the CLI performs every write.
 
 ## TL;DR — Non-negotiables
 
-- Input is the full `context reconcile prepare` payload. If the caller handed you a compact prepare summary or `--view issues` payload, load the full payload first with `context workflow show --payload prepare --unwrap --format json` (add `--digest` only as an explicit stale guard). Never `grep` / `sed` / `jq` / `cat` / `head` workflow scratch files or `--format json` stdout to recover prepare fields, and do not Read / Glob / Grep / Write workspace `raw/` / `knowledge/` / `archive/` / `decisions/` — the prepare payload and review output are the only inputs.
+- Input is the budget-safe `context reconcile prepare` summary or issues view. When an item lists candidates, load that item's candidate detail view with `context workflow show --payload prepare --view candidates --item-id <item-id> --unwrap --format json`; request broader detail only when a CLI `next_action` or detail command explicitly asks for it. Never `grep` / `sed` / `jq` / `cat` / `head` workflow scratch files or `--format json` stdout to recover prepare fields, and do not Read / Glob / Grep / Write workspace `raw/` / `knowledge/` / `archive/` / `decisions/` — the prepare payload and review output are the only inputs.
 - Ordinary compile prepare judgment belongs to `skill-compile-judge`. Use this skill for refresh/drop/non-compile reconcile, or when compile review asks for scope/omit/user-confirmation reasoning that is outside the judge handoff.
 - Output: one YAML or JSON document conforming to `context schema semantic-decisions --format yaml`. The schema defines canonical `relation` and `action` enums and the per-action required fields; do not memorise the enum list from this skill.
 - Accept a prepared `default_decision` with the compact form `{ item_id, accept_default: true }` (optionally `decided_by` / `rationale`); the CLI hydrates `target` / `proposed`. Empty `decisions: []` means "no items in prepare," not "accept all defaults." Without `--accept-safe-defaults`, emit one compact accept entry per safe default you intend to accept. With `--accept-safe-defaults`, the CLI auto-accepts mechanically safe no-candidate supported writes and reviewed-no-write skips, so emit only the manual decisions that still need judgment.
@@ -37,7 +37,7 @@ only; the CLI performs every write.
 |---|---|
 | `prepare.mode` is `drop` or `refresh` (covers `remove_unsupported` mode semantics, `reanchor`, `split_then_reanchor`) | [references/mode-semantics.md](references/mode-semantics.md) |
 | review returned `support_confirmation`, `omit_confirmation`, `scope_review_required`, or any `ask_user` you need to upgrade to an executable decision | [references/user-confirmation.md](references/user-confirmation.md) |
-| review returned `agent_hints[]` with `code: "context-only-leakage-high"` | [references/leakage-and-ownership.md](references/leakage-and-ownership.md) |
+| review diagnostics or cutover hints returned `code: "context-only-leakage-high"` | [references/leakage-and-ownership.md](references/leakage-and-ownership.md) |
 | items carry `temporal_prior` / `source_captured_at` / `temporal_disposition`, `source_support.evidence_block_*`, or prepared long `proposed.content` / `proposed.summary` | [references/temporal-and-evidence.md](references/temporal-and-evidence.md) |
 | considering `action: omit`, or items look redundant / low-value / scope-wrong | [references/scope-review-and-omit.md](references/scope-review-and-omit.md) |
 
@@ -122,7 +122,7 @@ Drop-mode-only branches (`reanchor`, `split_then_reanchor`, `remove_unsupported`
 
 Emit one document with `schema_version: "1.0"` and `decisions[]`. Include only executable final decisions plus unresolved `ask_user` questions. Do not include prose outside the document.
 
-If the latest review rejected the batch with `context-only-leakage-high`, do not convert it into a generic `ask_user`. Follow [references/leakage-and-ownership.md](references/leakage-and-ownership.md): regenerate the affected decision using one of the review hint's explicit repair options and cited item ids, then rerun `context reconcile review`.
+If the latest review rejected the batch with `context-only-leakage-high`, do not convert it into a generic `ask_user`. Follow [references/leakage-and-ownership.md](references/leakage-and-ownership.md): regenerate the affected decision using the review diagnostic's explicit repair options and cited item ids, then rerun `context reconcile review`.
 
 ### Step 4 — Self-verify
 

package/plugin/skills/skill-semantic-reconcile/references/leakage-and-ownership.md

@@ -1,6 +1,6 @@
 # Context-only leakage and ownership upgrades
 
-Consult this reference when `context reconcile review` returns `agent_hints[]` with `code: "context-only-leakage-high"`. For runs without that hint, ignore this file.
+Consult this reference when `context reconcile review` returns diagnostics or cutover hints with `code: "context-only-leakage-high"`. For runs without that code, ignore this file.
 
 ## What the hint means
 

package/scripts/build-plugin.ts

@@ -34,6 +34,8 @@ const repoRoot = resolve(pkgRoot, "../..");
 const PLUGINS_ROOT = process.env.C4A_PLUGINS_ROOT
   ? resolve(process.env.C4A_PLUGINS_ROOT)
   : resolve(repoRoot, "c4a-plugins");
+const MARKETPLACE_NAME = "c4a";
+const PLUGIN_NAME = "context";
 
 interface CommandSource {
   slug: string;
@@ -116,7 +118,7 @@ function rewriteClaudeSlashCommandsForCursor(body: string): string {
     .replace(/\/context:([a-z-]+)/g, (_match, slug: string) =>
       slug === "context" ? "/context" : `/context-${slug}`
     )
-    .replace(/^## Your task$/gm, "## Workflow")
+    .replace(/^## Your [Tt]ask$/gm, "## Workflow")
     .replace(/\bPackaged skill invoked by\b/g, "Internal procedure invoked by")
     .replace(/\bnot a user slash command\b/g, "not a user command");
 }
@@ -352,7 +354,7 @@ function stripHtmlComments(markdown: string): string {
 function publicSkillBody(command: CommandSource, publicName: string): string {
   const claudeCommand = claudeCommandForSlug(command.slug);
   const rewrittenBody = rewritePackagedSkillReferences(command.body, publicEntrySkillPath)
-    .replace(/^## Your task$/gm, "## Workflow");
+    .replace(/^## Your [Tt]ask$/gm, "## Workflow");
   return `---\nname: ${publicName}\ndescription: >\n  ${command.description} Equivalent to Claude ${claudeCommand}; use the local \`context\` CLI for workspace writes.\ntools:\n  - Bash\n---\n\n# ${command.title}\n\nPublic C4A Context entry for agents that expose skills instead of Claude slash commands.\n\n- Public entry: \`${publicName}\`\n- Claude equivalent: \`${claudeCommand}\`\n- CLI primitive prefix: \`context ...\`\n- Internal procedures live under \`${INTERNAL_PROCEDURES_DIR}/\`; read each referenced file in full before following that step.\n\n---\n\n${rewrittenBody.trimEnd()}\n`;
 }
 
@@ -601,29 +603,29 @@ async function ensurePluginsRoot(): Promise<void> {
 
 async function writeMarketplaceManifests(version: string): Promise<void> {
   const claudeMarketplace = {
-    name: "context",
+    name: MARKETPLACE_NAME,
     owner: { name: "c4a" },
     plugins: [{
-      name: "context",
+      name: PLUGIN_NAME,
       source: "./claude",
       description: "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts.",
     }],
   };
   const cursorMarketplace = {
-    name: "context",
+    name: MARKETPLACE_NAME,
     owner: { name: "Context4AI", email: "support@context4ai.dev" },
     metadata: { description: "C4A Context plugin marketplace" },
     plugins: [{
-      name: "context",
+      name: PLUGIN_NAME,
       source: "./cursor",
       description: "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
     }],
   };
   const codexMarketplace = {
-    name: "context",
+    name: MARKETPLACE_NAME,
     interface: { displayName: "C4A Marketplace" },
     plugins: [{
-      name: "context",
+      name: PLUGIN_NAME,
       source: { source: "local", path: "./codex" },
       policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
       category: "Productivity",

package/templates/aspects/code/prompt.md

@@ -37,8 +37,11 @@ The bucket contains:
 - The code aspect uses `evidence.mode: none`: it does not generate
   `raw/.evidence` block manifests. Symbols, files, and edges are already
   represented by the bucket JSONL indexes.
-- Formal code DSL query and logical code `source_ref` support are tracked by a
-  later version; this aspect only prepares the raw snapshot contract.
+- `context compile code` converts package and symbol rows into code-owned
+  Sections with code `source_ref` values such as
+  `src-1#package:<package>@<hash>` and
+  `src-1#symbol:<locator>:<kind>@<hash>`. These refs resolve against the raw
+  code snapshot JSONL indexes, not against prose evidence blocks.
 - Runner raw extraction results are intentionally not written as a separate
   bucket file. Future consumers should read `digests.jsonl` and the flat
   package/symbol/edge projections instead.