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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.36-beta.1",
+  "version": "0.5.38",
   "type": "module",
   "bin": {
     "context": "./cli.js"
@@ -12,6 +12,7 @@
     "react": "^18.3.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
+    "typescript": "^5.5.4",
     "unified": "^11.0.5",
     "yaml": "^2.5.1"
   },

package/plugin/README.md

@@ -67,7 +67,7 @@ From your project directory:
 
 1. **Init** — `/context:init` creates the `.context/` workspace;
 2. **Capture** — `/context:capture <url-or-path>` pulls in Feishu docs, local Markdown, code snapshots, and so on;
-3. **Code projection** — for code snapshots, `/context:compile code <source-slug>` materializes package/category/symbol Nodes such as `pkg`, `pkg/components`, and `pkg/symbol/button`;
+3. **Code projection** — for code snapshots, `/context:compile --aspect code <source-slug>` materializes package/category/symbol Nodes such as `pkg`, `pkg/components`, and `pkg/symbol/button`;
 4. **Align** — `/context:align` places prose material onto the Node structure, including docs or examples that should attach to existing code symbol Nodes;
 5. **Compile** — `/context:compile` lets the AI turn prose material into structured Sections;
 6. **Query** — `/context:query <question>` answers from local knowledge, citing Node and Section; code workspaces can filter mixed evidence with `--evidence code|prose|all`;

package/plugin/README_CN.md

@@ -67,7 +67,7 @@ bun add -g @c4a/context-cli
 
 1. **初始化** — `/context:init` 创建 `.context/` 工作目录；
 2. **采集** — `/context:capture <url-or-path>` 拉取飞书文档、本地 Markdown、代码快照等原始资料；
-3. **代码投影** — 对代码快照执行 `/context:compile code <source-slug>`，生成 `pkg`、`pkg/components`、`pkg/symbol/button` 这类 package/category/symbol Node；
+3. **代码投影** — 对代码快照执行 `/context:compile --aspect code <source-slug>`，生成 `pkg`、`pkg/components`、`pkg/symbol/button` 这类 package/category/symbol Node；
 4. **对齐** — `/context:align` 将文档原料归位至 Node 结构，包括挂靠到已有 code symbol Node 的手册、示例和经验；
 5. **编译** — `/context:compile` 由 AI 将文档原料加工为结构化 Section；
 6. **检索** — `/context:query <问题>` 在本地知识中查询答案，返回 Node 与 Section 级引用；代码工作区可用 `--evidence code|prose|all` 区分代码证据和文档证据；

package/plugin/commands/align.md

@@ -37,6 +37,8 @@ Run the expected view commands from the envelope. For additional reads, use only
 
 When a view returns `page.next_command`, follow that command to continue the same semantic view. Use `--source`, `--heading`, `--window`, or `--token-budget` only as view filters; do not inspect workflow files, cache files, host tool-results, or stdout fragments with generic tools.
 
+If a blocks view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, the response is a partial read. Do not finalize broad ownership or dense planned Sections from source-mapping/headings alone; follow `page.next_command` or the `how_to_explore[]` source full-read / expand-budget command first, then decide whether the remaining evidence needs sections or can stay context-only.
+
 ### Step 3 — Produce The Semantic Payload
 
 Reuse existing knowledge before inventing new Nodes: use `context mdrive glossary match <name>` and `context mdrive node list --format json` for term/entity reuse.
@@ -46,6 +48,7 @@ Apply packaged `context:skill-align-workflow` Node classification gates and stru
 Use CLI diagnostics instead of static prompt rules:
 
 - `diagnostics.automatic_ownership_adjustments[]` explains mechanical external-reference demotions and the explicit ownership override shape.
+- `pending-relation-refs` lists explicit Parent/Children/Related markdown links. Reuse existing target Nodes when present; keep unresolved target slug hints deferred instead of writing dangling `contains_parent`.
 - Validation diagnostics identify contiguity, citation eligibility, ownership, and mount-matrix problems.
 - `views[]` and `diagnostics` distinguish citable evidence from supporting context; do not infer citation eligibility from raw ownership prose.
 

package/plugin/commands/capture.md

