@c4a/context-cli 0.5.35-beta.3 → 0.5.38

package/plugin/skills/skill-align-workflow/references/candidate-resolution.md

@@ -57,4 +57,4 @@ block_ownership:
   - owners: [local:data-region]
 ```
 
-Refs may point to `llm_slug_hint` or final `slug`; prefer `*_ref` fields when a schema provides them. If the CLI rejects an unknown ref, use the returned `agent_hints[].available_node_refs` and resubmit a corrected `align-structure-decision`.
+Refs may point to `llm_slug_hint` or final `slug`; prefer `*_ref` fields when a schema provides them. If the CLI rejects an unknown ref, use the top-level envelope diagnostics (`issues[].expected_shape.available_node_refs`, `diagnostics.*.available_node_refs`, or the returned repair view) and resubmit the corrected `align-structure-decision` payload. `agent_hints[]`, when present, is only a cutover mirror and must not be the source of truth.

package/plugin/skills/skill-align-workflow/references/density-profile.md

@@ -2,6 +2,8 @@
 
 Use `density_profile` in `align-coarse-read` to describe how much structure the document needs before candidate discovery. This is a reading strategy, not a quality score.
 
+This reference applies only when the current envelope asks for `next_action.kind: "submit_coarse_read"`. A small or moderate direct route should follow `validate_align_decision`; do not emit a `single_pass` coarse-read payload unless the CLI requested coarse-read.
+
 | Profile | Use When | Agent Behavior |
 |---|---|---|
 | `macro` | A long source has many headings, sections, or broad topic shifts. | Create section proposals around major headings and preserve document-level anchors so later passes do not flatten scope. |

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

@@ -30,9 +30,11 @@ command. It does not hand-edit rendered knowledge.
   - 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 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. If the close receipt reports severely low coverage, surface the returned `--cover-uncovered-only` command as the recommended repair before treating the debt as accepted.
 - 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 <slug> --skip-unresolved --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. For severely low coverage, recommend one `--cover-uncovered-only` repair pass unless the user explicitly accepts the debt; otherwise report the warning and follow returned coverage view commands / `available_actions[]` only if the user chooses a repair or skip round.
+- Coverage and engagement denominators count primary citable content evidence. URL/reference-only, marker, frontmatter, embed, navigation, and context-only evidence is excluded or bucketed as non-blocking bookkeeping by the CLI.
+- User-accepted hard-fact risk is carried as `review_debt`; report it from close/status when present, but do not treat review-debt count as a close failure.
 - 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.
 - 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.
@@ -63,7 +65,7 @@ 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 <slug> --skip-unresolved --reason "<reason>"` or `context schema coverage-disposition`. Stop. |
+| Exit 0, warnings only | Summarise + list warnings verbatim. For severely low coverage, recommend the CLI-returned `--cover-uncovered-only` repair command before final acceptance; for other coverage warnings, surface returned coverage view commands / `available_actions[]` instead of inventing a local decision matrix. |
 | 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. |
@@ -118,12 +120,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

@@ -4,9 +4,9 @@ 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` + optional `summary` + `source_refs[]`,
-  and emits a compile draft JSON document. The CLI
-  validates the actions via `context compile draft <slug> --input -`.
+  kind via the priority chain, writes `content` + optional `summary` + `source_block_ids[]`,
+  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
@@ -18,19 +18,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 - --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, but use the narrow text view (`context compile context <slug> --request-full-text <block_id> --view text --format json`) and read `items[].text`; long blocks are paged, so follow `items[].next_command` when present. `request_full_text.pages[].text` and `raw_snippets[].quote` may mirror the same page text in full NodeContext outputs, 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 `next_command` for paged views and `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.
+- One Node per invocation — `node_slug` 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 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 block ids surfaced as citation-eligible in `source-refs-index` `items[]`, `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.
+- Every write action cites raw via `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`; the CLI expands it to canonical `source_refs[]` before saving. Use explicit `source_refs[]` only when the CLI gives no block id for the needed citation. Never mix both fields in one action, fabricate ids, or cite navigation-only blocks as evidence for a content Section.
+- For large source-ref views, prefer the returned `source_refs_index_command` / `source_refs_command` / `--view source-refs-index` when you only need block ids; open `source_refs_detail_command` only when you need quote preview or explicit `source_refs[]`.
 - 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 user-facing Markdown structure from cited raw when it carries meaning: inline code/code fences, Markdown links and URLs, blockquotes, list nesting, tables, and emphasis around key terms. Summary remains plain text; content may keep raw Markdown when that is the clearest faithful Section text.
+- 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`.
+- `skip` is the honest default when raw adds nothing. Bare `skip` (no evidence) is only for deterministic no-ops such as unchanged input, pure navigation, or context-only/background snippets. When a citation-eligible snippet was reviewed and intentionally not written, emit `skip` with `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id` so semantic review can record `reviewed_no_write`. Never attach `context_only` / supporting block ids to skip; raise a challenge if they should become citation evidence.
 - 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. 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.
