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

package/plugin/commands/compile.md

@@ -1,167 +1,89 @@
 ---
-description: "Compile the confirmed align plan into knowledge articles: draft, semantic reconciliation, apply, then close."
-argument-hint: "[--plan]"
+description: "Compile the confirmed align plan into source-linked knowledge through CLI-guided workflow steps."
+argument-hint: "[--plan|code <slug>]"
 allowed-tools: Bash(context:*)
 ---
 
-<!--
-This command is slightly over the 30-line default because it carries
-the default-mode vs `--plan`-mode comparison inline; the mode contrast
-belongs here rather than split across skill references.
-The agent protocol itself still delegates to internal packaged procedures.
--->
+## Your Task
 
-## Your task
-
-Synthesise the finalized align plan into knowledge through semantic CLI operations. If the user explicitly authorized托管/全自动/delegated mode at the start of this conversation, create the compile workflow with `--delegated`; otherwise stay in manual/default mode. The agent produces compile draft JSON per Node; the CLI owns storage, rendering, verification, and workflow payload persistence. Read workflow payloads with `context workflow show`; write through `context compile`, `context reconcile`, and `context mdrive` operations, never through direct workspace file tools.
+Synthesize finalized align structure into knowledge. The CLI owns workflow routing, validation, reconciliation, apply, close, payload storage, and recovery commands. The agent reads evidence and emits semantic payloads only when `next_action` asks for them.
 
 Naming convention:
 
 - `/context:*` names user slash commands.
 - `context ...` names CLI primitives.