@@ -1,6 +1,6 @@
 ---
 description: "Capture URLs, local Markdown, source code, stdin path lists, inbox/refresh sources, or conversation notes as Context sources."
-argument-hint: "[url | ./path.md [./more.md...] | --code [paths...] | --stdin | --inbox | --refresh | note]"
+argument-hint: "[url | ./path.md [./more.md...] | --code [paths...] | --aspect <name...> | --stdin | --inbox | --refresh | note]"
 allowed-tools: Bash(context:*, bun:*, brew:*, curl:*, sh:*, scoop:*, choco:*, lark-cli:*), WebFetch
 ---
 
@@ -30,6 +30,7 @@ Invocation note: code capture does not run through `npx`. `context capture --cod
 - `$ARGUMENTS` contains `--refresh` → `context capture --refresh`. This refreshes active Feishu URL sources and local Markdown sources whose stored origin file still exists; code sources use `context capture --code`.
 - User asks for code capture with explicit `--module` flags → run `context capture --code $ARGUMENTS`, preserving code flags such as `--module`, `--version`, `--version-from`, and `--no-runner-cache`.
 - User asks to refresh/re-capture an already configured code source → run `context capture --code` unless the user explicitly wants to change package selection or version flags. The CLI reuses stored `capture_config`, appends a new snapshot only when code/version content changes, and never overwrites prior snapshots.
+- User asks to run a configured custom aspect capture → run `context capture --aspect <name...> --format json`. Do not use `context capture --aspect code`; code capture remains `context capture --code` because it owns target path, `--module`, version, and runner-cache flags.
 - User provides one or more code target paths, or asks for code capture without explicit `--module` flags → run `context capture --code $ARGUMENTS --format json` directly. The CLI preflights every target first; if any target is ambiguous it returns candidates without writing, otherwise it captures all selected code targets serially.
   - If the CLI returns candidate packages, ask the user which package paths to capture.
   - Then run `context capture --code <original-target-if-present>` with one repeated `--module <path>` for every selected package. The CLI derives and stores path filtering silently from that selection.
@@ -58,11 +59,12 @@ Do not pipe the heredoc through another command, and do not discover files with
 Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
 
 - Run `context status --format json` and use its `next_step.command` / `workflow.next_step`.
+- If JSON status reports `incremental.pending_align.status: "pending"` with `count > 0`, suggest `/context:align` even when a previous finalized align workflow or prose `workflow.next_step` says compile. Newly captured structure work must be routed through align before compile.
 - If status says aligned knowledge is missing or alignment is required → suggest `/context:align`.
 - If status says compile work is pending for Markdown / evidence-backed knowledge → suggest `/context:compile`. Mention `/context:align` only if the user wants to revise the structure.
-- If the capture was code-only and status reports pending code projection, suggest the CLI-owned code route: `/context:compile code <source-slug>` or `context compile code <source-slug>`, followed by `context compile close` when the CLI asks for close.
+- If the capture was code-only and status reports pending code projection, suggest the CLI-owned code route: `context compile --aspect code <source-slug>`, followed by `context compile close` when the CLI asks for close.
 
-Never suggest prose compile or hand-built code knowledge for a code-only source. Code snapshots become active knowledge only through `context compile code`, which materializes package/category/symbol Nodes deterministically.
+Never suggest prose compile or hand-built code knowledge for a code-only source. Code snapshots become active knowledge only through `context compile --aspect code`, which materializes package/category/symbol Nodes deterministically.
 
 If capture is rejected with `agent_hints[].code = "workflow-cross-family-rejected"`, do **not** run `context workflow abandon ...` automatically. First run or ask the user to run `context workflow status --format json` and explain that another workflow is active in this workspace. Continue that workflow when it is the intended task; ask the user before abandoning it when the user wants to discard that in-progress work. If the user expected a different repository/workspace, change to the confirmed workspace root before retrying capture.
 
@@ -75,7 +77,7 @@ Stable structure:
 1. Completion headline. Single line with the action verb plus core counts: how many sources were captured this round, broken down by `new` / `updated` / `unchanged`. Capture data from `context capture ... --format json` `result.summary` (or per-source statuses when no aggregate is returned).
 2. Per-source list grouped by status. Show each captured source under one of three groups (`new` / `updated` / `unchanged`); within each group list the document title (`source.title`), kind label, and a short delta indicator for updated sources (for example added/removed line counts when the CLI returns them; otherwise "content changed"). Cache-hit code packages belong in `unchanged`. Omit groups that are empty.
 3. Pending workflow signals. When `context status --view summary --format json` reports follow-up work tied to this capture (sources pending align, sources pending compile, refreshed sources pending recompile, code sources pending projection), summarize each as a single line naming the work and which sources are affected. Omit the section entirely when there is no pending follow-up.
-4. Next step. Single command suggestion driven by status: `/context:align` when structure work is pending, `/context:compile` when prose compile work is pending, `context compile code <slug>` (or `/context:compile code <slug>`) when code projection is pending. If nothing is pending, say so explicitly.
+4. Next step. Single command suggestion driven by status: `/context:align` when structure work is pending, `/context:compile` when prose compile work is pending, `context compile --aspect code <slug>` when code projection is pending, or `context compile --aspect <name>` when a custom aspect projection is pending. If nothing is pending, say so explicitly.
 
 Do not include raw CLI diagnostics, agent_hints content, schema names, or workflow payload identifiers in the report. Those belong in earlier troubleshooting output, not in the completion summary.
 
@@ -105,5 +107,5 @@ Your prose to the user follows the user's conversation language. CLI commands, f
 - In `--format json`, code capture runner cache state is authoritative in `result.runner.cacheMode`: `prepared` means a workspace runner was prepared, `cached` means workspace cache hit, and `bypass` means `--no-runner-cache` used a temporary runner directory instead of the workspace runner cache.
 - Aspect snapshots default to `evidence.mode: none`. Prose-like custom aspects must opt in with `evidence: { mode: block }` in `aspects/<name>/aspect.yaml` before they generate evidence manifests. Invalid `evidence.mode` values are reported as `evidence-policy-invalid`; they are not silently treated as `none`.
 - Code aspect snapshots ship with `evidence.mode: none`; symbols/files/edges are indexed inside the code bucket. Do not ask users to inspect or repair a code `.evidence` manifest.
-- Code aspect capture writes raw code snapshots first. Materialize them with `context compile code <slug>` (or no slug for all actionable code sources) before prose align needs to attach documentation to code Nodes.
+- Code aspect capture writes raw code snapshots first. Materialize them with `context compile --aspect code <slug>` (or no slug for all actionable code sources) before prose align needs to attach documentation to code Nodes.
 - On duplicate capture of the same URL: identical `content_hash` → CLI skips with `unchanged`; different hash → CLI appends a new snapshot.

package/plugin/commands/compile.md

@@ -1,6 +1,6 @@
 ---
 description: "Compile the confirmed align plan into source-linked knowledge through CLI-guided workflow steps."
-argument-hint: "[--plan|code <slug>]"
+argument-hint: "[--plan|--aspect code [slug]|--aspect <name>|--all]"
 allowed-tools: Bash(context:*)
 ---
 
@@ -18,7 +18,9 @@ Naming convention:
 
 - **Default** — follow `context compile scan --format json` and the returned `next_action` until compile is closed or no work remains.
 - **`--plan`** — validate per-Node draft changes without closing or writing active knowledge; stop after the planned changes are reported.
-- **`code [selector]`** — run `context compile code [selector]`, report the CLI result, and stop unless the CLI asks for a follow-up close. The selector may be omitted to process all actionable code sources; when present, the CLI resolves source slug, package name, or module path.
+- **`--aspect code [selector]`** — run `context compile --aspect code [selector]`, report the CLI result, and stop unless the CLI asks for a follow-up close. The selector may be omitted to process all actionable code sources; when present, the CLI resolves source slug, package name, or module path.
+- **`--aspect <name>`** — run deterministic custom aspect projection for one configured aspect. Use `context compile --aspect <name> --allow-large-deprecate` only when the CLI rejected a large deprecate and the user confirms the runner output is intentionally empty or reduced.
+- **`--all`** — run `context compile --all` to materialize code projection first and then custom aspect projections in deterministic order.
 - **Delegated** — add `--delegated` only when the user explicitly authorized delegated/automatic mode at the start of this conversation. Do not infer it from vague "continue" permission.
 
 ### Core Rules
@@ -42,15 +44,21 @@ Protocol discovery:
 3. Run `context compile scan --format json` (or `context compile scan --delegated --format json` only for explicit delegated mode).
 4. If the scan returns `stop_noop` or no changed work, report that compile stopped before draft and no files were written.
 
+Run `context compile scan` only for this initial preflight unless the CLI explicitly returns it as the next command after a terminal/no-work state. During an active compile workflow, discover the next node from the current envelope (`next_action`, `views[]`, `workset_progress`) and follow returned commands; do not rerun scan between node cycles to probe for the next node.
+
 ## Main Loop
 
 Repeat until the CLI returns `stop_noop`, `close_compile` succeeds, or a blocking user question remains.
 
+Carry the latest envelope forward between iterations. After a successful node cycle, continue from its returned `next_action.command` / `workset_progress` rather than restarting at `context compile scan`.
+
 ### Step 1 — Read Expected Views
 
 Run expected view commands from the envelope before writing. For compile evidence, prefer the CLI-returned source-ref/scaffold views. They may expose:
 
-- `citable_source_refs[]` — the only refs eligible for draft `source_refs`.
+- `source_refs_index_command` / `source_refs_command` — compact block-id evidence index for drafting; use `items[].block_id` in `source_block_ids[]`.
+- `source_refs_detail_command` — detailed source refs with quote previews; open only when the compact index is not enough.
+- `citable_source_refs[]` — detailed-view refs eligible for draft citations; prefer `block_id` values in `source_block_ids[]`.
 - `supporting_context_refs[]` — background/framing only.
 - `required_preserved_literals[]` — URL, code identifier, `source_ref`, or `block_id` literals that must stay visible in the generated content or repair report.
 - diagnostics such as citation eligibility, source support, coverage, engagement, and advisory foldbacks.
@@ -78,6 +86,8 @@ Use typed diagnostics as the repair contract:
 - `reason_code`, `path`, and `missing[]` identify what to fix.
 - `diagnostics.auto_repaired[]` records mechanical repairs; warning severity must be surfaced in the final report.
 - `diagnostics.warnings[]` with info/advisory severity are not write blockers unless `blocking: true` or the next action says so.
+- `agent_recommended_action` classifies warning handling: `ignore` means continue unless the user asks for cleanup, `respond_optional` means repair only when semantically useful, and `respond_required` means resolve before the returned write action can succeed.
+- `source_support` is advisory lexical diagnostics, not a keyword gate. Do not patch drafts only to satisfy term overlap. Blocking evidence checks should come from invalid source refs, changed evidence boundaries, URL preservation, split-by-evidence candidates, or explicit top-level `next_action`.
 - stale prepare refresh returns `review_reconcile_decisions` with `reason_code: "prepare_refreshed"`; reread the new prepare result before reviewing.
 
 Do not recover by replaying an old manual path, editing rendered files, or guessing schema aliases.
@@ -86,4 +96,4 @@ Do not recover by replaying an old manual path, editing rendered files, or guess
 
 When `next_action.kind` is `close_compile`, execute `context compile close` through packaged `context:skill-compile-close` or the returned command. Never claim success unless close exits 0 and verify is green, except the explicit no-work path.
 
-Report in the user's conversation language. Include semantic apply counts, close/verify status, warning-level `auto_repaired[]`, and before/after workspace totals. Do not surface internal workflow payload digests, source-ref hashes, archive paths, or absolute file paths unless a user-facing report view explicitly returns them.
+Report in the user's conversation language. Include semantic apply counts, close/verify status, warning-level `auto_repaired[]`, `ready_with_debt` coverage/review-debt summaries when present, and before/after workspace totals. Do not surface internal workflow payload digests, source-ref hashes, archive paths, or absolute file paths unless a user-facing report view explicitly returns them.

package/plugin/commands/init.md

@@ -87,28 +87,27 @@ If the user request names specific aspects, map that directly:
 - "all aspects" / "全部 aspect" → append `--with-all-aspects`
 - "no aspects" / "不安装 aspect" / "minimal" → append `--no-aspects`
 
-Otherwise ask **one** multi-select question. The first option **must** be a `skip` choice so the user can always submit (host multi-choice tools such as Claude Code `AskUserQuestion` refuse to submit when zero boxes are checked). Pre-check `code` as the recommended default.
+Otherwise ask **one** short single-choice question. Keep the option count to three or fewer; host question tools reject longer option lists. Use the host's free-text `Other` escape hatch when the user needs a custom comma-separated aspect list.
 
 ```
