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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.38-beta.3",
+  "version": "0.5.39",
   "type": "module",
   "bin": {
     "context": "./cli.js"

package/plugin/commands/align.md

@@ -17,9 +17,10 @@ Run `context align scan --format json`.
 Use the returned `workflow.next-action-envelope.v2` as the source of truth:
 
 - Follow top-level `next_action.kind` and `next_action.command` for every write.
-- Use `views[].command` for evidence reads, prioritizing entries with `expected: true`.
+- Use only the returned `next_action.command` for the next required step. When it points at `read-plan`, run that one command first.
 - Treat `allowed_actions[]` as permission for read-only insertions such as `show_view`; do not choose a different write path from it.
 - Treat `agent_hints[]`, when present, as a temporary mirror or diagnostic only. If it conflicts with `next_action`, follow `next_action`.
+- Read workflow payload views only through returned `context workflow show` commands.
 
 For protocol discovery, prefer narrow commands:
 
@@ -27,17 +28,17 @@ For protocol discovery, prefer narrow commands:
 - `context protocol show align-compile --format json`
 - `context schema align-structure-decision --view minimal --format json`
 
-### Step 2 — Read Evidence Through Views
+### Step 2 — Read Evidence Through The Single Evidence Path
 
-Run the expected view commands from the envelope. For additional reads, use only budget-safe workflow views such as:
+If scan returns a `read-plan` command, run it and then follow the next command returned by that view. The normal path is:
 
-- `context workflow show --payload align-segments --view blocks --page-size 10 --token-budget 8000 --unwrap --format json`
-- `context workflow show --payload align-segments --view windows --page-size 10 --compact-hints --unwrap --format json`
-- `context workflow show --payload align-segments --view source-mapping --unwrap --format json`
+- `read-plan` summarizes source size, active source set, navigation/placeholder sources, and the next evidence command.
+- `source-bundle` returns the selected source text with `@c4a` block annotations. Read it, then write an align structure-decision JSON yourself; do not pipe the bundle text into `context align validate`.
+- `blocks`, `windows`, `block-index`, `source-mapping`, and `pending-relation-refs` are detail views only. Use them when the read-plan/source-bundle next action or `how_to_explore[]` asks for a narrow follow-up.
 
 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.
+If a detail view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, the response is a partial read. Return to the read-plan/source-bundle continuation instead of treating that partial JSON page as the complete source.
 
 ### Step 3 — Produce The Semantic Payload
 
@@ -54,7 +55,7 @@ Use CLI diagnostics instead of static prompt rules:
 
 ### Step 4 — Validate And Submit
 
-When the envelope asks for `validate_align_decision`, submit the structure-decision payload to `context align validate --input - --format json` or the exact returned command. If validate returns blocking diagnostics, repair the payload and rerun validate. If validate returns a `submit_structure_decision` next_action, execute that command with the validated payload.
+When the envelope asks for `validate_align_decision`, submit the structure-decision payload you authored after reading evidence to `context align validate --input - --format json` or the exact returned command. If validate returns blocking diagnostics, repair the payload and rerun validate. If validate returns a `submit_structure_decision` next_action, execute that command with the validated payload.
 
 For any other write kind, execute the top-level `next_action.command` exactly. If the command rejects the payload, follow the returned `next_action` and `reason_code`; do not infer a route fallback from memory.
 

package/plugin/commands/capture.md

@@ -18,9 +18,9 @@ Capture is entirely CLI-driven — your role is to route the right `context capt
 
 Do not run hand-written dependency preflight commands before `context capture --code`. The CLI owns TypeScript runner/plugin resolution and returns structured `agent_hints[]` when the runner is missing or misconfigured.
 
-If `context capture --code ...` fails with install or runner hints, surface the CLI's `agent_hints[]` install command exactly as printed. Ask the user once whether to run that command on their behalf; global installs touch shared state, so explicit confirmation is required before invoking `Bash`. If approved, run the exact command from `agent_hints[0].command`, then retry the original `context capture --code ...` invocation. If declined, leave the command visible so the user can run it manually. Do not inline `@c4a/extract-ts`, do not hand-write code snapshots, and do not continue with partial capture.
+If `context capture --code ...` fails with install or runner hints, surface the CLI's `agent_hints[]` install command exactly as printed. Ask the user once whether to run that command on their behalf; global installs touch shared state, so explicit confirmation is required before invoking `Bash`. If approved, run the exact command from `agent_hints[0].command`, then retry the original `context capture --code ...` invocation. If declined, leave the command visible so the user can run it manually. Do not inline extraction packages, do not hand-write code snapshots, and do not continue with partial capture.
 
-Invocation note: code capture does not run through `npx`. `context capture --code` resolves `@c4a/extract` and `@c4a/extract-ts` from the installed `@c4a/context-cli` package using Node package resolution, prepares a user-cache aspect runner wrapper, and executes that wrapper directly. The plugin must therefore be available to the same global install that provides `context`.
+Invocation note: code capture does not run through `npx`. The default code aspect uses the `@c4a/extract` runner and `@c4a/extract-ts` plugin bundled into the installed `@c4a/context-cli`, then records the bundled runner identity in the user-cache manifest. Only non-default runner/plugin packages configured in `aspects/code/aspect.yaml` need to be resolvable from the same global install that provides `context`; when they are missing, the CLI returns structured install hints.
 
 ### Route by argument
 

package/plugin/commands/compile.md

@@ -37,12 +37,11 @@ Protocol discovery:
 - `context protocol show align-compile --format json`
 - command-specific `context schema <name> --view minimal --format json`
 
-## Preflight
+## Start
 
-1. Run `context doctor`. If output-align errors block compile, tell the user to run `/context:align` and stop.
-2. Run `context status --format json` and `context mdrive workspace stats --format json` for before/after reporting.
-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.
+1. Run `context compile scan --format json` (or `context compile scan --delegated --format json` only for explicit delegated mode).
+2. If the scan returns `stop_noop` or no changed work, report that compile stopped before draft and no files were written.
+3. Run `context status --format json` or `context mdrive workspace stats --format json` only when needed for the final before/after report or when the CLI asks for diagnostics. Do not run doctor/status/source-list as a required preflight before following a valid compile scan or align-finalize handoff.
 
 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.
 
@@ -58,6 +57,7 @@ Run expected view commands from the envelope before writing. For compile evidenc
 
 - `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.
+- `request_full_text_command` / `--view text` — narrow text view for one block when quote preview is not enough; this is still Node-scoped, not a workspace evidence bundle.
 - `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.
@@ -87,7 +87,7 @@ Use typed diagnostics as the repair contract:
 - `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`.
+- `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, unsupported confirmed hard facts, or explicit top-level `next_action`. URL preservation, section kind precision, example formatting, and summary style are advisory/debt unless the CLI explicitly marks them blocking.
 - 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.

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

@@ -7,13 +7,13 @@ description: "Internal procedure for /context:align. Reads CLI-guided align evid
 
 ## TL;DR
 
-Run `context align scan --format json`, read expected evidence views, produce semantic structure payloads, and follow top-level `next_action`. The CLI owns route, validation, repair commands, and stage guards; this skill owns only semantic classification and source-bound structure judgment.
+Run `context align scan --format json`, follow the top-level `next_action.command` to read the CLI-selected evidence path, produce semantic structure payloads, and continue following top-level `next_action`. The CLI owns route, validation, repair commands, and stage guards; this skill owns only semantic classification and source-bound structure judgment.
 
 <reference>
 
 ## Canonical Data
 
-- `workflow.next-action-envelope.v2` is authoritative. Branch on `next_action.kind`, execute `next_action.command` for writes, and use `views[].command` for budget-safe evidence reads.
+- `workflow.next-action-envelope.v2` is authoritative. Branch on `next_action.kind`, execute `next_action.command`, and treat `views[].command` as detail reads rather than a checklist.
 - `allowed_actions[]` may permit extra read-only work before the next write; it is not a menu of alternate write paths.
 - `agent_hints[]`, when still present, is a short-term cutover mirror or diagnostic. Do not prefer it over top-level `next_action`.
 - Schema names and enum values come from `context schema <name>`; use `--view minimal` for protocol discovery before full schema reads.
@@ -39,13 +39,15 @@ Run `context align scan --format json`. Confirm `schema_version: "workflow.next-
 
 If no envelope is present, stop and surface the CLI output; do not reconstruct an align route from old prompt memory.
 
-### Step 2 — Inspect Expected Views
+### Step 2 — Follow The Evidence Read Path
 
-Run `views[].command` entries marked `expected: true` before writing. Use additional `show_view` commands only when listed in `allowed_actions[]` or returned in `how_to_explore[]`.
+Run the returned `next_action.command`. For structural align work this is normally `read-plan`; after that, follow the `read-plan` / `source-bundle` response's `next_action.command`.
+
+`read-plan` is the navigation surface. It chooses whether the next evidence read is a whole-batch `source-bundle`, a scoped source/window bundle, or an existing coarse-read route. `source-bundle` is annotated source text; read it and then author the requested align JSON yourself. Never pipe bundle text into `context align validate`.
 
 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.
+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; continue the current detail view only when `page.next_command` is explicitly needed, otherwise return to the read-plan/source-bundle continuation.
 
 ### Step 3 — Reuse Existing Knowledge
 
@@ -65,7 +67,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. 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 `submit_structure_decision`, produce one structure-decision document with finalized Nodes, document edges, planned Sections, and ownership. Prefer the strongest source-backed `section_kind` that fits the current schema priority chain; avoid planning an entire dense source as `description` when the evidence clearly contains examples, comparison tables, Q&A, decisions, specs, warnings, or principles. Treat kind precision as a drafting quality preference, not a reason to block an otherwise source-backed write. 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.
 
@@ -78,7 +80,7 @@ If any write is rejected, follow the returned `next_action` and `reason_code`. D
 ### Step 7 — Self-verify
 
 - [ ] All writes followed top-level `next_action.command`. If not, return to **Step 1**.
-- [ ] Evidence was read through `views[].command`, `how_to_explore[]`, or CLI schema/protocol commands only. If not, return to **Step 2**.
+- [ ] Evidence was read through returned `next_action.command`, `how_to_explore[]`, or CLI schema/protocol commands only. If not, return to **Step 2**.
 - [ ] Node classification used the semantic gates in `references/gates.md`. If not, return to **Step 4**.
 - [ ] URL/reference ownership followed CLI diagnostics, not static prompt rules. If not, return to **Step 5**.
 - [ ] Structure decisions passed `context align validate --input - --format json` before finalize. If not, return to **Step 6**.

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

@@ -2,7 +2,7 @@
 
 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.
+This reference applies only when the current envelope asks for `next_action.kind: "submit_coarse_read"`. In normal direct routes, read-plan/source-bundle already selected the evidence path; do not emit a `single_pass` coarse-read payload unless the CLI requested coarse-read.
 
 | Profile | Use When | Agent Behavior |
 |---|---|---|

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

@@ -23,14 +23,14 @@ Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update`
 - 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.
+- Pick `kind` from the CLI's `context schema compile-draft` contract, especially `section_kind_priority` and the mount matrix. Treat kind precision as a drafting quality preference, not a reason to loop forever when the CLI accepts the write. A `decision` needs at least two surfaced alternatives plus a reason; bare "we use X because Y" is usually `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_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.
+- 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. If the CLI later reports URL, example, section-kind, or summary-style issues as advisory/debt, do not patch solely for those unless the cited source meaning is materially lost.
+- Preserve literals surfaced by the CLI when they are part of the user-facing knowledge. When source-refs or scaffold output lists `required_preserved_literals[]`, keep source-backed URL, code identifier, `source_ref`, or `block_id` literals visible in the relevant `content`, `summary`, skip reason, or repair challenge when doing so carries meaning. Do not rely on memorized URL rules; let CLI literal fields and citation diagnostics define what matters, and treat URL/style preservation warnings as advisory unless the next action is blocking.
 - `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 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.
@@ -158,10 +158,10 @@ For each classified snippet:
    - 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. 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.
+4. Preserve `required_preserved_literals[]` from the CLI evidence view when the literal is part of the source-backed knowledge. For link-heavy citation-eligible evidence, keep meaningful URLs in `content` when the action writes knowledge; for supporting-only literals, keep them in the repair/challenge context instead of citing them. Do not patch only to satisfy non-blocking URL or style advisories.
 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_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.
+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; invalid evidence references remain blocking.
 
 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`.
 

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

@@ -29,7 +29,7 @@ decisions only; the CLI reviews, applies, and writes every workspace change.
 - 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.
 - `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.
+- Evidence-boundary errors and unsupported confirmed hard facts remain blocking evidence issues. Missing URLs, section kind precision, example formatting, summary style, and lexical hard-term spelling/casing/punctuation/paraphrase mismatches are advisory unless the active CLI `next_action` explicitly blocks on them.
 - 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/references/temporal-and-evidence.md

@@ -51,12 +51,12 @@ When the prepare item carries long `proposed.content` or a `proposed.summary`, t
 - Preserve prepared `content` and `summary` on executable write decisions (`merge_update`, `supersede.new`, `keep_separate`, `split_then_reanchor` sub-Sections) unless the decision intentionally rewrites the user-facing content.
 - The only legitimate way to clear `summary` is an update-style decision that explicitly emits `summary: null` as the chosen outcome.
 
-## Example content preservation repair
+## Example content preservation advisory
 
-If review reports that a cited example evidence contains a command / config / code fence missing from `proposed.content`, repair:
+If review reports that a cited example evidence contains a command / config / code fence missing from `proposed.content`, first check the CLI issue severity and next action.
 
-- **Preferred**: regenerate the decision with the relevant fenced block included in `proposed.content` (preserve language, fences, and exact code).
-- **Fallback only after user confirmation**: keep a prose-only example summary, mark the final decision `decided_by: user` per `references/user-confirmation.md`. Auto mode is not user confirmation.
+- **When blocking**: regenerate the decision with the relevant fenced block included in `proposed.content` (preserve language, fences, and exact code), then rerun review.
+- **When advisory/debt**: do not patch solely for formatting. Patch only if the missing command/config/code changes the user-facing meaning or the user asks for fidelity cleanup.
 
 ## How this slots into the main procedure
 

package/templates/aspects/README.md

@@ -29,11 +29,11 @@ Unlike the align/compile pipeline (LLM-driven, designed for unstructured documen
 ├── README.md               ← This file
 ├── code/
 │   ├── aspect.yaml         # Built-in code aspect (generated when selected during init)
-│   └── prompt.md           # Agent/human hint only; CLI does not read it
+│   └── README.md           # Aspect maintainer guide; CLI does not read it
 ├── <your-aspect>/
 │   ├── aspect.yaml         # Required: aspect definition
 │   ├── extract.ts          # Aspect plugin module (local mode)
-│   └── prompt.md           # Optional: hint for humans/agents
+│   └── README.md           # Optional: maintainer guide for humans/agents
 └── <another-aspect>/
     └── ...
 
@@ -470,14 +470,14 @@ When the user chooses to install the code aspect, `context init` generates `aspe
 # View the current CLI-bundled template (read-only):
 context aspect template code
 
-# Write the latest template to aspects/code/ (overwrites aspect.yaml, preserves prompt.md):
+# Write the latest template to aspects/code/ (overwrites aspect.yaml, preserves README.md):
 context aspect template code --write
 
 # Diff current file against the latest template:
 context aspect template code --diff
 ```
 
-> `--write` will not overwrite `prompt.md` (user-edited agent hints). To reset prompt.md, delete it first, then `--write`.
+> `--write` will not overwrite `README.md` (user-edited maintainer guide). To reset README.md, delete it first, then `--write`.
 
 ---