-- Internal packaged procedures invoked by slash workflows are not user slash commands. Do not invent extra slash-command entrypoints for draft or close stages.
+- `context:skill-*` names packaged internal procedures, not user slash commands.
+
+### Modes
+
+- **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.
+- **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
+
+- Follow top-level `next_action.kind` and `next_action.command` for every write.
+- Use `views[].command` for evidence reads, prioritizing `expected: true`.
+- Treat `allowed_actions[]` as permission for read-only insertions; it is not a menu of alternate write paths.
+- Treat `agent_hints[]`, when present, as a temporary mirror or diagnostic. If it conflicts with `next_action`, follow `next_action`.
+- Do not use direct file tools, shell scripts, `jq`, `sed`, `cat`, `head`, `tail`, Python, or Node.js to inspect workspace storage, workflow payload files, or `--format json` stdout.
+
+Protocol discovery:
+
+- `context schema workflow.next-action-envelope.v2 --view minimal --format json`
+- `context protocol show align-compile --format json`
+- command-specific `context schema <name> --view minimal --format json`
+
+## Preflight
+
+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.
+
+## Main Loop
+
+Repeat until the CLI returns `stop_noop`, `close_compile` succeeds, or a blocking user question remains.
+
+### 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`.
+- `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.
+
+Follow `page.next_command` for pagination. Use `how_to_explore[]` for narrow reads. Do not expand workflow payloads through host tool-results. Node-cycle receipts are compact by default; `actions_meta[]` exposes current draft action handles for patching without an extra status read.
+
+### Step 2 — Produce Payloads Only When Requested
+
+For `submit_compile_cycle`, load the Node evidence via the returned command/views, invoke packaged `context:skill-compile-draft` for exactly one Node, and pass the emitted JSON on stdin to the returned `next_action.command`.
+
+For `continue_compile_cycle`, do not invoke the draft skill and do not attach `--input`; execute the returned `next_action.command` exactly. `--continue` resumes a saved draft session. If it returns `status: "noop"`, follow the returned `close_compile` next action.
+
+For `patch_compile_draft`, submit only the patch schema requested by the CLI. Use `actions_meta[].action_id` for `replace_action` / `remove_action`, or `add_action` with `before` / `after`; do not use generic `op/path/value` aliases.
+
+For `review_reconcile_decisions`, load the prepare payload through CLI views such as `context workflow show --payload prepare --unwrap --format json`, invoke packaged `context:skill-compile-judge` when semantic judgment is needed, run `context reconcile validate --mode compile --node <slug> --decisions - --format json`, repair any blocking diagnostics, then pass validated decisions to the returned review command.
+
+Invoke `context:skill-compile-judge` only when the top-level `next_action.kind` is exactly `review_reconcile_decisions`. If `questions` are present but `next_action.kind` is `patch_compile_draft`, patch the draft first; do not infer judge mode from question counts.
+
+For `apply_reconcile_review`, `close_compile`, `finish_current_node`, `submit_coverage_disposition`, or `abandon_or_rescan`, execute the returned command exactly. If it rejects, follow the new `next_action` and `reason_code`.
+
+### Step 3 — Repair From Diagnostics
+
+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.
+- 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.
 
-Modes:
+## Close And Report
 
-- **Default (no flag)** — draft plan + semantic reconciliation + apply writes + close.
-- **`--plan`** (opt-in when `$ARGUMENTS` contains `--plan`) — per Node, run `context compile --draft <slug> --input - --plan` so the CLI validates stdin draft content without writing active knowledge; surface a user-facing change list (new knowledge, replaced knowledge, unchanged knowledge, and why) while keeping internal Section ids / source refs in details only when needed, then **stop at the end of the per-Node loop — do NOT run close**. The user re-runs `/context:compile` without `--plan` to apply; that run does the real writes + close.
-- **`--code [slug]`** — run the CLI-owned code projection route directly with `context compile --code [slug]`, report its output, then stop. This route does not enter doctor/draft/reconcile and uses the same deterministic implementation as `context align --code`. It materializes code snapshots into package/category/symbol Nodes; run `context compile --close` afterward only when the CLI asks for close.
-
-Delegated workflow mode:
-
-- If the user explicitly authorized托管/全自动/delegated mode at the start of this conversation, add `--delegated` to the first compile workflow-creating command, preferably `context compile --scan-changes --delegated --format json`. Do not add it for vague "continue" / "继续" permission.
-- `--delegated` is a workflow-level authorization, not a per-review override. It only lets the CLI auto-accept low-risk weak lexical support when `source_support.missing_hard_terms` is empty; missing hard facts, type drift, schema errors, ownership/structure challenges, and destructive gates still block.
-- Never hand-author `decided_by: delegated_agent`; the CLI injects it only inside a delegated compile workflow.
+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.
 
-Language policy: your explanatory prose and final reports follow the user's conversation language. Node titles, summaries, and user-facing draft explanations follow `NodeContext.generation_policy.language` when the CLI provides it. Source-bound compile draft `content` should stay close to the cited source language when it differs from the workspace language; do not translate cited English facts into Chinese just to match the workspace. Section `summary` is a compact reader/query aid derived from `content`; source_support hard-term matching checks `content`, not `summary`. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. CLI stdout/stderr, the canonical `processing <slug>` lines, paths, slugs, block ids, source refs, issue codes, flags, and command names stay as printed.
-
-Stable prompt/output policy: keep fixed protocol, schema, mount matrix, and workspace lookup context before per-Node payloads. For repeated Nodes, use the same command order and consume CLI JSON as-is. Do not add current timestamps, random ids, storage paths, or host absolute paths to draft payloads or reports unless the CLI explicitly returned them as semantic workspace facts.
-
-Preflight:
-
-1. Run `context doctor`; output-align group must be green. If it reports missing aligned knowledge, tell the user to run `/context:align` and stop. Incremental cache group warnings are informational here; only output-align errors block compile.
-2. Run `context mdrive workspace stats --format json`, `context source list --format json`, and `context status --format json`; record the before counts and `STATUS.semantic.refreshed_source_pending_compile.source_ids[]`. This status means newer raw snapshots exist; it does not mean finalized ownership or `node.sources[]` are already refreshed.
-3. Run `context compile --scan-changes --format json` and parse the JSON as `COMPILE_WORKSET`. If delegated workflow mode is explicitly authorized, run `context compile --scan-changes --delegated --format json` for this first scan instead. `--scan-changes` is the only workset scan flag; `--plan` is reserved for draft validation.
-   - If `context workflow status --format json` has `current: null` but `last_published` is present, continue with `context compile --scan-changes`; the published finalized ownership is still the workspace structure truth. Use `context workflow list --format json` only when you need lineage/history diagnostics.
-   - Compile JSON may include `source_finalize`; use it as lineage for the finalized ownership that produced the current Node set and citation ownership.
-   - If `COMPILE_WORKSET.reason` is `no-changed-nodes` and there are no refreshed sources pending compile, report `no changed nodes`; stop before invoking the draft procedure, running any draft command, or running close.
-   - If `COMPILE_WORKSET.status` is `unknown-input`, continue conservatively using the Nodes listed in `COMPILE_WORKSET.nodes`; keep the `unknown_inputs[]` reasons in the final report.
-   - Otherwise process only `COMPILE_WORKSET.nodes`, preserving the CLI order. Per-Node `processing <slug>` echoes must match this order.
-
-Review input rule: normal compile flow reads the current prepare payload automatically: pass decisions with `context reconcile review --decisions - --view status`. Add `--prepare-digest` only when you intentionally want an explicit stale guard. Never pass prepare files or hand-edited review output to apply; once review writes a ready artifact for the current workflow scope, plain `context reconcile apply` consumes it.
-
-Semantic decision schema discovery: run `context schema semantic-decisions` for JSON, or `context schema semantic-decisions --format yaml` for readable YAML. Do not infer it from memory, and do not hand-edit review output; once `context reconcile review` writes a ready review artifact for the current workflow scope, plain `context reconcile apply` consumes it without re-reading any decisions file.
-
-`source_ref` values are opaque citation tokens. Copy them from CLI payloads into draft/reconcile decisions exactly as printed; do not parse, normalize, or dereference them as file paths.
-
-Do not use Python, Node.js, shell, or other ad-hoc scripts to preprocess, filter, summarize, or inspect ReconcileContext / review payloads. Do not use `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect workspace storage or temporary workflow artifacts. Consume the structured output from `context reconcile prepare` and `context reconcile review` directly, and pass agent-authored draft/decision payloads through stdin rather than scratch files. Never extract `review.apply_document` manually; the CLI applies the ready review artifact stored under the current workflow scope.
-
-Refreshed-source loop:
-
-1. If `STATUS.semantic.refreshed_source_pending_compile.source_ids[]` is non-empty, process each source id before the per-Node draft loop. Compile context refreshes deterministic stale source ownership when possible; if the CLI reports `source-ownership-stale`, rerun `context align --scan` and finalize before compiling that source.
-2. Run `context reconcile prepare --mode refresh --source <source-id> --format json`. Feed stdout to packaged `context:skill-semantic-reconcile`; the output includes `workflow_payload.digest` for review. Do not reconstruct the semantic decision shape from memory.
-   - The prepare output omits refresh sections whose evidence block hash is unchanged. If it returns a single `status: "unchanged"` / `change_status: "unchanged"` item, report that no semantic refresh decisions are needed for that source and continue with the filtered compile workset.
-3. Pass the skill output to `context reconcile review --decisions - --view status`. Use stdout for readiness/issues/questions; apply reads the ready review artifact from the workflow scope. Resolve questions exactly like the per-Node loop, including `support_confirmation`, `scope_review_required`, and `omit_confirmation` handling.
-4. Default mode only: run plain `context reconcile apply` after `context reconcile review` returns `ready_to_apply: true`; the CLI loads the unique ready review for the current workflow scope. If questions were answered, rerun review on the updated decisions to refresh the ready artifact, then run `context reconcile apply` again. In `--plan` mode, stop after review and report the not-written refresh decisions.
-5. After all refreshed sources are applied in default mode, run `context compile --scan-changes --format json --ignore-source <source-id>` with one `--ignore-source` flag for each refresh-applied source. Use that filtered result for the per-Node loop. This does not rebuild section fingerprints early; it only removes Nodes whose remaining changed blocks came entirely from sources already handled by refresh reconciliation. If a Node still has changed blocks from other sources, unknown inputs, or full-context reasons, keep it in the ordinary per-Node loop.
-
-Per-Node loop:
-
-Process Nodes sequentially. `/context:compile` may cover a multi-Node workset, but each Node must finish its own `context → draft → prepare → review → apply` loop before you apply another Node. Do not run multiple Node draft/reconcile/apply chains in parallel or bury several Node failures inside one shell batch. Capture/align can be broad; compile write decisions must be per-Node and complete.
-
-1. For every workset Node, run `context compile --context <slug> --format json`. If the refreshed-source loop applied any source, append the same `--ignore-source <source-id>` flags used for the filtered workset. The JSON stdout is a compact summary with workflow payload handles; do not extract digests by hand. First inspect citation handles with `context compile --context <slug> --view source-refs --token-budget 2000 --format json` or `context workflow show --payload node-context --view source-refs --token-budget 2000 --unwrap --format json`; this source-refs view is only a projection of `NodeContext.raw_snippets[]`, not a separate data source. If it returns `truncated: true`, follow `how_to_explore[]` to narrow by `--source` / `--heading` or expand the budget. Only expand the durable NodeContext when you are ready to pass its returned `.value` object to the draft skill. NodeContext is derived only from finalized ownership: `primary_evidence` and citation-eligible `shared_evidence` may be cited; `context_only` and every secondary shared snippet are background only and must not be cited. If NodeContext includes `generation_policy`, apply it to generated titles, summaries, and user-facing explanations; for source-bound draft `content`, prefer the cited source language when it differs. Do not default Node titles/summaries to English scaffolding such as "How-To", "Strategy", or "Architecture" when the workspace language is not English. `context compile --context <slug> --request-full-text <block_id> --format json` may expose visible evidence text for inspection, including primary evidence; read expanded page text from `request_full_text.pages[].text`. Long blocks are returned as line-bounded pages with `request_full_text.pages[].next_command`; follow that command to continue reading the same block. `raw_snippets[].quote` mirrors the same page text beside source_ref metadata, but `request_full_text.pages[]` is the explicit page API. Do not use file tools to bypass the page. Full-text inspection does not promote secondary shared evidence into citation eligibility; if the block should support this Node, emit `pending_ownership_challenge` or `structure_challenge` instead of writing a Section. When the workset requires full context, the NodeContext payload has `incremental.status: "full-context"` with the `unknown_inputs[]` reasons from the same entrypoint. `incremental.locator_only_changes[]` entries with `agent_action: "none"` are close-time maintenance only; do not draft them. The CLI stores the durable NodeContext and coverage candidates as workflow payloads, not root scratch files. Do not expand the context with direct file tools; the NodeContext payload is the evidence boundary. Prefer citation-eligible refs for citeable evidence and treat `context_only` as background. Do not repeatedly slice saved NodeContext JSON manually; use source-refs, coverage-summary, coverage detail filters, and returned `how_to_explore[]`.
-2. Invoke packaged `context:skill-compile-draft` and follow its procedure to emit draft JSON. Do not reconstruct the draft shape or Section classification rules from memory; the draft skill carries the canonical kind priority, mount matrix, examples, and reflection gates. Section writes use `content` plus optional `summary`; new Sections do not need `section_id`, and the op is exactly `op: "add"` because compile-draft `actions[]` already targets Sections. Do not use align-style op names such as `add_section` or `propose_section`. Cite raw via `source_refs: [...]` chosen from `raw_snippets[].source_ref`; use a single-element array for one citation, and use multiple refs only when the Section content actually consumes all of them. The CLI may auto-narrow over-wide citations and leaves removed refs uncovered. The CLI rejects retired `body` / `detail` / `raw`, singular `source_ref`, and quoted-evidence fields with canonical repair hints. If a note or changed raw snippet should be reviewed but intentionally not written, emit `op: "skip"` with the relevant `source_refs: [...]`; a bare skip is only for deterministic no-op cases. If a NodeContext contains only navigation or placeholder evidence (`Parent` / `Children` / `Related` / `Relations`, "no detailed content", etc.), emit `skip`; do not create a low-value `description` Section from that navigation line just to satisfy the workflow.
-3. Fast path: pass the draft to `context compile --node-cycle <slug> --input - --accept-safe-defaults --format json`. This validates the draft, prepares reconcile, reviews mechanically safe defaults, and applies only when no semantic judgment remains. If stdout returns `status: "applied"`, continue to the next Node. If it returns `status: "partial-applied"` or `status: "review-required"`, use the returned `prepare` / `review` handles and continue with the manual path below for only the remaining questions/issues; do not rerun the earlier context/source-ref reads. When you need to patch a remaining action after prepare, run `context compile --draft-status <slug> --format json`; each action backed by the latest prepare payload includes `reconcile_item_id` and `source_support`, so use that claim id instead of guessing.
-4. Manual path: pass the draft to `context compile --draft <slug> --input - --plan --prepare --format json`. This validates schema, source refs, and mount matrix, stores the compile draft as a workflow payload, and prepares the semantic reconcile payload without writing active knowledge. Default stdout is a compact prepare summary; use it to inspect readiness. If semantic judgment is needed, load the full prepare payload with `context workflow show --payload prepare --unwrap --format json` and feed that full payload to packaged `context:skill-compile-judge`. The judge output is the decision input for `context reconcile review`; keep `skill-semantic-reconcile` for refresh/drop or non-compile reconcile flows. For triage-only inspection, use `context workflow show --payload prepare --view issues --unwrap --format json`; add `--status unsupported`, `--status weak`, `--item-id <claim-id>`, or `--page-size <n>` instead of expanding huge prepare payloads. If all pending items are mechanically safe defaults, prefer `context reconcile review --accept-safe-defaults --view status` instead of invoking the skill. If most items are safe and only a few need explicit decisions, combine `--accept-safe-defaults` with `--decisions -` and submit only those explicit decisions. If the CLI returns draft revision hints, use `context compile --draft-status <slug> --format json` and `context compile --draft-patch <slug> --input - --plan` so only the affected action is revised; draft-status includes the action `reconcile_item_id` after prepare, plus `source_support`, so `act_005` and `claim-005` stay mechanically linked. Draft-patch `schema_version` may be omitted, or use `patch_schema_version` from draft-status if you include it. Then rerun `context compile --draft <slug> --plan --prepare --format json` with no `--input`; it reloads the saved patched draft. On hard rejection after a draft session is saved, read `context compile --draft-status <slug> --format json`, patch only the failed actions, and retry.
-5. Review the prepared context before accepting defaults. Treat lexical `source_support` as a diagnostic; final support and relation judgment belong to `context:skill-compile-judge`, which must compare only listed candidates and include the same-source-ref multi-kind semantic-role check. Do not copy raw text merely to raise matched-term counts; there is no separate default `evidence-echo` warning, and preserved prose/bullets are valid only when they are active user-facing knowledge. Treat `temporal_prior` and candidate `temporal_disposition` as context for your rationale only; they do not change `default_decision` or make merge/supersede mechanically safe. If the prepare output has `items: []`, use its `next_decisions_template` as the decisions document for review; do not pass the whole prepare context as `--decisions`.
-   - If `agent_hints[]` contains `compact-source-low-coverage` or `dense-source-low-coverage`, return to the same compile draft and add actions for the suggested uncovered evidence before semantic review. Treat the reported coverage count (`covered/total`, remaining snippets) as a required self-check, not polish. A supported first quote only proves that one action is valid; it does not prove the Node is complete.
-   - If close later reports unresolved coverage, first inspect `context workflow show --payload coverage-candidates --view coverage-summary --token-budget 2000 --unwrap --format json`. Use `available_actions[]` and, when needed, narrow with `context workflow show --payload coverage-candidates --view coverage --type <issue-type> --token-budget 2000 --unwrap --format json` or `--node <slug>`. Then use `context compile --context <slug> --cover-uncovered-only --format json` to start a targeted repair draft, or `context compile --coverage-skip-unresolved --coverage-disposition-node <slug> --reason "<reason>"` only when all unresolved candidates for that node are intentionally excluded for the same reason. Use targeted `coverage-disposition` only when candidates need different outcomes.
-6. Pass the judge skill output to `context reconcile review --decisions - --view status`. Use stdout for compact readiness/issues/questions. If questions are returned, ask the user in business language and convert unresolved `ask_user` items into final actions before applying. For `support_confirmation`, use `question.group_key` when present: group only questions that share that key and are all ordinary content-compression checks; ask once with a compact list of claims and cited evidence. If the user confirms the group, keep each final write action and add `decided_by: user`. Do not group questions that add new facts, have missing hard facts, or have different source/evidence boundaries. If review reports unsupported evidence, revise the draft or rerun the judge with corrected source_refs rather than forcing a decision. For `scope_review_required`, run `context:skill-semantic-reconcile` once more over the prepare context and current decisions before asking the user; if it still cannot resolve the scope, ask the user. For `omit_confirmation`, ask the user; only a confirmed no-write answer may become `action: omit` with `decided_by: user`. Never mark `decided_by: user` on your own; auto mode or permission to continue is not user confirmation.
-7. Default mode only: run plain `context reconcile apply` after `context reconcile review --view status` returns `ready_to_apply: true`; the CLI applies the unique ready review for the current workflow scope. If questions were answered, rerun review on the updated decisions, then run `context reconcile apply` again. This writes active knowledge, verifies, and records the semantic ledger. In `--plan` mode, stop after review and report the not-written decisions.
-8. Persistent failure → stop and surface the full rejection list; never edit rendered files to bypass.
-
-Close (default mode only — skip entirely in `--plan` mode):
-
-1. Invoke packaged `context:skill-compile-close`; it triggers `context compile --close`, which refreshes locator-only evidence, canonicalizes source refs, compacts derived knowledge files, verifies the final workspace, rebuilds section fingerprints, and refreshes the incremental cache.
-2. Run `context verify` as a second pass if the skill escalated any issue. Run `context mdrive workspace stats --format json` and `context source list --format json` and diff against the before counts.
-3. Run `context mdrive node list --format json` to collect semantic node handles for the final report. Use `node_class` to keep concrete entities, term definitions, domains, and actions visibly separated. If the user explicitly asks for file links, use an explicit human/report view when available; those links are user inspection aids, not workflow inputs.
-
-`context compile --close` may archive explicit debug scratch files through the CLI-owned output lifecycle. Normal compile state lives in workflow-scoped payloads. Current align state is internal CLI state, not a file protocol. Do not move, delete, or archive workspace output files yourself; the CLI owns that lifecycle.
-
-Close only projects finalized Nodes that materialize as a CLI-written knowledge article or as an explicit no-write placeholder declared by align with `planned_sections: []`. A compile skip action records reviewed no-write evidence, but it does not by itself turn an arbitrary finalized Node into a placeholder.
-
-In plan mode, your final report is the aggregated user-facing change list across all Nodes + "re-run `/context:compile` without `--plan` to apply"; do not run `context compile --close` or `context verify` (they only make sense against a real write).
-
-Never claim success unless `context compile --close` exited 0 and `context verify` is green. The only exception is the `no-changed-nodes` gate, where you report that compile stopped before draft and no files were written. Never hand-write rendered knowledge, index, or changelog files — the CLI is the sole writer.
-Never use Read / Glob / Grep / Write against workspace storage; use `context workflow`, `context compile`, `context reconcile`, `context source`, `context query`, and `context mdrive`.
-For large draft payloads, feed stdin directly into the `context compile` command with a heredoc. Do not pipe a heredoc through another command and do not redirect generated content into workspace files. Do not pipe `context ... --format json` through `python3`, `node`, `jq`, `sed`, `cat`, `2>&1`, or shell fallback wrappers. For draft schema discovery, run `context schema compile-draft` for readable YAML or `context schema compile-draft --format json` for machine-readable JSON:
-
-```bash
-context compile --draft billing-api --input - --plan --prepare --format json <<'JSON'
-{
-  "schema_version": "compile.draft.v2",
-  "target_node": "billing-api",
-  "actions": [
-    {
-      "op": "add",
-      "kind": "description",
-      "content": "Billing API exposes invoice lookup and payment capture endpoints.",
-      "source_refs": ["src-1#billing-api L10-18@7a6f4c9d2e10"]
-    }
-  ]
-}
-JSON
-```
-
-For reviewed no-write material, keep the evidence in the skip action so semantic review can record it:
-
-```bash
-context compile --draft billing-api --input - --plan --prepare --format json <<'JSON'
-{
-  "schema_version": "compile.draft.v2",
-  "target_node": "billing-api",
-  "actions": [
-    {
-      "op": "skip",
-      "reason": "reviewed; intentionally not written",
-      "source_refs": ["src-1#reviewed-note L12-14@7a6f4c9d2e10"]
-    }
-  ]
-}
-JSON
-```
-
-For navigation-only or placeholder-only context, no active Section is the correct result:
-
-```bash
-context compile --draft billing-api --input - --plan --prepare --format json <<'JSON'
-{
-  "schema_version": "compile.draft.v2",
-  "target_node": "billing-api",
-  "actions": [
-    {
-      "op": "skip",
-      "reason": "navigation-only context; align graph already preserves parent/child/related structure"
-    }
-  ]
-}
-JSON
-```
-
-Final report contract (default mode):
-
-- Report in the user's conversation language.
-- Keep a stable structure with these semantic sections; translate section headings into the user's conversation language instead of copying these English labels verbatim:
-  1. Completion headline.
-  2. Semantic apply table. Include refreshed-source rows first in source-id order when the refreshed-source loop ran, then one row per Node in align frontmatter order. Columns: target (source id or Node title/slug), type (`refresh` or Node type), and the `context reconcile apply --format json` counts: `applied`, `skipped`, `merged`, `superseded`, `kept_separate`, `omitted`, and `questions_resolved`. Include `reanchored`, `removed_unsupported`, and `split_then_reanchored` only when non-zero.
-  3. Close stage with `context compile --close` result, final node/section totals, verify status, changelog stamp, incremental counts (`recompiled`, `locator_updates`, `canonical_source_ref_updates`, `rebuilt`), section fingerprint rebuild count, and archive status / archived file count when reported by CLI. Do not use close output as the semantic apply summary; aggregate the per-Node `context reconcile apply` results from Step 6.
-  4. Before/after status diff table with at least total nodes, node counts by type, total sections, and last compile time.
-  5. Knowledge objects by semantic handle. Include every Node slug and `node_class` returned by `context mdrive node list --format json`; group or label term definitions separately from concrete entities when useful. Include human-readable links only when an explicit human/report view returns them, and state that they are not workflow inputs.
-  6. Optional next step only when there is a concrete useful follow-up (for example recapture stale material or run `/context:align` to revise structure).
-- Do not say the user can inspect files without providing links.
-
-Final report contract (`--plan` mode):
-
-- Use the same stable shape where possible, but make the headline clearly indicate that this was a plan-only run.
-- Replace the close-stage section with a not-written section and tell the user to re-run `/context:compile` without `--plan` to apply.
-- Do not include knowledge file links for files that were not written.
+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.