@@ -57,69 +59,37 @@ 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`. 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[]`.
+- `source_id` is the source registry id (e.g. `local:billing`); `src-N` aliases only appear inside `source_ref` strings. Prefer `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id` in draft `source_block_ids[]`; if you must use explicit `source_refs[]`, copy `raw_snippets[].source_ref` verbatim.
 
 ## Output — Compile Draft JSON (main path)
 
 Canonical shape: `context schema compile-draft --format yaml` (or `--format json`). The CLI is the source of truth for fields, enums, and validation — do not memorise the shape from this file.
 
-Main-path ops are **`add`** and **`skip`**. A typical new Section action is `{ op: "add", kind: "<chain-picked>", content: "...", source_refs: ["src-1#... L10-14@..."] }`; never spell that as `add_section` because the `actions[]` array already names the target object. A bare skip is `{ op: "skip", reason: "..." }`; a reviewed-no-write skip carries `source_refs[]` from the cited snippet.
+Main-path ops are **`add`** and **`skip`**. A typical new Section action is `{ op: "add", kind: "<chain-picked>", content: "...", source_block_ids: ["<block_id>"] }`; never spell that as `add_section` because the `actions[]` array already names the target object. A bare skip is `{ op: "skip", reason: "..." }`; a reviewed-no-write skip carries `source_block_ids[]` only from citation-eligible `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`.
 
-`update` / `supersede` / `deprecate` ops live in [references/refresh-and-update.md](references/refresh-and-update.md). `structure_challenge` / `pending_ownership_challenge` ops live in [references/structural-challenges.md](references/structural-challenges.md). Do not emit them from the main path.
+Minimal valid draft envelope:
 
-`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`.
+```json
+{
+  "schema_version": "compile.draft.v2",
+  "node_slug": "<matches node.slug>",
+  "actions": []
+}
+```
 
-## Section Kind Canon
+`update` / `supersede` / `deprecate` ops live in [references/refresh-and-update.md](references/refresh-and-update.md). `structure_challenge` / `pending_ownership_challenge` ops live in [references/structural-challenges.md](references/structural-challenges.md). Do not emit them from the main path.
 
-Walk this priority chain and stop at the first form that fits:
+`source_block_ids[]` is a mechanical shorthand over the same citation-eligible evidence; a single citation is still a single-element array. When one Section summarises contiguous multi-block evidence, list only the block ids the `content` actually consumes. If using explicit `source_refs[]`, copy them verbatim from `raw_snippets[].source_ref`. 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`.
 
-```
-example -> comparison -> faq -> incident -> changelog ->
-decision -> spec -> warning -> principle -> description
-```
+## Section Kind Choice
 
-| 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. |
+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
 
@@ -137,6 +107,8 @@ When raw mentions a name that overlaps the workspace glossary, put that name's s
 
 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`.
 
+If the CLI returns source-ref narrowing, candidate hard-fact, summary quality, or low-coverage advisories with `agent_recommended_action: ignore`, do not patch solely to satisfy the advisory. Patch only when the cited source actually loses meaning, a confirmed hard fact is unsupported, or the returned `next_action` asks for a draft patch.
+
 ## FAQ attachment priority
 
 | FAQ topic | Attach to |