-Q. Which aspects should be installed? (multi-select)
-  A. skip — install no aspects now; add later with `context init --with-aspects <name>`
-  B. code — scripted local source-code capture. (Recommended; pre-checked)
-  C. design-system — placeholder aspect template.
-  D. openapi — placeholder aspect template.
-  E. graphql — placeholder aspect template.
+Q. Which aspects should be installed?
+  A. code — scripted local source-code capture. (Recommended)
+  B. all built-in aspects — code, design-system, openapi, graphql.
+  C. skip — install no aspects now; add later with `context init --with-aspects <name>`.
 ```
 
 Hard rules when mapping into the host UI:
 
-- The `skip` option **must** be present as the **first** choice. Do not relabel it `Other`, do not omit it, do not assume the host's auto-injected `Other` covers it. `Other` (if present) is a free-text escape hatch and is unrelated to "skip".
-- Pre-check `code` so the user can submit immediately to get the recommended setup.
-- The user cannot submit zero boxes — they always pick at least `skip` or one aspect. If they pick `skip` together with any aspect, treat `skip` as the winner and ignore the others.
+- Do not present separate options for every built-in aspect; that exceeds host option limits once `skip` is included.
+- Put `code` first and mark it as recommended.
+- Treat the host auto-injected `Other` as a free-text custom list such as `code,openapi`, not as "skip".
 
 Map the answer:
 
+- `code` selected → append `--with-aspects code`.
+- `all built-in aspects` selected → append `--with-all-aspects`.
 - `skip` selected → append `--no-aspects`.
-- One or more aspects selected (without `skip`) → append `--with-aspects <comma-separated names>`, e.g. `--with-aspects code,openapi`.
-- Host auto-injected `Other` selected → ignore it, fall back to the recommended default `--with-aspects code`.
+- Host auto-injected `Other` selected → parse the user's comma-separated aspect names and append `--with-aspects <names>`. If the custom text is empty or invalid, ask once for clarification rather than silently installing all aspects.
 
 Do not silently install all aspects when the user asked for a code-only workspace.
 

package/plugin/commands/status.md

@@ -11,8 +11,10 @@ Run `context status` from the active workspace root only. `status` is intentiona
 Surface the CLI's output verbatim — its trailing suggestions are already actionable. Do not invent additional suggestions; the CLI decides what to recommend based on the workspace state. Typical recommendations you will see:
 
 - Run `/context:align` when there is active raw material but no align plan yet (compile's Stage 1 prerequisite).
+- Run `/context:align` when JSON status reports `incremental.pending_align.status: "pending"` with `count > 0`. This structural signal takes precedence over a previous finalized align workflow's compile hint.
 - Run `/context:compile` when align plan exists and raw is newer than the last compile.
 - Run `/context:capture --code` when the repo is a git checkout but no source-code snapshot has been captured yet.
+- Run `context compile --aspect code` when code projection is pending, or `context compile --aspect <name>` when a custom aspect projection is pending. JSON status includes `aspect_projection` and `code_projection` summaries for these deterministic paths.
 
 Recent CLI output may include `incremental.cache_status`, `incremental.pending_align`, and `incremental.pending_compile`. Surface those fields verbatim. If the user asks what they mean, explain that they show the local incremental cache health and queued align/compile work; cache warnings are informational unless the CLI output includes a blocking error or an explicit next action.
 

package/plugin/skills/skill-align-workflow/SKILL.md

@@ -20,6 +20,7 @@ Run `context align scan --format json`, read expected evidence views, produce se
 - Existing knowledge is the lookup registry. Use `context mdrive glossary match <name>` and `context mdrive node list --format json`; do not read `knowledge/**` or create a separate registry file.
 - Code projection Nodes are reusable knowledge handles. When document evidence belongs on a code symbol, reuse the code slug instead of creating a parallel document Node.
 - `diagnostics.automatic_ownership_adjustments[]` and validation diagnostics are the mechanical external-reference ownership source of truth. Independent reference definitions, pure URLs, relation kind blocks, and multiline reference-only lists default to context_only; submit an explicit `block_ownership[]` owned/shared entry only when such a reference block is primary citation evidence.
+- When `pending-relation-refs` is present, inspect it before finalizing graph structure. Use existing matches for `contains_parent_ref` or `domain_gate.child_refs`; keep unresolved target slug hints deferred and do not write dangling parent or edge refs.
 - `views[]` and diagnostics distinguish citable evidence from supporting context. Do not promote supporting/context-only material into cited Sections unless a later ownership correction makes it citation-eligible.
 - Keep cache-friendly prompt order: fixed protocol/schema first, existing knowledge lookup second, source evidence views third, current semantic payload last. Preserve CLI JSON order and do not add timestamps, random ids, scratch paths, or host paths to generated payloads.
 - Node type, tag, fake-Entity, `domain`, and `action` gates are in `references/gates.md`.
@@ -44,6 +45,8 @@ Run `views[].command` entries marked `expected: true` before writing. Use additi
 
 Read evidence through semantic CLI views, not shell parsing. Follow `page.next_command` for pagination. Use `--source`, `--heading`, `--window`, and `--token-budget` as view filters only. `--unwrap` removes workflow metadata; it does not expand a compact view into full detail.
 
+If a blocks view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, treat that response as a partial read. Do not finalize source-wide ownership or dense planned Sections from source-mapping/headings alone; follow `page.next_command` or the `how_to_explore[]` source full-read / expand-budget command first, then decide whether to write, split, or leave evidence as context.
+
 ### Step 3 — Reuse Existing Knowledge
 
 Query existing knowledge for reusable names before proposing new term/service/system/action Nodes. Exact title/slug/alias hits should usually become references to the existing Node, not duplicate candidates.
@@ -62,7 +65,7 @@ For large or batched payloads, use `references/density-profile.md` and `referenc
 
 Use `next_action.input_schema` or the matching `context schema <name> --view minimal --format json` output to shape the payload.
 
-For `submit_structure_decision`, produce one structure-decision document with finalized Nodes, document edges, planned Sections, and ownership. Keep only source-supported semantic decisions in the payload; leave mechanical repair and patch routing to CLI diagnostics.
+For `submit_structure_decision`, produce one structure-decision document with finalized Nodes, document edges, planned Sections, and ownership. Planned Sections must carry the strongest source-backed `section_kind` that fits the current schema priority chain; do not plan an entire dense source as `description` when the evidence clearly contains examples, comparison tables, Q&A, decisions, specs, warnings, or principles. Keep only source-supported semantic decisions in the payload; leave mechanical repair and patch routing to CLI diagnostics.
 
 For coarse-read, candidate-op, patch, ownership, or rescan actions, follow the command and schema in the returned `next_action`. Do not carry old candidate-table, decision-patch, or full-tree payload shapes forward.
 

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 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.
+- 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, surface the CLI-returned coverage view commands / `available_actions[]` instead of inventing a local decision matrix. 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. |

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

@@ -4,7 +4,7 @@ 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[]`,
+  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.
@@ -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.
+- 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 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.
+- 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` 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 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,17 +59,27 @@ 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`.
+
+Minimal valid draft envelope:
+
+```json
+{
+  "schema_version": "compile.draft.v2",
+  "node_slug": "<matches node.slug>",
+  "actions": []
+}
+```
 
 `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.
 
-`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`.
+`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`.
 
 ## Section Kind Choice
 
@@ -95,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 |
@@ -138,15 +152,16 @@ 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. 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.
+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`.
 
@@ -154,6 +169,6 @@ Rendered knowledge starts with optional `c4a:summary`, then the active `content`
 
 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.
 
-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.
+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-judge/SKILL.md

@@ -28,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>

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
@@ -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,7 +120,7 @@ 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 the review diagnostic's explicit repair options and cited item ids, then rerun `context reconcile review`.