package/plugin/commands/context.md

@@ -4,7 +4,7 @@ argument-hint: "<free text | url | source-id | question>"
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Inspect `$ARGUMENTS` and delegate to the most appropriate subcommand. Route without running anything of your own first — let the target subcommand drive.
 

package/plugin/commands/drop.md

@@ -4,7 +4,7 @@ argument-hint: "<source-id|url> [--reason <text>] [--yes]"
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Retract a source without losing the audit trail. The CLI owns source resolution, impact planning, semantic decision application, knowledge cleanup, source stamp, changelog append, and verify; the agent presents the impact plan and waits for confirmation.
 
@@ -23,3 +23,16 @@ Language policy: any prose you speak directly to the user follows the user's con
 Never Read / Glob / Grep / Write workspace files directly. All workspace access goes through semantic CLI commands such as `context drop --plan`, `context reconcile prepare --mode drop`, `context reconcile review`, `context drop --apply-plan`, and `context source`. If you need the semantic decision shape, run `context schema semantic-decisions` for JSON or `context schema semantic-decisions --format yaml` for readable YAML; do not infer it from memory.
 Never use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect or preprocess workspace storage or temporary workflow artifacts. Consume CLI JSON/YAML/text outputs directly. Do not pipe `context ... --format json` through `python3`, `node`, `jq`, `sed`, `cat`, `2>&1`, or shell fallback wrappers.
 Plan handoff is workflow-scoped. Run `context drop --plan <target> --format json`; the CLI stores the drop-plan payload in the current workflow. `--save-output` is only for an explicit human-readable scratch copy and must not be passed to later steps.
