@c4a/context-cli 0.6.0-beta.8 → 0.6.1

package/plugin/skills/skill-prose-compile/references/internal-procedures/compile-actions/references/structural-challenges.md

@@ -1,73 +0,0 @@
-# Structural and ownership challenges
-
-Consult this reference when the cited evidence **cannot be written as a Section under the current confirmed structure**:
-
-- The evidence describes a coherent process that should be its own `action` Node (not a Section here).
-- The evidence implies a missing `depends_on` edge between Nodes.
-- The evidence belongs under a different parent Node.
-- A finalized shared-block split leaves this Node with only secondary, non-citable evidence.
-- A visible `context_only` or secondary-shared block contains facts that need citation, requiring an ownership upgrade.
-
-In these cases, do **not** force the content into a Section. The current
-`context.compile-actions.v1` schema does not accept challenge actions. Stop the
-compile draft for this Node, report the structure defect, and return to the
-prose align gate so the structure can be revised as `unresolved[]`, a corrected
-node, a corrected section plan, or a typed edge.
-
-## When to challenge vs. when to skip
-
-| Situation | Route |
-|---|---|
-| Evidence is a repeatable procedure with steps that clearly warrant a sub-Action | Return to align and propose a new or corrected `action` node. |
-| Evidence depends on a Node that the current structure does not link to this Node | Return to align and add a source-backed typed edge such as `depends_on`, `prerequisite`, or `applies_to`, or keep it in `unresolved[]` when evidence/target is incomplete. |
-| Evidence belongs under a different parent | Return to align and move the planned section source refs to the correct node. |
-| The planned section has no primary source-backed evidence for this Node | Return to align and revise section ownership/source refs, or remove the node if it should not exist. |
-| The Node should not exist because its evidence belongs elsewhere | Return to align and remove or replace the node before compile. |
-| Background/context evidence holds facts this Node needs to cite | Return to align and make those source refs owned by the correct planned section, or keep the issue unresolved. |
-
-Use challenge labels only as private reasoning labels in your user explanation.
-Do not put them in `context.compile-actions.v1`.
-
-## Report shape
-
-When this reference triggers, do not submit a compile payload for the affected
-Node. Report a compact structure repair request to the user and the align gate:
-
-```jsonc
-{
-  "reason_code": "structure_reconfirmation_required",
-  "issue": "missing_action_node",
-  "view_ref": "<matches selected view_ref>",
-  "summary": "The cited evidence is a repeatable procedure.",
-  "source_refs": ["file:docs/runbook.md#span:ops L40-55@<span-hash>"],
-  "align_repair": "Add a supported action node or keep the issue in unresolved[]."
-}
-```
-
-The actual committed repair is a revised `context.structure.v1` payload. Use
-the align schema and validation diagnostics for that repair; do not invent a
-compile action shape.
-
-## What these are NOT
-
-- **Not a substitute for `skip`** when raw simply has no write-worthy fact for this Node.
-- **Not a Section.** Structure defects never appear in active knowledge.
-- **Not a compile action.** Do not encode them as `op` values in
-  `context.compile-actions.v1`.
-- **Not a free retargeting path.** Do not switch `view_ref`, `section_id`, or
-  `source_refs[]` inside compile merely to make validation pass. The confirmed
-  structure must be repaired first.
-- **Not a free upgrade path.** Exact text views expose visible evidence text for
-  inspection, but they do not change section ownership. If you need to cite
-  background content, return to align and revise ownership/source refs.
-
-## How this slots into the main procedure
-
-- **Step 3 — Build actions**: when evidence implies a missing Action, missing
-  edge, wrong parent, or needed ownership/source-ref repair, stop the compile
-  draft for this Node and return to align instead of writing a Section.
-- **Step 5 — Self-verify**: no Section write cites source refs outside the
-  planned section ownership; if any did, remove the action and return to align.
-- **Review handoff**: if a user asks why compile stopped, explain the structure
-  effect plainly: paths, ownership, and relations are frozen at compile time, so
-  these repairs need a new confirmed structure rather than a draft-page patch.

package/plugin/skills/skill-prose-compile/references/internal-procedures/compile-actions.md

