@c4a/context-cli 0.5.41-beta.7 → 0.6.0-alpha.6

package/plugins/claude/skills/skill-prose-compile/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: skill-prose-compile
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Uses confirmed Context document structure to create source-bound draft prose
+  candidates through `context.compile-actions.v1`, without reading raw
+  snapshots directly.
+tools:
+  - Bash
+---
+
+# skill-prose-compile
+
+Compile confirmed document structure into reviewable draft knowledge.
+
+## TL;DR
+
+- Use this after `context status` reports `structure-ready` or
+  `needs-prose-compile`, or when the user explicitly asks to compile confirmed
+  prose structure into draft pages.
+- The input is already confirmed `context.structure.v1`; do not redesign node
+  ownership, page paths, or relationships here. Return to prose align if those
+  are wrong.
+- Read compile context through CLI views only: `read-plan`, `node-context`, and
+  `schema`. Use align evidence views only when the compile view or validation
+  output gives a specific source ref that needs exact text.
+- Emit `context.compile-actions.v1`; the CLI mirrors source spans, derives
+  `content_mode`, writes review candidates, and enforces source-bound evidence.
+- The `summary` field in each action is the Agent-authored behavior half only:
+  compact source-backed recall text for the cited section. The CLI separately
+  renders the reachability half from confirmed typed edges into review metadata;
+  do not invent edge summaries or relation fields in the action payload.
+- Default to omitted `content` so the CLI mirrors the cited source span.
+  Do not write explicit `content`. If the evidence cannot be represented as a
+  faithful mirrored continuous span, split the section or return to prose align
+  for a confirmed structure change.
+- Before choosing section kind, summary, skip/update, weak-evidence handling, or
+  structure repair, read the current procedure references listed by the CLI as
+  `semantic_reference_files`. These are the migrated compile judgment rules, not
+  summaries.
+- Do not produce or validate compile actions from this entry file alone. If the
+  relevant `semantic_reference_files` have not been read in the current turn,
+  stop and read them first.
+
+<reference>
+
+## User-Facing Gates
+
+Use semantic labels, not SDK function names:
+
+| Gate | Say this | Do not say this first |
+|---|---|---|
+| Compile context | "I will inspect the confirmed structure and each node's planned evidence before drafting sections." | `node-context`, `context.compile-actions.v1` |
+| Source-bound draft | "I will mirror supported source spans into reviewable draft pages and attach summary/kind metadata." | `compileProse` |
+| Non-mirror evidence | "This section cannot be compiled as-is because the evidence is not one faithful source mirror; we need to split or revise the structure." | "The agent can rewrite this automatically." |
+| Structure mismatch | "This compile cannot proceed because the confirmed structure no longer matches the evidence; we need to return to structure confirmation." | Editing `knowledge/` or `unapproved/` directly |
+
+## Runtime Discipline
+
+- Follow `context status`, `routing.next_commands`, compile view
+  `next_action`, and validation diagnostics. Treat CLI commands as the source
+  of truth.
+- Use only the returned `next_action.command` for the next required write.
+  Treat `allowed_actions[]` as permission for read-only insertions; it is not a
+  menu of alternate write paths.
+- Treat `agent_hints[]` as temporary diagnostics. If an agent hint conflicts
+  with a status route, compile view `next_action`, or validation result, follow
+  the top-level route.
+- Do not use direct file tools, shell scripts, `jq`, `sed`, `cat`, `head`,
+  `tail`, Python, or Node.js to inspect `sources/`, `unapproved/`,
+  `knowledge/`, `dist/`, or CLI-managed `.tmp` as a substitute for Context
+  views.
+- Run one write at a time. Do not parallelize compile stage, review apply,
+  close, or build writes.
+- Compile does not get a second, looser rule set. If a rule conflicts with the
+  current CLI schema or diagnostics, follow the CLI and repair the payload.
+- Write digest/hash flags are stale guards. Use values returned by the CLI; do
+  not parse stdout fragments or host tool-result files to reconstruct them.
+- If a payload is too large for a heredoc, stage it under
+  `.tmp/agent-payloads/<run-id>/...` in the workspace root and redirect stdin
+  from that file. Never reuse fixed `/tmp/c4a-*` names, and never place agent
+  scratch payloads under CLI-managed `.tmp/context-cli/`, `sources/`,
+  `unapproved/`, `knowledge/`, `dist/`, review output, or package output
+  directories.
+
+## Compile Views
+
+Recommended read order:
+
+```bash
+context run compile:<type>:<source>:<collection> --view read-plan --format json
+context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
+context run compile:<type>:<source>:<collection> --view schema --format json
+```
+
+Use CLI-returned `available_view_refs`, `planned_sections`, `local_sources`, and
+`next_action.command`. Do not reconstruct the structure by opening
+`unapproved/structure.yaml` or `knowledge/structure.yaml` directly.
+
+## Procedure References
+
+These are current compile rules for source-bound drafting, judgment, semantic
+repair, and close handoff.
+
+| Decision | Reference |
+|---|---|
+| Compile action drafting, section kind, coverage, summaries, content intent | [references/internal-procedures/compile-actions.md](references/internal-procedures/compile-actions.md) |
+| Action/domain compile gates | [references/internal-procedures/compile-actions/references/action-domain-gates.md](references/internal-procedures/compile-actions/references/action-domain-gates.md) |
+| Notes, refresh/update, and structural challenges | [references/internal-procedures/compile-actions/references/notes.md](references/internal-procedures/compile-actions/references/notes.md), [references/internal-procedures/compile-actions/references/refresh-and-update.md](references/internal-procedures/compile-actions/references/refresh-and-update.md), [references/internal-procedures/compile-actions/references/structural-challenges.md](references/internal-procedures/compile-actions/references/structural-challenges.md) |
+| Support, duplicate, replacement, conflict, weak evidence, and relation judgment | [references/internal-procedures/compile-judgment.md](references/internal-procedures/compile-judgment.md), [references/internal-procedures/semantic-judgment.md](references/internal-procedures/semantic-judgment.md) |
+| Leakage, ownership, temporal evidence, disposition, omit, and user confirmation | [references/internal-procedures/semantic-judgment/references/leakage-and-ownership.md](references/internal-procedures/semantic-judgment/references/leakage-and-ownership.md), [references/internal-procedures/semantic-judgment/references/temporal-and-evidence.md](references/internal-procedures/semantic-judgment/references/temporal-and-evidence.md), [references/internal-procedures/semantic-judgment/references/disposition-semantics.md](references/internal-procedures/semantic-judgment/references/disposition-semantics.md), [references/internal-procedures/semantic-judgment/references/scope-review-and-omit.md](references/internal-procedures/semantic-judgment/references/scope-review-and-omit.md), [references/internal-procedures/semantic-judgment/references/user-confirmation.md](references/internal-procedures/semantic-judgment/references/user-confirmation.md) |
+| Close gate and current close output boundaries | [references/internal-procedures/close-gate.md](references/internal-procedures/close-gate.md) |
+
+## Compile Contract
+
+The compile action payload uses `schema_version: context.compile-actions.v1`.
+Compile may:
+
+- mirror source spans as `verbatim`;
+- emit `skip` decisions when no source-backed body should be written. `skip`
+  does not produce a placeholder candidate; generated parent-index pages use
+  the parent-index compile path, not an action payload placeholder.
+
+Relationships and cross references do not go into verbatim body. In current
+output they stay in `structure.yaml` typed edges; this workflow does not render
+relationship reference blocks.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Open Compile Context
+
+Run:
+
+```bash
+context run compile:<type>:<source>:<collection> --view read-plan --format json
+```
+
+Use the returned node list, source overview, and next action. If the CLI says
+the structure is missing, unconfirmed, stale, frozen against the wrong
+snapshot, or invalid, return to prose align or source capture as indicated.
+
+### Step 2 — Inspect One Node
+
+For each node that should become draft knowledge, run:
+
+```bash
+context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
+context run compile:<type>:<source>:<collection> --view schema --format json
+```
+
+Read the compile references listed by `semantic_reference_files` before
+classifying section kind, summary, support, skip/update, weak evidence, or
+structure repair.
+
+Do not treat those references as optional background. They are the current
+compile drafting, judgment, and semantic-repair procedures.
+
+When exact evidence text is needed, use the CLI-returned source ref with the
+current evidence view. Do not open snapshot files directly.
+
+### Step 3 — Draft And Validate Actions
+
+Create a `context.compile-actions.v1` payload for the selected view. Prefer
+omitted `content` with `source_refs[]` so the CLI mirrors source spans.
+If the source evidence is non-contiguous or contains separable examples,
+configuration blocks, lists, or procedures, split the compile actions when the
+confirmed structure supports that split. If the structure is too coarse, return
+to prose align and ask the user to confirm a section split instead of writing
+summarized body text. Explicit `content` / `content_intent` is not part of the
+current compile contract.
+
+For small payloads, use stdin/heredoc. For larger payloads, write a scratch file
+under `.tmp/agent-payloads/<run-id>/` and pass it through `--input`. Scratch
+files are disposable agent working files; they are never compile state and must
+not be read back as a substitute for CLI views.
+
+Validate:
+
+```bash
+context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml> --format json
+```
+
+Repair diagnostics by routing them to the right decision:
+
+- source ref or planned-section mismatch -> reread node-context, or return to
+  structure confirmation if ownership is wrong;
+- unsupported kind or op -> use the schema view and current compile references;
+- explicit content -> omit `content` and mirror source, or return to align for
+  a section split;
+- weak evidence, duplicate, conflict, omit, or scope issue -> use the compile
+  judgment / semantic judgment references and ask the user when required;
+- frozen structure mismatch -> rerun status and return to align/capture as
+  directed.
+
+Use typed diagnostics as the repair contract:
+
+- `reason_code`, `path`, and `missing[]` identify what to fix;
+- warnings are not write blockers unless the response marks them blocking or
+  the next action says so;
+- weak evidence, duplicate, conflict, temporal, leakage, ownership, and scope
+  issues are semantic review issues, not formatting problems;
+- raw/source-ref pointer diagnostics are evidence checks, not content-quality
+  judges.
+
+When validation returns a new `next_action.command`, follow that exact command.
+When it returns blocking diagnostics without a write command, repair and
+validate again. Do not stage a compile payload just because the YAML shape looks
+valid.
+
+### Step 4 — Stage Draft Candidates
+
+Stage only after validation has no errors:
+
+```bash
+context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
+```
+
+After staging, return to `context status`. If status reaches
+`compile-ready-for-review`, delegate review to
+`${CLAUDE_PLUGIN_ROOT}/skills/skill-review-gate/SKILL.md`.
+
+### Step 5 — Close Handoff
+
+After review apply, return to `context status`. If status says
+`compile-close-needed`, run deterministic close:
+
+```bash
+context close --format json
+```
+
+Close derives `knowledge/structure.yaml` and edge projection from approved
+knowledge, then runs the final verify gate. It must not rewrite approved
+verbatim body. References, changelog, package index, and section fingerprint
+rebuilds are not current close output.
+
+Then route to package output when status reaches `ready-to-build`.
+
+### Step 6 — Self-verify Checklist
+
+- [ ] Compile started from confirmed structure, not a new structure proposal.
+- [ ] Node context and schema came from compile phase views.
+- [ ] Compile references were read before choosing kind/summary/support.
+- [ ] Actions mirror source by default and do not invent body text.
+- [ ] No explicit reader-visible `content` was written by the Agent.
+- [ ] Relationships are expressed as structure edges, not inserted into
+  verbatim text.
+- [ ] No direct edits were made to `sources/`, `.tmp`, `unapproved/`,
+  `knowledge/`, review HTML, or `dist/`.
+
+### Final Report
+
+Report in the user's language. Include only:
+
+- view refs compiled in this round;
+- candidate ids staged and whether they contain verbatim or empty sections;
+- validation warnings that still matter for review;
+- whether review, close, verify, or build is the next status route.
+
+Do not report internal payload digests, source-ref hashes, internal workspace
+paths, absolute paths, scratch file paths, or raw CLI JSON unless the user asks
+for debug output.
+
+</procedures>