+
+## Final Report
+
+Report in the user's conversation language. Translate section headings into the user's language instead of copying the English labels below verbatim. Optimize for human readability: name the dropped source by its title, use Node titles instead of slugs, and use Section kind plus heading for each archived Section. Do not surface source ids, content hashes, archive directory paths, semantic ledger ids, or workflow payload identifiers.
+
+Stable structure:
+
+1. Completion headline. Single line naming the dropped source by title plus verify status (for example "「<source title>」 dropped, verify ok"). Capture data from `context drop --apply-plan --format json`.
+2. Affected Node tree. Group archived Sections by their owning Node. Each Node entry shows the Node title and Node type; below it list the archived Sections with their kind plus a short heading/preview that identifies which Section was archived (not the section id). Include Nodes whose alias mappings or visibility changed even when no Section was archived. Omit the tree entirely when the plan was a no-op or alias-reindex-only.
+3. Variance summary. Bullet list of counts: archived Sections, affected Nodes, semantic decisions applied, and the final verify status. Show every counter so the user can verify nothing unexpected fired, including zeros.
+4. Next step. Single command suggestion: `/context:status` to inspect the current knowledge distribution, or `/context:purge` when the user wants to permanently clear the archived snapshots.
+
+Do not include raw drop-plan digests, archive directory paths, or workflow payload identifiers in the report. Those belong in earlier troubleshooting output, not in the completion summary.