@@ -160,20 +132,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`.
 
@@ -186,29 +152,23 @@ For each classified snippet:
 1. Write `content` as the Section text the reader should see. It can include long prose, URLs, tables, command/config/code fences, or short raw wording. Keep one coherent, cited fact group per action.
 2. Keep `content` 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.
    - Default to raw wording. Only make semantic-preserving edits for formatting, typo fixes, casing, entity/alias consistency, or sentence cleanup. If the raw text is already clear, `content` should equal the raw text.
-   - `source_support` is a lexical diagnostic, not the final semantic judge. Do not stuff raw text into `content` just to raise matched-term counts.
+   - Preserve meaningful Markdown formatting from the cited raw: inline code markers, fenced blocks, Markdown link targets, blockquote markers, nested list structure, tables, and emphasis on key terms. Do not flatten these into plain prose unless the formatting is purely decorative.
+   - `source_support` is advisory lexical diagnostics, not the final semantic judge or a keyword gate. Do not stuff raw text into `content` just to raise matched-term counts, and do not patch a clear draft only to satisfy a lexical term mismatch.
    - 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.
    - 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. 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.
+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. Lexical `source_support` 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.
+7. Cite evidence with `source_block_ids[]`, picking values from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`. When one Section summarizes contiguous multi-block evidence, list only the block ids consumed by that Section content; the CLI expands and 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_block_ids[]` only when the skip represents reviewed no-write material from citation-eligible evidence; omit evidence for purely deterministic no-ops, navigation, and context-only/background snippets. Never submit singular `source_ref`, mix `source_block_ids` with `source_refs`, or use quoted-evidence fields; the CLI rejects them.
 
 Rendered knowledge starts with optional `c4a:summary`, then the active `content`. If `content` differs from the cited raw, the CLI may render a debug-only `c4a:raw` block for audit; agents must not emit `raw`.
 
 ### Step 4 — Emit the JSON
 
-Emit one compile draft JSON document for the caller to pass to `context compile draft <slug> --input - --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 `schema_version` is `compile.draft.v2`, `node_slug` 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/notes.md

@@ -22,13 +22,13 @@ When a `raw_snippets[]` entry has `source_type: "note"`:
 
    `revision_kind` (`replace` / `clarify` / ...) refines the choice within `revision`.
 
-3. **No-write reviewed-no-write case.** If the note says "don't modify active knowledge yet" or the correct outcome is no-write after review, emit `skip` with `source_refs[]` containing the note's `raw_snippets[].source_ref`. This lets semantic review record `reviewed_no_write` instead of treating the skip as an unreviewed no-op.
+3. **No-write reviewed-no-write case.** If the note says "don't modify active knowledge yet" or the correct outcome is no-write after review, emit `skip` with `source_block_ids[]` containing the note's citation-eligible block id. This lets semantic review record `reviewed_no_write` instead of treating the skip as an unreviewed no-op.
 
-4. **Bare skip is not allowed for notes.** A bare `skip` (no `source_refs[]`) is only for deterministic no-op cases such as unchanged input or pure navigation. Notes always carry an anchor and an intent; the skip must cite the note's source_ref.
+4. **Bare skip is not allowed for notes.** A bare `skip` (no evidence) is only for deterministic no-op cases such as unchanged input or pure navigation. Notes always carry an anchor and an intent; the skip must cite the note's block id or explicit source_ref.
 
 ## Where this lives in the main procedure
 
 - **Step 2 — Classify**: run the note-first comparison **before** the generic kind priority chain. If the note resolves to `update` / `supersede` / `skip` (reviewed), record the action and move on; do not also process the same note through the generic chain.
-- **Step 5 — Self-verify**: every note snippet was either consumed by an anchored action or carried into a `skip` with `source_refs[]`.
+- **Step 5 — Self-verify**: every note snippet was either consumed by an anchored action or carried into a `skip` with `source_block_ids[]`.
 
 Notes never become structure_challenge or pending_ownership_challenge on their own. If a note describes a structural problem (missing Action, wrong parent, etc.), capture the underlying evidence in raw form and emit the challenge from that — see `references/structural-challenges.md`.

package/plugin/skills/skill-compile-draft/references/refresh-and-update.md

@@ -41,9 +41,9 @@ When `existing.sections[]` is non-empty, every `section-N` id you read here is a
 
 ### `update` / `supersede.new` mechanics
 