@@ -1,413 +0,0 @@
----
-name: compile-actions
-description: >
-  Internal procedure invoked by the current compile gate; not a user slash
-  command. For one View at a time, reads the CLI-provided node-context
-  (planned metadata, planned sections, local source aliases, and source refs),
-  classifies each planned source span into a Section kind via the priority
-  chain, writes source-bound actions with section_id, kind, required summary,
-  source_refs[], and emits a context.compile-actions.v1 document
-  for the caller to submit to the current phase command.
-  Activates when compile iterates across the confirmed align structure.
-tools:
-  - Bash
----
-
-# compile-actions — write Section actions for one View
-
-Classify source-backed planned evidence for one materialized View into `add`, `update`, or
-`skip` actions; emit JSON; the CLI performs every write. Replacement or
-withdrawal judgments stay in user/structure review unless the schema view
-explicitly exposes a current write shape.
-
-## TL;DR — Non-negotiables
-
-- One View per invocation — `view_ref` MUST equal the selected `view_ref`; no cross-View writes. Finish the current View's draft quality checks before the caller moves to another View's review/apply loop.
-- Agent emits JSON only; no markdown, no direct workspace file writes. The caller submits the JSON to the current phase command; the CLI validates and stores candidate state.
-- Evidence boundary: treat the CLI-provided node-context and evidence views as
-  complete. Cite only source refs already planned on the selected section.
-  If exact text is needed before choosing kind/summary/content, read it through
-  current evidence views such as
-  `context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json`
-  or `--view span-text`. Never `grep` / `sed` / `jq` / `cat` / `head`
-  snapshots, `--format json` stdout, or agent scratch files.
-- Actions are candidate write actions, not final semantic decisions. Op naming
-  is scoped by schema: `actions[]` already targets Sections, so Section
-  lifecycle ops are verb-only: `add`, `update`, and `skip`. Do not use
-  align-style names such as `add_section`, `write_section`, or
-  `propose_section`.
-- Citation validation passing is not completion. Before emitting, estimate
-  coverage from the planned section refs: if there are 3+ citation-eligible
-  spans, a one-action draft is valid only when the later spans are duplicates,
-  navigation, placeholders, or continuations of the same fact. Small dense docs
-  still need multiple actions when later spans state distinct capabilities,
-  constraints, examples, risks, FAQ, or usage notes. Large manuals/design docs
-  should compile to several orthogonal actions in the same draft.
-- Pick `kind` from the current compile schema view, especially legal values and
-  mount rules. Treat kind precision as a drafting quality preference, not a
-  reason to loop forever when the CLI accepts the write. A `decision` fits only
-  when the source explicitly presents two or more alternatives or options and
-  records the chosen path plus rationale. One-option policy conclusions are
-  usually `spec`, `principle`, or `description`. Bare rules or checks are usually
-  `spec`. Reach `description` only after every more specific kind fails.
-- `node.sections[]` / `planned_sections[]` is the confirmed structure scaffold,
-  not a loose suggestion. Prefer a planned kind when the evidence fits; if a
-  source-backed stronger kind differs, validate it and let CLI diagnostics guide
-  review.
-- `kind × node.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.
-- The schema view exposes `legal_section_kinds`, `section_kind_priority`,
-  `section_kind_triggers`, and `section_kind_mount_matrix`. CLI validation
-  rejects unknown kinds and kind/node_type mount violations; treat those as
-  structure or drafting errors, not review-time style preferences.
-- Every write action cites raw via `source_refs[]` copied from the chosen
-  planned section. Omitted-content verbatim actions must use one contiguous
-  same-document evidence run; split non-contiguous evidence into multiple
-  sections or return to prose align when the confirmed section is too coarse.
-  Do not use explicit `content` / `content_intent` as a shortcut to merge
-  unrelated or non-contiguous source spans into a shorter summary. Never
-  fabricate refs or cite navigation-only spans as evidence for a content
-  Section.
-- For large evidence, use `source-index` to choose refs and `span-detail` /
-  `span-text` only for the spans an action needs.
-- `content` is not accepted on source-backed writes. Cite with `source_refs[]`
-  and let the CLI mirror source into content. If the problem is non-contiguous
-  source refs, dense examples, a needed translation, or a too-broad planned
-  section, split the section through align instead of writing a compressed or
-  summarized `content` paragraph. Prefer `summary` on `add` / `update` when
-  it adds useful recall value; omit it when the View or Section title is already
-  self-explanatory. Summary is recall text, not evidence. This summary is only
-  the behavior half: the CLI derives any reachability half from confirmed
-  structure edges after validation, so do not add relation summaries or edge
-  fields to the action payload.
-  The CLI
-  rejects unsupported fields (`body`, `detail`, `raw`, singular `source_ref`,
-  quoted-evidence) with canonical repair hints.
-- The CLI also rejects template-like explicit `content`: bare TODO/TBD,
-  `<placeholder>`, deferred-content placeholders, source-omission text such as
-  "see source text", and directory lead-ins such as "this section describes" or
-  "本节介绍". Only preserve such markers when they are literally present in the
-  cited source text and are themselves the fact being documented.
-- 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; the materialized mirrored Section body may preserve raw Markdown when that is the clearest faithful Section text. Do not patch solely for style cleanup unless the cited source meaning is materially lost.
-- Do not synthesize a user-facing prefix by concatenating `heading_path` values (for example, `Parent - Child:`) when that prefix is not in the cited raw. Use headings only to choose grouping and framing; if a heading's wording is itself useful, keep it as sourced content only when it appears in the cited span text.
-- Preserve source-backed URLs, code identifiers, or `source_ref` literals when
-  they are part of reader-facing knowledge or a repair challenge. Do not rely on
-  memorized URL rules, and do not add literals only for scoring or traceability.
-- Relationships and cross-node references belong in confirmed structure edges,
-  not in compile action fields or verbatim body. Do not add structure edges or unresolved relations
-  to `context.compile-actions.v1`.
-- `skip` is the honest default when source evidence adds nothing. Bare `skip`
-  is only for deterministic no-ops such as unchanged input, pure navigation, or
-  context/background snippets. When citation-eligible evidence was reviewed and
-  intentionally not written, emit `skip` with the relevant `source_refs[]`.
-- 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; narrow context-only navigation/reference blocks may be rendered later as a `References` auto-block, while active Sections still need citation-eligible content.
-- FAQ collections attach to the most specific finalized Node (Entity → Action → Domain fallback); never create a standalone FAQ container.
-- Output language: Node-facing summaries and user-facing draft explanations
-  follow the workspace/source language when the phase view exposes one;
-  otherwise match the source material. Section `summary` is reader/query aid:
-  write Chinese summary prose for clearly Chinese cited evidence or mirrored
-  content; English summary prose is acceptable for clearly English evidence;
-  mixed technical evidence may keep concise mixed-language terms. Mirrored
-  content is source-bound: preserve the cited source language, product names,
-  code identifiers, CLI flags, slugs, `source_ref` tokens, and exact quoted
-  evidence as printed.
-- Stable output: keep action order aligned with evidence order — that ordering
-  is the only stability concern the CLI cannot enforce. The CLI rejects unknown
-  fields (timestamps, random ids, host/scratch paths) and canonicalises stored
-  payloads; fixed rules and schema come from this skill, so only the current
-  node-context should vary between repeated View draft calls.
-
-## Edge cases — consult references when:
-
-| Condition | Reference |
-|---|---|
-| `node.node_type` is `action` or `domain` | [compile-actions/references/action-domain-gates.md](compile-actions/references/action-domain-gates.md); use current `node-context` fields, planned sections, edges, and source refs |
-| current schema/view exposes note evidence | [compile-actions/references/notes.md](compile-actions/references/notes.md) |
-| `existing.sections[]` non-empty, **or** `incremental.status` is `unchanged` / `full-context`, **or** `incremental.locator_only_changes[]` non-empty | [compile-actions/references/refresh-and-update.md](compile-actions/references/refresh-and-update.md) |
-| evidence implies missing Action / wrong parent / `depends_on` gap / planned-section ownership repair | [compile-actions/references/structural-challenges.md](compile-actions/references/structural-challenges.md) |
-
-If none of the above hold, you are on the main path (first compile of an entity Node with default `changed-only` incremental status). The procedure below covers that path end-to-end.
-
-<reference>
-
-## Input — node-context
-
-Canonical shape: `context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json` (or `--format json`). The CLI is the source of truth for fields, enums, and produced-by paths.
-
-Boundary recap:
-
-- `view_ref` is the active write boundary. The payload `view_ref` must match
-  the selected view; do not draft for another view because the evidence looks
-  related.
-- `planned_sections[]` and their `source_refs[]` are the evidence floor. Never
-  cite outside the selected planned section unless you first return to align and
-  reconfirm structure.
-- `local_sources[]` are aliases for source refs inside the node-context view.
-  Preserve CLI-returned refs exactly in the payload.
-- `existing.sections[]`, when present, means this is a refresh path. Read
-  [compile-actions/references/refresh-and-update.md](compile-actions/references/refresh-and-update.md)
-  before writing an `update` or deciding that no action is needed.
-- `incremental.status`, locator-only changes, low-coverage diagnostics, and
-  repair hints are part of the compile contract. Preserve their reason in the
-  user-facing handoff when they force a skip, full-context read, or return to
-  structure confirmation.
-- Candidate or conflict lists surfaced by the CLI are the only relation
-  comparison set. Do not search `knowledge/`, `dist/`, or source snapshots to
-  invent more candidates.
-- When you need exact source text for kind/summary/content judgment, read only
-  the matching `span-detail` or `span-text` view for that source ref.
-
-## Evidence Index Translation
-
-Evidence views may expose compact indexes, grouped spans, and detail commands.
-The committed evidence handle in the current workflow is `source_refs[]`, copied
-from the confirmed planned section or from a CLI evidence view that the current
-node-context explicitly points to.
-
-Use the same discipline behind the evidence index:
-
-- A write action cites only the refs it actually consumes. Do not attach every
-  planned ref to a broad section just to make validation pass.
-- Omitted-content verbatim actions need one continuous same-document evidence
-  span after CLI canonicalization. If the relevant evidence is non-contiguous,
-  split it into separate sections or return to align for a confirmed section
-  split.
-- If a planned section contains several unrelated facts, write several actions
-  when the schema allows it; otherwise return to structure confirmation and
-  split the planned section. Do not hide unrelated claims behind one summary.
-- If the only available evidence is context/background, navigation, parent /
-  child / related lists, placeholder text, or a title-only cue, do not promote
-  it to active section body. Use `skip`, `unresolved[]`, or return to align as
-  appropriate.
-- Source refs are not traceability padding. They are the support boundary for
-  reader-visible mirrored content and summaries. Every fact in `summary` must
-  be covered by the cited refs.
-- Never convert CLI-visible evidence handles into new ad hoc ids, aliases, or
-  quoted evidence fields. Copy current refs exactly and let validation reject
-  stale or miscoped refs.
-
-## Output — Compile Draft JSON (main path)
-
-Canonical shape: `context run compile:<type>:<source>:<collection> --view schema --format json` (or `--format json`). The CLI is the source of truth for fields, enums, and validation — do not memorise the shape from this file.
-
-Main-path ops are **`add`**, **`update`**, and **`skip`** when supported by the
-current schema. A typical new Section action is
-`{ op: "add", section_id: "<planned-section-id>", kind: "<chain-picked>", summary: "...", source_refs: ["<source_ref>"] }`;
-omit `content`. Never spell that as `add_section` because the `actions[]` array
-already names the target object. A bare skip is `{ op: "skip", reason: "..." }`;
-a reviewed-no-write skip may carry `source_refs[]` from the planned section.
-
-Payload shape example. This envelope is **not valid** until `actions[]`
-contains at least one action; the CLI rejects empty `actions[]` with
-`schema.actions_missing`.
-
-```json
-{
-  "schema_version": "context.compile-actions.v1",
-  "view_ref": "<matches selected view_ref>",
-  "actions": []
-}
-```
-
-Minimal valid `add` payload:
-
-```json
-{
-  "schema_version": "context.compile-actions.v1",
-  "view_ref": "<matches selected view_ref>",
-  "actions": [
-    {
-      "op": "add",
-      "section_id": "<planned-section-id>",
-      "kind": "<confirmed-section-kind>",
-      "summary": "<source-backed summary>",
-      "source_refs": ["<source_ref>"]
-    }
-  ]
-}
-```
-
-Minimal valid no-write payload:
-
-```json
-{
-  "schema_version": "context.compile-actions.v1",
-  "view_ref": "<matches selected view_ref>",
-  "actions": [
-    {
-      "op": "skip",
-      "reason": "<source-bound reason>"
-    }
-  ]
-}
-```
-
-Refresh/update judgment lives in
-[compile-actions/references/refresh-and-update.md](compile-actions/references/refresh-and-update.md),
-but emit only fields accepted by the current schema. Structure challenges live
-in [compile-actions/references/structural-challenges.md](compile-actions/references/structural-challenges.md);
-if the current schema has no challenge op, return to align rather than
-inventing one.
-
-`source_refs[]` is the committed evidence contract. A single citation is still
-a single-element array. Keep hard citation gaps separate because omitted-content
-verbatim cannot form one source ref across unrelated spans. When one Section
-summarizes multi-span evidence, list only refs the action actually consumes.
-Preserve raw wording by omitting `content`.
-Preserving a cited prose/bullet list as the Section's user-facing content is
-allowed when that list is the actual knowledge; the anti-pattern is copying raw
-text only as traceability padding. For `example` Sections that cite command /
-config / code fences, cite the relevant fenced block and let the CLI mirror it.
-Inline command/code spans are not fences; if the cited raw is a numbered list
-or prose with inline code, keep that shape and do not synthesize a ```bash```
-block or shell commands.
-
-## Section Kind Choice
-
-Use `context run compile:<type>:<source>:<collection> --view schema --format json` (or yaml) for the current legal kind list, priority order, and mount matrix. This skill adds only semantic guardrails:
-
-- Stop at the first kind whose source-backed form fits.
-- Do not choose `description` to hide lists, rules, tables, samples, risks, choices, or Q+A evidence that has a more precise kind.
-- When the strongest kind is not mountable on this Node type, choose the next legal kind that the evidence truly supports, or `skip` with a structural challenge reason.
-
-Confidence is optional. Omit it for ordinary confirmed claims; set it only when the evidence is clearly verified, inferred, or speculative according to the schema enum.
-
-## Description anti-abuse gates
-
-`description` is the kind for narrative claims that do not match any other form. Before locking in `kind: description` for a snippet, run three classification checks against the cited span:
-
-1. **Atomicity**: single narrative, or multi-step / multi-row / multi-config? Multi → split into the right kinds — each step into its own `spec` / `warning`, each row into a `comparison` Section, each config block into `example` (sample) or `spec` (constraint with a check method).
-2. **Kind-precision**: does a higher-priority kind fit better? A fenced code / config / command block belongs in `example`; a comparison table belongs in `comparison`; a Q+A pair belongs in `faq`; `incident` requires dated or timestamped failure evidence with impact scope plus root cause, mitigation, or handling record; ordinary scenario, case-study, or impact-result prose is not `incident`; a versioned change record belongs in `changelog`; `decision` requires two or more surfaced alternatives or options plus a chosen path and rationale; a verifiable rule with a check method belongs in `spec`; explicit risks belong in `warning`; a stable design rule or core mechanism without a recorded choice or check method belongs in `principle`.
-3. **Action threshold**: multi-step fragments that clear the Action bar → emit `op: skip` with a note "evidence warrants sub-Action; re-align needed"; do not create Nodes from this skill.
-
-A Node whose raw is genuinely narrative — definitions, summaries, plain prose without enumerations or normative wording — legitimately ends with description-dominant output. The smell fires the other way: when raw contained enumerations, normative rules, or code blocks, and the draft collapsed them to `description`. Redraft from Step 2 in that case, not from a percentage threshold. Navigation-only evidence is handled separately by the TL;DR navigation rule and Step 2 — the gates above are not the right place to second-guess that path.
-
-## Cross-Node Relations
-
-When a Section meaningfully discusses another known Node, preserve that
-relationship in confirmed `structure.yaml` edges or unresolved items. Do not
-add structure edges or unresolved relations to compile actions and do not inject `[[id]]` style
-links into verbatim body, because that breaks source mirror verification.
-
-Use this decision chain:
-
-1. If the relation is already a confirmed edge, compile may mention only what
-   the selected section refs state; the edge itself remains in structure.
-2. If the source-backed section clearly depends on, compares, triggers, or
-   applies to another existing/current node but the edge is missing, stop and
-   return to prose align with a structure repair note.
-3. If the target is only a title hint, navigation clue, unresolved external
-   system, or not present as a current/approved node, keep it in `unresolved[]`;
-   do not invent a NodeRef to make the relation fit.
-4. If another node name appears incidentally inside an example, command, URL, or
-   product list and does not change the section's retrieval meaning, keep the
-   source text as-is and do not add a relationship.
-
-Relationship wording in body text still follows the source. Do not add
-"depends on", "triggers", "contains", or similar language unless the cited span
-states that relationship. The typed edge can preserve relation intent without
-rewriting verbatim content.
-
-If the CLI returns summary quality or low-coverage advisories with non-error severity, do not patch solely to satisfy the advisory and do not inspect every folded detail row by default. Patch only when the cited source meaning is lost, the user asks for cleanup, or the returned `next_action` asks for a draft patch.
-
-## FAQ attachment priority
-
-| FAQ topic | Attach to |
-|---|---|
-| About a concrete thing | That thing's Entity (Section `faq`) |
-| About a mechanism or term | The matching Entity |
-| About an action / flow | That Action |
-| Cross-topic / generic workspace FAQ | Domain (fallback only) |
-
-Never manufacture a FAQ container Node. If a FAQ cluster grows too large, a
-sub-Entity is the correct escape hatch; return to structure confirmation with a
-source-backed repair note instead of encoding that decision in compile actions.
-
-</reference>
-
-<procedures>
-
-### Step 1 — Sanity-check the context
-
-Confirm `view_ref` is set; abort if not. Note `node.node_type` — it caps legal
-kinds per the CLI Section mount matrix.
-
-Check edge case conditions from the routing table at the top of this skill. If any apply, read the relevant reference **before** continuing. The references explain how their conditions modify Step 1 / Step 2 / Step 3.
-
-Estimate coverage from the planned section source refs before writing actions.
-Treat "the first quote is supported" as only a validation result, not a
-completion signal.
-
-Use the CLI-provided citation-eligible snippets and diagnostics as the coverage contract. Distinct source-backed facts should become distinct actions or evidence-carrying skips; duplicates, navigation-only blocks, placeholders, and unsupported fragments can be skipped. If later CLI diagnostics report low coverage, repair the same draft through the returned `next_action`.
-
-### Step 2 — Classify each raw snippet
-
-For each planned section and its source refs:
-
-1. If the snippet only contains navigation or placeholder evidence (`Parent` / `Children` / `Related` / `Relations`, sibling links, "no detailed content", etc.), emit `skip`. Do not create a Section whose content is just "Children: ..." or "Related: ..." and do not summarize facts that are not present in the snippet.
-2. Pick kind using [Section Kind Choice](#section-kind-choice); stop at the first kind whose trigger fires.
-3. Verify the kind against the mount matrix for `node.node_type`. Mismatch → pick the next legal kind down the chain, or emit `skip` with a reason pointing at a better Node. Never "fall through to description" just to place evidence.
-4. If you land on `description`, walk the [Description anti-abuse gates](#description-anti-abuse-gates). Any gate fires → split or `skip`.
-
-For dense documents, group nearby spans by heading context and write one action
-per coherent fact group. Repeated `#` headings inside one source are often
-internal chapters of the current Node; keep them as Sections unless the evidence
-establishes a separate durable Node identity.
-
-### Step 3 — Build actions
-
-For each classified snippet:
-
-1. Do not write `content`. Cite `source_refs[]` and let the CLI mirror source
-   into the Section content. If the cited raw is too broad, non-contiguous, or
-   needs translation/rewording, split actions/sections or return to structure
-   confirmation. Do not compress several raw blocks into one paragraph.
-2. `summary` on `add` / `update` is optional behavior-half recall text.
-   When present, it is LLM-authored reader/query aid: one plain paragraph, no
-   Markdown, and compact. In YAML payloads, write `summary` as a plain
-   single-line scalar. Omit it when the title is self-explanatory rather than
-   writing filler.
-   It covers only the cited section behavior. The CLI appends deterministic
-   edge reachability metadata from confirmed structure edges during candidate
-   materialization; do not duplicate that relation text in `summary`.
-   Generic placeholders like "description section covering N evidence spans"
-   are invalid drafting quality even when the payload remains schema-valid.
-   If you cannot write a meaningful summary for source-backed reader content,
-   do not submit a placeholder; narrow the action, use `skip` for no-write
-   evidence, or return to the evidence/structure gate. The CLI reports
-   non-blocking advisory hints for weak summary quality; it does not treat
-   summary style as an evidence failure. Keep summaries faithful to the
-   source-backed action, but do not copy source-only keywords into `summary` for
-   scoring.
-3. Preserve meaningful source-backed literals in `summary`, skip reason, or
-   repair challenge when they are part of the knowledge. Do not patch only to
-   satisfy non-blocking URL or style advisories.
-4. Keep edge confidence out of compile actions. Source-authored uncertainty is
-   preserved on confirmed structure edges during align; compile only consumes
-   those edges for deterministic reachability metadata.
-5. Keep cross-node relationships in structure edges; do not add extra relation
-   fields to compile actions.
-6. Cite evidence with `source_refs[]`, copied from the planned section. Hard
-   citation gaps stay separate, while heading-annotated evidence may stay
-   together or be split by semantic knowledge unit. If the evidence is
-   non-contiguous or contains separable claims, split the draft into separately
-   cited actions instead of stretching one action across unrelated spans. For
-   `skip`, include `source_refs[]` 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` or quoted-evidence fields.
-
-Approved knowledge may contain non-rendered `context:summary` metadata comments,
-but reader-visible section body starts with the active mirrored content. Agents
-must not emit rendered comments, debug raw blocks, or audit payloads themselves.
-
-### Step 4 — Emit the JSON
-
-Emit one compile draft JSON document for the caller to submit to the current envelope's `next_action.command`. No markdown wrapper, no leading prose, no trailing commentary.
-
-Before returning, ensure `schema_version` is `context.compile-actions.v1`,
-`view_ref` matches the selected view, every add/update action has `section_id`, fields
-conform to the current compile schema view, citations point only at
-CLI-provided planned section evidence, and node-context was the only evidence
-source except for exact span reads through current CLI views.
-
-</procedures>

package/plugin/skills/skill-prose-compile/references/internal-procedures/compile-judgment.md

@@ -1,123 +0,0 @@
----
-name: compile-judgment
-description: >
-  Internal support/relation judgment procedure for the current compile and
-  review gates; not a user slash command. Consumes current compile/review
-  diagnostics and evidence views, judges each draft action's source evidence
-  support and relation to listed candidates, and returns a judgment the caller
-  expresses through current compile actions, unresolved structure, or an
-  explicit user question.
-tools:
-  - Bash
----
-
-# compile-judgment — judge compile support and relation
-
-Decide whether each proposed compile action is supported by cited source
-evidence and how it relates to candidate Sections listed by the CLI. Return the
-judgment in the current route; the CLI reviews, applies, and writes every
-workspace change.
-
-## TL;DR — Non-negotiables
-
-- Invoke this procedure only when current align/compile/review diagnostics ask
-  for support, duplicate, conflict, replacement, or weak-evidence judgment.
-- Input is the budget-safe diagnostic or view returned by the current phase.
-  If the view is paginated, follow `next_command` until every relevant item is
-  listed.
-- The summary is an index: use only CLI-returned detail commands when full
-  proposed content, source evidence, or source_ref details are needed.
-- Do not inspect `sources/`, `unapproved/`, `knowledge/`, or `dist/` directly
-  or run ad-hoc scripts to reconstruct candidates. Use only the current
-  diagnostics, evidence views, candidate lists, and detail commands returned by
-  the CLI.
-- Output the judgment in the caller's current shape: repair compile actions,
-  update unresolved structure items, or ask the user. Do not emit a standalone
-  judge-decision payload unless the current CLI schema view explicitly asks for
-  one.
-- Keep one decision per diagnostic item, preserving CLI order.
-- Compare only the candidates listed on that item. Do not perform workspace-wide BM25, grep, or source-file searches.
-- Inspect every candidate page the CLI provides before judging. If candidates
-  are paged, follow `next_command` until no candidate page remains.
-- When there are no candidates, classify the action as new unless the evidence
-  itself is unsupported or structurally misplaced.
-- For duplicate, replacement, conflict, or update judgments, name the matched
-  candidate Section in prose or repair rationale only when the current CLI view
-  exposes that 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.
-- Raw/source_ref diagnostics are deterministic evidence checks, not a keyword gate. A supported judge verdict comes from the cited raw evidence semantically covering the claim.
-- Evidence-boundary errors remain blocking evidence issues. Section kind precision, example formatting, and summary style 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.
-- Weak support, replacement, or conflict that depends on business meaning must
-  route to explicit user confirmation. A blanket "continue" is not enough; ask
-  the concrete choice and express the answer through the current compile,
-  structure, or review route.
-
-<reference>
-
-## Judgment Shape
-
-Use these values as the decision vocabulary in your repair note or user
-question. The current write payload is still `context.structure.v1` or
-`context.compile-actions.v1`, not this table.
-
-## Verdict Meanings
-
-| Judgment | Meaning |
-|---|---|
-| `supported` | Cited source evidence covers the claim. |
-| `weak` | The evidence plausibly supports an ordinary summary, but review may ask for confirmation. |
-| `unsupported` | The claim adds facts or boundaries not present in cited source evidence. |
-| `new` | No listed candidate already covers the proposed knowledge. |
-| `duplicate` | A listed candidate already covers the same claim. |
-| `replacement` | A listed candidate is stale or wrong and should be replaced by the new claim. |
-| `conflict` | The prepared claim and candidate disagree and need user resolution. |
-| `update` | The prepared claim should refine one listed candidate. |
-| `merge` | The proposed claim should be folded into one listed candidate without changing meaning, when the current schema exposes a safe update path. |
-
-</reference>
-
-<procedures>
-
-### Step 1 — Load Current Diagnostics And Candidate Details
-
-Use the caller-provided compact diagnostic output. For every item with
-candidates, load only the CLI-provided candidate detail view before judging
-relation. Do not infer missing candidates from memory or bypass the detail view.
-
-### Step 2 — Judge Support
-
-For each item, read the proposed content and cited evidence. Use source_ref
-diagnostics only as evidence pointers; final support is your
-semantic verdict from the cited raw evidence.
-
-### Step 3 — Judge Relation
-
-Compare the proposed claim against each listed candidate. Track every visible
-candidate in your reasoning, and continue candidate pages until the CLI says the
-candidate list is complete. If the candidate list is empty, classify the action
-as `new` unless support or structure checks fail.
-
-Use this relation/action chain before returning a repair:
-
-| Relation judgment | Current route |
-|---|---|
-| Exact same claim already active | Do not write a duplicate section; emit or repair a `skip` with duplicate reason when the schema supports it. |
-| Same claim with source-backed wording/detail refinement | Use `update` only when node-context and schema expose the target section; otherwise ask the user or return to review/structure. |
-| Related but orthogonal claim | Keep a separate action/section when the planned section owns the cited source refs. |
-| New evidence replaces a previous rule, value, or decision | Treat as replacement; ask the user or return to review/structure. Do not hide the replacement inside a same-section edit. |
-| Direct contradiction | Ask the user. Do not auto-resolve from source order, title order, or "latest-looking" wording. |
-| Candidate relation depends on another node or edge | Return to prose align so the typed edge or unresolved item can be confirmed. |
-
-For duplicate, replacement, conflict, merge, or update judgments, name the
-candidate section(s) inspected in the repair rationale when the CLI exposes
-their ids. Do not claim workspace-wide uniqueness unless the current CLI view
-performed that search.
-
-### Step 4 — Emit Judge Decisions
-
-Return only the judgment needed by the caller: repaired current payload,
-unresolved item, or user question. Do not invent a separate semantic repair command
-unless the current CLI explicitly returns one.
-
-</procedures>