package/plugin/commands/extract.md

@@ -4,7 +4,7 @@ argument-hint: "<path> [--format json|jsonl|pretty]"
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Run `context extract $ARGUMENTS` and stream the CLI's stdout back to the user.
 

package/plugin/commands/init.md

@@ -10,7 +10,7 @@ UX before `context init` runs) lives inline here per the slash-command
 length exemption for self-contained slash commands.
 -->
 
-## Your task
+## Your Task
 
 Initialize a context workspace, including layout, default-language, and focus confirmation before creating it.
 
@@ -70,7 +70,10 @@ Q. What will this workspace mainly hold?
 Interpret the answer:
 - Chose A–D → generate a 2–3 line focus description in the user's language. Phrase it as
   "primarily X; supporting materials such as Y may also be filed here" rather than exclusion
-  language — workspaces absorb auxiliary material in practice. Pass it as `--focus "..."`.
+  language — workspaces absorb auxiliary material in practice. Show the exact generated focus
+  text to the user and ask for one confirmation before running `context init`. If the user
+  approves, pass it as `--focus "..."`; if the user edits it, pass the edited text as
+  `--focus "..."`; if the user declines or says to skip, run without `--focus`.
 - Chose E or described freely → pass the user's text verbatim as `--focus "..."`.
 - User says "skip" / "don't care" → run `context init` without `--focus`.
 - `$ARGUMENTS` already contains `--focus "..."` → skip this step entirely.