-- `update` keeps the same `section-N` id; provide new `content` (optional `summary`, optional new `source_refs[]`) but do not include `kind` unless the kind itself is changing.
-- `supersede.new` is a fresh Section; it needs `kind`, `content`, `source_refs[]`, and may carry `summary`, `refers_to_nodes[]`, and `confidence` per the same rules as `add`.
-- `deprecate` only needs `target_section_id` and `reason`. Do not pass `content` or `source_refs[]`.
+- `update` keeps the same `section-N` id; provide new `content` (optional `summary`, optional new `source_block_ids[]`) but do not include `kind` unless the kind itself is changing.
+- `supersede.new` is a fresh Section; it needs `kind`, `content`, `source_block_ids[]`, and may carry `summary`, `refers_to_nodes[]`, and `confidence` per the same rules as `add`.
+- `deprecate` only needs `target_section_id` and `reason`. Do not pass `content`, `source_block_ids[]`, or `source_refs[]`.
 
 ## Output schema (refresh ops)
 
@@ -53,12 +53,12 @@ When `existing.sections[]` is non-empty, every `section-N` id you read here is a
 	    { "op": "update", "target_section_id": "section-3",
 	      "content": "...",
 	      "refers_to_nodes": null,
-	      "source_refs": ["src-1#api L18-21@c0d4e5f61728"] },
+	      "source_block_ids": ["c0d4e5f61728"] },
 	    { "op": "supersede", "target_section_id": "section-5",
 	      "reason": "raw published a new retention value",
 	      "new": { "kind": "spec", "content": "...",
 	               "refers_to_nodes": ["..."],
-	               "source_refs": ["src-1#limits L30-34@9d1e2f3a4b5c"] } },
+	               "source_block_ids": ["9d1e2f3a4b5c"] } },
     { "op": "deprecate", "target_section_id": "section-2", "reason": "..." }
   ]
 }

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`.
@@ -27,7 +28,8 @@ decisions only; the CLI reviews, applies, and writes every workspace change.
 - Escape hatch: when an item has no candidates, `relation_verdict: new` with `compared_section_ids: []` and `compared_count: 0` is valid and expected.
 - For `duplicate`, `supersede`, `conflict`, or `merge_into`, set `target_section_id` to the matched candidate Section id.
 - Same `source_ref` can support different Section kinds only when the semantic role differs. Detect and explain same-source-ref multi-kind cases instead of treating them as automatic duplicates.
-- A supported judge verdict may override low lexical `source_support` only when the cited raw evidence covers the hard facts. If `source_support.missing_hard_terms[]` names real missing facts, do not mark support as supported.
+- `source_support` is advisory lexical diagnostics, not a keyword gate. A supported judge verdict may override low lexical `source_support` when the cited raw evidence semantically covers the claim.
+- Evidence-boundary errors, missing URLs, and split-by-evidence candidates remain blocking evidence issues. Do not patch drafts merely because `source_support.missing_hard_terms[]` contains a spelling, casing, punctuation, or paraphrase mismatch.
 - Weak support is a warning-level verdict, not permission to invent missing facts. Unsupported support should normally pair with `conflict` or a later user question rather than a write decision.
 
 <reference>
@@ -35,7 +37,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 +52,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 +82,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 +104,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-semantic-reconcile/SKILL.md

@@ -5,7 +5,7 @@ description: >
   and compile scope-review fallback; not a user slash command. Ordinary compile
   prepare judgment uses `skill-compile-judge`. This skill consumes only
   `context reconcile prepare` output, judges semantic relation/action for each item,
-  and emits a schema_version 1.0 semantic decision document for `context reconcile review`;
+  and emits a `semantic-decisions.v2` decision document for `context reconcile review`;
   apply consumes the current workflow's ready review artifact.
 tools:
   - Bash
@@ -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) |
 
@@ -50,7 +50,7 @@ If none of the above hold, you are on this skill's main path: refresh/drop/non-c
 Accept a prepared `default_decision` with the compact form:
 
 ```yaml
-schema_version: "1.0"
+schema_version: "semantic-decisions.v2"
 decisions:
   - item_id: claim-001
     accept_default: true
@@ -59,7 +59,7 @@ decisions:
 For a changed action or hand-authored decision, emit the full shape with the action's required fields (see Action Rules below):
 
 ```yaml
-schema_version: "1.0"
+schema_version: "semantic-decisions.v2"
 decisions:
   - item_id: claim-001
     relation: near_duplicate
@@ -120,9 +120,9 @@ Drop-mode-only branches (`reanchor`, `split_then_reanchor`, `remove_unsupported`
 
 ### Step 3 — Emit Decisions
 
-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.
+Emit one document with `schema_version: "semantic-decisions.v2"` 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;
@@ -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",