package/plugins/claude/skills/skill-prose-compile/references/internal-procedures/close-gate.md

@@ -0,0 +1,132 @@
+---
+name: close-gate
+description: >
+  Internal procedure invoked by the current compile/continue flow; not a user
+  slash command. Runs after review apply. Triggers `context close --format json`,
+  which derives knowledge/structure.yaml, projects approved edges, and runs the
+  final verify gate. Agent intervention is limited to interpreting CLI output
+  and routing verify errors back to source capture, align structure, compile
+  actions, or review as appropriate. The skill never hand-edits rendered
+  knowledge.
+tools:
+  - Bash
+---
+
+# close-gate — approved structure projection + final verify
+
+Close a compile run. The CLI does the work; the skill reads the
+CLI's output and routes any failure back to the correct upstream
+command. It does not hand-edit rendered knowledge.
+
+## TL;DR — Non-negotiables
+
+- CLI-driven. `context close --format json` derives `knowledge/structure.yaml`,
+  projects approved edges, and verifies the final workspace including edge
+  source refs. Use the command's stdout + exit code; that's the close's full
+  output.
+- **Agent NEVER edits rendered knowledge from the close stage.** The CLI is the
+  sole writer for approved structure projection. If verify reports an error
+  here, route it back, not around:
+  - Content / Section issues → re-run the current compile gate for the affected
+    node after fixing compile actions.
+  - Structural issues → return to the align structure gate and reconfirm.
+  - Source/evidence issues → recapture the affected source, then rerun align or
+    compile as status instructs.
+- Exit 0 → summarise approved node count, approved edge count, structural edge
+  contract status, and verify status. References, changelog, package index,
+  section fingerprints, and full incremental cache rebuilds are not current
+  close output.
+- Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not hand-open the affected rendered article.
+- Materialized knowledge means approved Markdown plus its approved
+  `knowledge/structure.yaml` projection. A compile skip action records reviewed
+  evidence, but it does not by itself materialize an arbitrary finalized Node.
+- Never re-run compile actions from close to paper over verify failures. Draft
+  failures belong in the compile loop.
+- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `sources/`, `unapproved/`, `knowledge/`, or `dist/` files.
+- Current close can self-heal stale or malformed `knowledge/structure.yaml`
+  projection by deriving it again from approved Markdown and approved edge
+  sources. It must not rewrite verbatim section body.
+- LLM-assisted repair (`--fix-with-llm`) is not a current close action.
+- Output language: summary prose matches the user's language; CLI output, issue codes, file paths stay as printed.
+- Current align state is internal CLI state, not a file protocol. The CLI owns
+  this lifecycle — the agent must not move, delete, or archive workspace output
+  files by hand.
+- Semantic decisions are applied and recorded before close. Compile-close does
+  not judge or rewrite semantic decisions; it only verifies the already-applied
+  workspace and rebuilds approved structure projection.
+
+<reference>
+
+## Stages inside `context close --format json`
+
+Close is one in-process command with one exit code:
+
+1. **Approved knowledge scan** — reads approved Markdown only through CLI
+   project readers.
+2. **Structure projection** — writes deterministic `knowledge/structure.yaml`
+   with nodes, approved edge projection, input hash, and structural edge
+   contract status.
+3. **Workspace verify** — runs the final verify gate. Any error prevents close
+   readiness.
+4. **Status receipt** — reports whether close is ready and which upstream gate
+   owns any failure.
+
+## Outcome routing
+
+| Outcome | Agent action |
+|---|---|
+| Ready, verify pass | Summarise approved nodes, approved edges, structural edge contract, and verify status. Stop. |
+| Ready, verify warnings only | Summarise warning codes and state that build may proceed when warnings are allowed by status/build gate. |
+| Verify error in approved section content/evidence | Surface the issue list and route back to compile actions or source recapture as indicated by status. Do not edit approved Markdown. |
+| Verify error in approved structure projection | Run `context close --format json` once more only when status says the projection is close-repairable; otherwise return to align structure. |
+| Source/evidence stale or missing | Route to source capture/refresh, then rerun align/compile as status instructs. |
+
+The close stage never edits rendered knowledge on the agent side. Every verify
+error routes back to the correct upstream gate (source capture, align
+structure, compile actions, or review), never sideways into a hand Edit. Use
+the CLI issue code and hint printed by `context close --format json` for the
+error→command mapping.
+
+References, changelog, section fingerprints, and package index rebuilds are not
+current close outputs.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Invoke close
+
+Run `context close --format json`. The caller may have already invoked it;
+check for existing output before re-running.
+
+### Step 2 — Interpret
+
+Use stdout + stderr. The exit code selects the path via [Outcome routing](#outcome-routing).
+
+### Step 3 — Route errors to the correct upstream command
+
+For each error in the CLI's report, classify via [Outcome routing](#outcome-routing) and name the re-entry command in your report. Do NOT hand-edit rendered knowledge — that violates the CLI-sole-writer principle and masks the real upstream fix. Specifically:
+
+- Section / content issue → rerun the current compile gate for that node.
+- Structure issue → return to align structure and user confirmation.
+- Source/evidence issue → recapture the affected source, then rerun align or
+  compile as status instructs.
+
+One pass. If the CLI reports multiple errors, list them all and let the user choose the order; do not loop the close stage itself.
+
+### Step 4 — Report
+
+Summarise in the user's language:
+
+- Approved node count.
+- Approved edge count and structural edge contract status.
+- Verify result: pass / pass-with-unverifiable-evidence / fail, with issue
+  codes verbatim.
+
+Stop. Do not auto-invoke follow-on commands.
+
+### Step 5 — Final guardrails
+
+Run close once, surface every error with its re-entry command, and never inspect or edit rendered knowledge outside the CLI.
+
+</procedures>

package/plugins/claude/skills/skill-prose-compile/references/internal-procedures/compile-actions/references/action-domain-gates.md

@@ -0,0 +1,52 @@
+# Action and Domain gates
+
+Consult this reference when **`node.node_type` is `action` or `domain`**. For
+`entity` Nodes, ignore this file and follow the main SKILL.md procedure.
+
+## Action Nodes (`node.node_type === "action"`)
+
+Treat the confirmed node type and planned sections as the compile boundary for
+procedural claims. An Action Node exists because align confirmed process
+evidence: steps/phases, trigger -> handling -> result, role collaboration, or a
+repeatable plan. Actor, goal/outcome, repeatability, answerability, trigger,
+step, and phase claims **must** come from the selected planned section
+`source_refs[]`; do not invent process semantics from the title alone.
+
+| Evidence pattern | What it authorizes |
+|---|---|
+| Planned section source refs contain ordered steps, phases, or repeatable handling | `spec` or `example` Sections for procedure content. |
+| Planned section source refs explicitly name actor, goal, outcome, or repeatability | Concise `description` / `spec` Sections using those same refs. |
+| No source ref states a trigger | **No trigger Section.** Write goal or applicability if supported, but do not fabricate a trigger sentence. |
+| Existing structure edge or unresolved relation indicates another Node is required for answerability | Mention only what the current source refs support; keep the relation in structure, not in compile action fields or verbatim body. |
+
+If the planned sections for an `action` node do not contain source-backed
+process evidence, treat that as a structural defect and return to align using
+[structural-challenges.md](structural-challenges.md). Do not invent an action
+body just because the node type is `action`.
+
+If the current evidence can only support one thin Section or only a parallel
+option/config list, do not stretch it into procedure prose. Emit `skip` for the
+unsupported planned section, or return to align so the node can be revised. The
+CLI does not auto-downgrade an Action or choose replacement Entity tags.
+
+## Domain Nodes (`node.node_type === "domain"`)
+
+Treat Domain nodes as grouping surfaces. The domain's scope and child grouping
+are expressed by confirmed `edges[]` and by source-backed planned sections; they
+do **not** authorize new reader-facing facts by themselves.
+
+- Source refs on planned sections may orient coverage of the Domain's range, but
+  only those refs can support reader-facing text.
+- Child relations belong to `structure.yaml` typed edges, not active Sections;
+  do not turn a child list into a Section.
+- Align-time grouping rationale is not evidence. Do **not** turn it into a
+  `description` Section unless the planned source refs state the same claim.
+
+Recall the mount matrix limit: Domain Nodes allow only `description`, `warning`, `principle`, `decision`, `faq`. A spec / example / comparison / incident / changelog landing here is a kind/type mismatch — drop down the priority chain or `skip`.
+
+## How this slots into the main procedure
+
+- **Step 1 — Sanity-check**: after the standard `node.id` / mount-matrix check,
+  run the action/domain inspection above.
+- **Step 2 — Classify**: respect the gate's authorization boundary when picking kinds.
+- **Step 5 — Self-verify**: confirm no Section was written from evidence the gate disallowed.

package/plugins/claude/skills/skill-prose-compile/references/internal-procedures/compile-actions/references/notes.md

@@ -0,0 +1,48 @@
+# Note snippets
+
+Consult this reference only when the current CLI exposes note evidence in a
+source-bound phase view. Note evidence carries conversation material
+(revisions, decisions, brainstorms) rather than primary source documents.
+
+## TL;DR
+
+Note snippets are **prioritization hints, not write authority**. `note_intent`, `anchored_to[]`, and `revision_kind` may suggest update / replacement / complement / skip, but they never authorize a write without semantic review.
+
+## How to route a note snippet
+
+When a source evidence entry has `source_type: "note"`:
+
+1. **Compare against the anchor first.** If `anchored_to[]` names this Node or one of its Sections, treat that target as the candidate for `update` / replacement review / `add` (as a complement) / `skip`. **Do not create a new Node** from the note title here — that is an align-time concern.
+
+2. **Use `note_intent` and `revision_kind` to bias the action**:
+
+   | `note_intent` | typical action |
+   |---|---|
+   | `revision` | `update` when meaning stays the same; otherwise replacement review against the anchored Section |
+   | `decision` | `add` a `decision` Section when no equivalent exists; otherwise `update` |
+   | `brainstorm` | usually `skip` unless the brainstorm explicitly confirms a fact the Node should record |
+
+   `revision_kind` (`replace` / `clarify` / ...) refines the choice within `revision`.
+
+3. **No-write reviewed-no-write case.** If the note says "don't modify active
+   knowledge yet" or the correct outcome is no-write after review, emit `skip`
+   with the note's current `source_refs[]` when the CLI exposes them. This lets
+   semantic review record `reviewed_no_write` instead of treating the skip as an
+   unreviewed no-op.
+
+4. **Bare skip is not allowed for notes.** A bare `skip` (no evidence) is only
+   for deterministic no-op cases such as unchanged input or pure navigation.
+   Notes always carry an anchor and an intent; the skip must cite the note's
+   explicit source ref when the current CLI exposes one.
+
+## Where this lives in the main procedure
+
+- **Step 2 — Classify**: run the note-first comparison **before** the generic kind priority chain. If the note resolves to `update` / replacement review / `skip` (reviewed), record the current action or user/structure route and move on; do not also process the same note through the generic chain.
+- **Step 5 — Self-verify**: every note snippet was either consumed by an
+  anchored action or carried into a `skip` with `source_refs[]` when the current
+  CLI exposes citeable refs.
+
+Notes never become compile challenge actions on their own. If a note describes a
+structural problem (missing Action, wrong parent, etc.), capture or cite the
+underlying source evidence and return to the structure gate described in
+`references/structural-challenges.md`.

package/plugins/claude/skills/skill-prose-compile/references/internal-procedures/compile-actions/references/refresh-and-update.md

@@ -0,0 +1,85 @@
+# Refresh and update
+
+Consult this reference when **any** of the following holds:
+
+- `existing.sections[]` is non-empty (Node already has active knowledge; this is a refresh, not a first compile).
+- `incremental.status` is `unchanged` or `full-context` (non-default incremental signals).
+- `incremental.locator_only_changes[]` is non-empty (locator-only deltas without content changes).
+
+For first compile of a fresh Node with `incremental.status === "changed-only"`, skip this file.
+
+## Incremental status handling
+
+| `incremental.status` | What to do |
+|---|---|
+| `changed-only` (default) | Normal path — main SKILL.md procedure applies as written. |
+| `unchanged` | Emit exactly one `skip` action with a brief reason. Do not iterate snippets. |
+| `full-context` | Draft from the full fallback. **Preserve `unknown_inputs[]` reasons** in any abort/retry explanation so the caller sees why the fallback was needed. |
+
+The CLI may deterministically skip unchanged output or update locator-only evidence before writing. **Do not force artificial content changes to bypass fingerprint skip** — those skips are part of the protocol, not a problem to route around.
+
+## Locator-only changes
+
+`incremental.locator_only_changes[]` entries always carry `agent_action: "none"` and `handled_by: "compile-close"`. **Do not emit a draft action for those Sections** unless the same Section also appears in `changed_blocks[]` with a real content change.
+
+## Reconciling with `existing.sections[]`
+
+When `existing.sections[]` is non-empty, every section id you read here is a
+potential same-section `update` target or a signal that the structure/user gate
+must decide a higher-risk replacement or withdrawal. Walk the existing Sections
+in order and decide:
+
+| Raw evidence vs existing Section | op |
+|---|---|
+| Raw still supports the existing claim unchanged | Emit nothing (or one summarising `skip`) |
+| Raw clarifies or rephrases without changing meaning | `update` — same `section-N` stays active |
+| Raw changes meaning (new spec value, reversed decision) | Stop and route to user/structure review; do not emulate a replacement with `update` |
+| Raw removes the supporting evidence | Stop and route to user/structure review; do not hide the previous active section with a compile no-write |
+
+### Replacement vs `update` semantics
+
+Replacement preserves the audit trail so readers can see that the prior policy
+changed — **critical for specs / decisions / principles**. Use `update` only
+for typo / wording fixes / detail additions that do not change meaning. When
+meaning changes or support disappears, do not write a compile action until the
+user/structure gate has chosen the intended disposition.
+
+### Current output mechanics
+
+- `update` keeps the same planned section identity. In the current
+  `context.compile-actions.v1` shape, emit `op: "update"` with `section_id`,
+  `kind` when needed, `summary` when useful, and current `source_refs[]`. Omit
+  `content` so the CLI mirrors the new cited source span. If the intended update
+  requires translation, compression, or reorganization, stop and return to the
+  structure/user gate instead of writing reader-visible content in compile.
+- Fresh replacement content is a new structure/review decision, not a current
+  compile write shape. Preserve the semantic judgment in the user report or
+  unresolved structure discussion and route back to the appropriate gate; do
+  not invent unsupported target fields.
+
+## Output shape (current update path)
+
+```jsonc
+{
+  "schema_version": "context.compile-actions.v1",
+  "view_ref": "architecture:entity/example",
+  "actions": [
+    {
+      "op": "update",
+      "section_id": "retention-policy",
+      "kind": "spec",
+      "summary": "...",
+      "source_refs": ["file:docs/example.md#span:retention L10-14@<span-hash>"]
+    }
+  ]
+}
+```
+
+## How this slots into the main procedure
+
+- **Step 1 — Sanity-check**: when `existing.sections[]` is non-empty, read every section id and status before classifying snippets. When `incremental.status` is `unchanged`, short-circuit with one `skip`.
+- **Step 2 — Classify**: still walk the kind priority chain for each citation-eligible snippet; the reconciliation table above governs which `op` to emit for snippets that map to an existing Section.
+- **Step 5 — Self-verify**: every `update` targets a known planned section id
+  from the confirmed structure. If a replacement or withdrawal judgment has no
+  accepted compile action shape, stop and route back through review/align
+  instead of emitting unsupported fields.

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

@@ -0,0 +1,73 @@
+# 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.