package/plugin/commands/purge.md

@@ -4,7 +4,7 @@ argument-hint: "[--yes]"
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Purge the workspace archive. This is destructive: it deletes all restorable
 source/knowledge artifacts created by `context drop --apply-plan`.

package/plugin/commands/query.md

@@ -4,7 +4,7 @@ argument-hint: "<question>"
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Naming convention:
 

package/plugin/commands/status.md

@@ -4,7 +4,7 @@ argument-hint: ""
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Run `context status` from the active workspace root only. `status` is intentionally local-only and does not walk up from child directories. If the CLI reports `workspace-not-found`, relay that error and ask the user to rerun from the workspace root or initialize with `/context:init`; do not probe storage paths to discover a workspace.
 

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

@@ -1,29 +1,29 @@
 ---
-name: context-align-workflow
-description: "Internal procedure for /context:align. Read align workflow schemas, operate candidate ledger payloads, and produce an align-structure-decision for CLI finalize."
+name: skill-align-workflow
+description: "Internal procedure for /context:align. Reads CLI-guided align evidence, applies semantic Node classification gates, and emits align structure-decision payloads for CLI validation/finalize."
 ---
 
 # Align Workflow Procedure
 
 ## TL;DR
 
-Run the align workflow through the CLI-owned beta.8 payload chain: scan segments, prepare neutral candidate operations, finalize an `align-structure-decision`, and let the CLI write finalized ownership.
+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.
 
 <reference>
 
 ## Canonical Data
 
-- Schema names are exposed by `context schema <name>`.
-- Candidate ledger and aggregate payloads are mechanical inputs only.
-- Finalized structure is represented by `align-structure-decision`.
-- Retired payloads include candidate tables, decision patches, and full-tree finalize documents.
-- Existing knowledge is the lookup registry. Use `context mdrive glossary match <name>` / `context mdrive node list --format json` for term/entity reuse; do not read `knowledge/**` and do not create a separate registry file.
-- Code projection Nodes are existing knowledge handles. When document evidence belongs on a code symbol, reuse the code slug instead of creating a parallel document Node. If the slug exists only as projected code knowledge and is not yet in finalized prose ownership, declare that same slug in the current `nodes[]`, add the prose `planned_sections`, and route `sections[].owner` plus `block_ownership[].owners` to it.
-- Keep cache-friendly prompt order: fixed protocol and schemas first, existing knowledge lookup second, source-shared payload views third, current candidate batch last. Preserve CLI JSON order and do not add timestamps, random ids, scratch paths, or host paths to generated payloads.
-- `align-segments.generation_policy` is the workspace language contract for generated Node titles, summaries, rationale prose, and planned Section wording. Source-bound Section wording should stay close to the cited source language when it differs from the workspace language. Preserve product names, code identifiers, slugs, flags, `block_id` handles, and `source_ref` tokens exactly when needed.
-- Source titles and headings are ordinary evidence, not structural authority. Do not automatically copy them into Node titles or aliases; classify the evidence referent first, then generate a title that fits the final Node type.
+- `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.
+- `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.
+- 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.
+- `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`.
-- Coarse-read density and neutral signal rules are in `references/density-profile.md`.
+- Coarse reading density and neutral signal rules are in `references/density-profile.md`.
 - Candidate anomaly handling, `label_hint`, and `llm_slug_hint` reference rules are in `references/candidate-resolution.md`.
 
 </reference>
@@ -32,69 +32,53 @@ Run the align workflow through the CLI-owned beta.8 payload chain: scan segments
 
 Use this only inside `/context:align`.
 
-1. Start from `align-segments`.
-2. Inspect it through semantic CLI views, not shell parsing: `context workflow show --payload align-segments --view segment --unwrap --format json`, `context workflow show --payload align-segments --view source-mapping --unwrap --format json`, `context workflow show --payload align-segments --view blocks --token-budget 2000 --unwrap --format json`, and `context workflow show --payload align-segments --view windows --unwrap --format json`. Read and obey `generation_policy` before authoring any title, summary, rationale, or planned Section wording. Use `source-mapping` for source-to-block id ranges before writing coarse-read `evidence_blocks`; drill into content with `--source <source-id>`, `--heading <prefix>`, `--window <window-id|src-N:M>` (`src-N:M` means the M-th window under `source_alias` src-N from `--view windows`), or a larger `--token-budget <n>`. If a budgeted view returns `truncated: true`, follow `how_to_explore[]` commands before expanding the budget. `--unwrap` only removes the workflow metadata envelope; it does not change the selected view.
-3. Query existing knowledge for reusable names before proposing new term/service/system/action Nodes. `context mdrive glossary match <name>` returns deterministic `match.kind`, `match.matched`, and `match.rank`; exact title/slug/alias hits should usually become references to the existing Node, not duplicate candidates.
-4. Produce coarse-read anchors and neutral content signals as JSON. Pick `density_profile` using `references/density-profile.md`; content signals describe text shape only, not final Node type. Submit the artifact through stdin with `context align --coarse-read - --format json`. Prefer omitting `schema_version`; the CLI infers single-source vs batch from shape. The latest `align-coarse-read` payload is only the most recent checkpoint; durable multi-source reading notes live in `align-candidate-ledger.source_readings`. For multiple sources, submit one envelope with `coarse_reads[]`; each entry must use the current coarse-read fields (`source_id`, `density_profile`, `reading_anchors`, `section_proposals`), not retired `reading_notes` / `block_readings`.
-5. Produce candidate ops batches as JSON. Before each batch, refresh the Node classification gates in `references/gates.md`; their TTL is one batch or about ten candidates, whichever comes first. Candidate slugs/titles are provisional: if a source heading says "方案", "架构", "流程", "策略", "演练", or similar scope/process language, do not preserve that wording unless the final Node type really needs it. Use `local:<name>` only inside the current batch; submit each batch through stdin with `context align --ops - --format json`. Prefer omitting `schema_version`; the CLI normalizes candidate ops to the current schema. `--ledger-digest <digest>` is optional; usually omit it and pass it only when you intentionally want stale-batch rejection for a high-assurance retry. The CLI reducer assigns durable candidate ids. For `merge_into`, `supersede`, and `reject`, include the required `*_label_hint` fields from the visible candidate labels.
-6. Read the CLI-written candidate ledger and aggregate with `context workflow show --payload align-candidate-ledger --view ledger --unwrap --format json` and `context workflow show --payload align-candidate-aggregate --view aggregate --unwrap --format json`. To revisit one source's coarse-read notes, add `--source <source-id>` to the ledger view; candidates do not carry source ids, so add `--status` or `--candidate-id` only when you also need candidate rows. Treat aggregate fields as mechanical statistics and warnings, not semantic recommendations. Review `anomaly_signals[]`; address clear mistakes with another ops batch, otherwise continue. These signals are warnings and do not by themselves block finalizing.
-7. If the CLI returns `agent_hints[]`, follow them before retrying. Legacy-protocol hints mean the submitted payload/schema is retired; switch to the beta.8 schema named in the hint instead of reshaping old fields.
-8. Before producing `align-structure-decision`, refresh and apply `references/gates.md`: classify Node type in order (`action` scale + process evidence, then concrete/term `entity`, then child-bearing `domain`), reject fake Entities only when at least two suspicious signals match, keep `term` separate from concrete A/B tags, and provide required `action_gate` / `domain_gate` fields. Classification is about the content referent, not the source title. After type is chosen, rewrite the Node title to fit that type: Entities name concrete objects or atomic terms, Domains name grouping scopes, and Actions name executable processes.
-9. Produce `align-structure-decision` as JSON with finalized nodes, `contains_parent`, `depends_on`, and one `block_ownership[]` entry per coverable block. Node titles and summaries must follow the latest `generation_policy` language; do not default to English scaffolding such as "How-To", "Strategy", or "Architecture" when the workspace language is not English. Do not automatically add the original source title as an alias. Submit it through stdin with `context align --finalize -`; the CLI resolves the current align-segments payload. Prefer stable `llm_slug_hint` values for `contains_parent_ref`, `from_ref`, `to_ref`, owners, and section owners while the final slug is still being normalized.
+### Step 1 — Start From The Envelope
 
-   If `align-segments.incremental.mode` is `incremental`, finalize is a delta merge. Submit only the Nodes and ownership supported by the current scanned sources; reference previous finalized Nodes when they are parents, dependencies, domain children, owners, or visibility targets. Absence of an old Node or edge is not a delete signal. Do not redeclare an old parent/domain just to attach a new child. `sections[].owner` must be a Node declared in the current payload; previous finalized Nodes can be referenced structurally but do not receive new section plans from this incremental payload. Existing or previously removed Node slugs cannot change `node_type`; `context align --scan --full` does not bypass that guard. Use a new slug for a different type, or retire the old slug through `context drop` or explicit structure correction before re-aligning.
+Run `context align scan --format json`. Confirm `schema_version: "workflow.next-action-envelope.v2"`, then identify `next_action`, `views`, `workflow`, `route`, and `diagnostics`.
 
-   For code-projection Nodes, "existing knowledge file" and "previous finalized prose ownership" are different states. A freshly projected code Node can be reused by declaring the same slug in the current finalize payload and planning only prose-owned Sections for the current evidence. Compile merges the prose source and Sections into the existing code Node while preserving code metadata and code-owned Sections. Prose Sections must cite document evidence, not `aspect:code:*` source refs.
+If no envelope is present, stop and surface the CLI output; do not reconstruct an align route from old prompt memory.
 
-   `nodes[].planned_sections` is the distinct set of Section kinds planned for that Node. List each kind at most once; do not copy `sections[].section_kind` one-for-one when a Node has multiple Sections of the same kind.
+### Step 2 — Inspect Expected Views
 
-   For large finalize decisions, use `block_ownership_defaults[]` instead of enumerating every block. Each default names a `source_id` plus the same ownership fields as a block-level entry except `block_id`; the CLI expands it across that source's coverable blocks. Put only exceptions in `block_ownership[]`, which override defaults for their `block_id`. Keep the payload on stdin; do not generate temp JSON files just to list hundreds of ownership rows.
+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[]`.
 
-   If a finalized Node is intentionally navigation-only or placeholder-only, set `planned_sections: []` and keep its relation/placeholder blocks as `context_only` or `ignored`; do not assign `owned` evidence or plan a description solely to keep the Node alive. This is the expected placeholder-domain shape when the graph/slug is useful but the source has no citation-worthy body content. Compile close will create an empty placeholder Node with no active Sections.
+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.
 
-   Each `block_ownership[]` entry sets `ownership_role` to one of five values, and the **shape of the rest of the entry depends on the role**. Set `ownership_role` first and only include the fields that role requires; surplus fields trigger schema errors. The CLI returns `agent_hints[].correct_shape` with the canonical JSON skeleton on any role/field mismatch — reshape that entry to match it instead of guessing.
+### Step 3 — Reuse Existing Knowledge
 
-   - `owned`: exactly one slug in `owners[]`, plus `visible_to[]` and `reason`. Do not include `primary_owner` or `question_id`.
-   - `shared`: at least two slugs in `owners[]`, `primary_owner` chosen from those owners (the Node that authors cited Sections from this block; secondaries receive compact raw preview and must request full text or raise an ownership challenge before citing it), `visible_to[]`, `reason`. Do not include `question_id`.
-   - `context_only`: **omit `owners` and `primary_owner` entirely.** Required: `visible_to[]`, `reason`. Do not include `question_id`. Also use this for **external-URL reference-link blocks** (orphan `[label]: https://...` / `[label]: http://...` definitions, including ByteDance internal hosts and Lark / docs wikis) when no Node in this batch clearly owns the references — the URLs themselves are unique knowledge not duplicated in body prose, so they must stay reachable downstream even if no inline body usage exists. `context_only` keeps those URLs as raw background only; compile must not cite them as active Sections unless a later ownership patch upgrades the block to `owned` / primary `shared`.
-   - `ignored`: **omit `owners`, `primary_owner`, and `visible_to`.** Required: `reason`. Use for outdated markers, **intra-workspace navigation lines** (`Parent:` / `Children:` / `Related:` / `Relations:` rows whose targets are other Nodes already represented in the align graph), and placeholders without independent knowledge. **Do not put external-URL reference-link blocks here** — those carry unique URLs that the align graph cannot reconstruct; route them to `context_only` (or `owned` / `shared` if a Node should author a citation-eligible "相关链接" Section). Do not include `question_id`.
-   - `unresolved`: **omit `owners` and `primary_owner`.** Required: `question_id` (matching a top-level `unresolved[].question_id`) and `reason`. Use when classification is blocked by missing evidence.
+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.
 
-   After finalize, a second `context align --finalize` is rejected with `workflow-finalize-locked`; follow the returned `remediation_options[]` instead of resubmitting into the finalized workflow. Use `context workflow list --format json` when you need to audit finalize history.
+When a code projection Node already represents the object, reuse its slug for prose evidence and plan only prose-owned Sections for the current source evidence.
 
-   If finalize returns an `align-finalize-draft` payload, patch the saved draft instead of rewriting the whole finalize document. Use JSON Pointer paths from the returned issues and submit only the corrections. Patch paths are relative to `raw_decision`, so use `/nodes/...`, `/sections/...`, or `/block_ownership/...`, not `/raw_decision/...`:
+### Step 4 — Classify Semantic Structure
 
-   ```json
-   {
-     "schema_version": "align.finalize-patch.v1",
-     "operations": [
-       { "op": "replace", "path": "/block_ownership/3/primary_owner", "value": "rspack" }
-     ]
-   }
-   ```
+Apply `references/gates.md` before authoring Nodes: classify Node type in order (`action` scale + process evidence, then concrete/term `entity`, then child-bearing `domain`), reject fake Entities only when at least two suspicious signals match, keep `term` separate from concrete tags, and provide required gate evidence.
 
-   Submit it with `context align --finalize-patch - --format json`. Add `--payload-digest` only when you intentionally want an explicit stale guard. If issues remain, patch the remaining issue paths; if validation passes, the CLI commits the finalized workflow artifacts.
+Source titles and headings are ordinary evidence, not structural authority. Choose titles and summaries that fit the final Node type and the CLI-provided generation policy.
 
-   After finalize has succeeded, do not resend the full structure just to correct a few block roles. Submit a narrow ownership patch against the current finalized ownership digest:
+For large or batched payloads, use `references/density-profile.md` and `references/candidate-resolution.md` only when the CLI `next_action` asks for coarse-read or candidate-op payloads. Do not choose those stages yourself.
 
-   ```json
-   {
-     "schema_version": "align.ownership-patch.v1",
-     "base_digest": "sha256:<finalized-ownership-digest>",
-     "block_ownership": [
-       {
-         "block_id": "<block-id>",
-         "ownership_role": "owned",
-         "owners": ["<node-slug>"],
-         "visible_to": ["<node-slug>"],
-         "reason": "Why this block is citation evidence for the node."
-       }
-     ]
-   }
-   ```
+### Step 5 — Build The Payload Requested By `next_action`
 
-   Submit it with `context align --ownership-patch - --format json`. Keep `base_digest` in the patch body when you want stale ownership rejection. Use `context schema align-ownership-patch` when uncertain.
+Use `next_action.input_schema` or the matching `context schema <name> --view minimal --format json` output to shape the payload.
 
-Never write raw, cache, knowledge, `/tmp`, or workspace scratch files. Never pipe `context ... --format json` through `jq`, `head`, `tail`, `sed`, `cat`, `2>&1`, Python, Node.js, or shell scripts. Never read host persisted output files such as Claude `tool-results/**`; rerun a narrower `context workflow show` command instead. Never submit old candidate-table, decision-patch, or full-tree payloads.
+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 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.
+
+### Step 6 — Validate And Submit
+
+Before finalizing a structure decision, run `context align validate --input - --format json`. If validate returns blocking diagnostics, repair the exact paths it reports and rerun validate. If validate returns a finalize `next_action`, submit the same validated payload to that command.
+
+If any write is rejected, follow the returned `next_action` and `reason_code`. Do not retry by guessing direct/batched stages, forcing route bypasses, or editing workflow files.
+
+### 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**.
+- [ ] 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**.
+- [ ] No raw, cache, knowledge, `/tmp`, host tool-results, or workflow scratch files were read or written with generic tools. If violated, restart from **Step 1**.
 
 </procedures>

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

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

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

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