@c4a/context-cli 0.6.1 → 0.6.2

package/plugins/skills/context-init/references/internal-procedures/skill-prose-align.md

@@ -1,322 +0,0 @@
----
-name: skill-prose-align
-description: >
-  Internal procedure invoked by the public Context continuation entry; not a user slash command.
-  Uses Context document evidence views to propose, validate, and confirm
-  `unapproved/structure.yaml` without reading raw snapshots directly.
-tools:
-  - Bash
----
-
-# skill-prose-align
-
-Turn captured document evidence into confirmed structure.
-
-## TL;DR
-
-- Use this after document capture, or when the user asks to split, merge,
-  reorganize, classify, or relate document evidence.
-- When status is `captured-ready-to-classify`, run every returned capture-phase
-  evidence command before editing `src/index.ts`. Use the collection-neutral
-  title tree, span index, and exact text to propose a mainline collection; wait
-  for user confirmation, then declare matching align/compile/review phases.
-- The first product output is a structure draft, not final page body.
-- Read source material only through CLI evidence views: `read-plan`,
-  `source-index`, `span-detail`, `span-text`, `schema`, and
-  `structure-summary`. Additional views are diagnostic surfaces; use the route
-  and view set returned by the CLI.
-- Write and validate `context.structure.v1` into `unapproved/structure.yaml`.
-  Stop for user confirmation before compile.
-- Before semantic judgment, use the CLI `semantic-rules` View to page through
-  only `semantic_rules.required`. Use each selection `reason` to keep unrelated
-  rules out of the current judgment.
-- Plan source evidence as Sections before promoting any heading to a Node/View.
-  Promotion depends on source-backed standalone retrieval identity, not on a
-  hard-coded section kind or collection name.
-- Do not produce or validate a structure payload from this entry file alone. A
-  ruleset already present in the active context may be reused only when both its
-  `handle` and `digest` match. If the context was compacted, the digest changed,
-  or the rule content is no longer present, resume the CLI rule-page sequence.
-- When status reaches `structure-ready` or `needs-prose-compile`, hand off to
-  `skill-prose-compile.md`.
-- Compile, review, close, verify, and build remain separate gates.
-
-<reference>
-
-## User-Facing Gates
-
-Use semantic labels, not SDK function names:
-
-| Gate | Say this | Do not say this first |
-|---|---|---|
-| Collection classification | "I have inspected the captured evidence. Based on these source characteristics, I recommend this knowledge category; please confirm before I configure compilation." | Guessing from a filename, URL, or SDK collection enum before investigation |
-| Material investigation | "I will read the evidence index and source spans through Context, then propose a structure draft." | `alignProse`, `source-index`, `context.structure.v1` |
-| Structure confirmation | "Confirming this structure freezes page paths, section ownership, and relationships for this compile round." | `unapproved/structure.yaml` as a raw parameter |
-| Compile handoff | "The structure is confirmed; I will switch to source-bound compile for draft pages." | Continuing to edit structure in compile |
-
-## Runtime Discipline
-
-`skill-continue-workflow` owns global state routing; this Skill owns only the
-align phase selected by that route. Use CLI evidence/rule/diagnostic Views,
-follow their exact continuation commands, and treat hints as subordinate to
-`next_action`. Evidence reads may be parallel; stage, confirm, Review apply,
-close, and build writes remain serial. Never reconstruct digest values or
-inspect CLI-managed state files as a substitute for a View.
-- 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/`, or package output directories.
-- If a validation or view response includes `reason_code`, `path`, `missing[]`,
-  `diagnostics`, `repair_hints`, or `agent_hints`, treat those fields as the
-  repair contract. Do not recover by replaying a stale manual route, editing
-  rendered files, or guessing schema aliases.
-
-## Evidence Views
-
-Recommended read order:
-
-```bash
-context run align:<type>:<source>:<collection> --view read-plan --format json
-context run align:<type>:<source>:<collection> --view source-index --compact --format json
-context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
-context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
-context run align:<type>:<source>:<collection> --view schema --format json
-context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
-```
-
-Use CLI-returned `next_command` values for pagination. Do not reconstruct
-documents with ad hoc `cat`, `grep`, or scripts against `sources/` or `.tmp`.
-
-## Structure Contract
-
-The structure draft uses `schema_version: context.structure.v1` and lives at
-`unapproved/structure.yaml` after staging. It contains:
-
-- lifecycle state such as validated/confirmed and frozen snapshot metadata;
-- concept `nodes[]` with stable `node_ref`, `node_type`, title/summary, and
-  ownership;
-- materialized `views[]` with `view_ref`, collection, path, section plans, and
-  evidence refs;
-- typed edges using the closed set defined by the CLI;
-- unresolved items when evidence is weak, conflicting, or the target node is
-  missing.
-
-Confirmed structure is a human gate. Validation passing is not the same as
-confirmation. Do not write `lifecycle.state: confirmed`, `confirmed_by`,
-`confirmed_at`, or `structure_digest` until the user has explicitly confirmed
-the structure proposal in the conversation.
-
-When the current conversation explicitly authorizes fully managed operation,
-use the CLI-returned `--stage --managed` command after successful validation.
-The CLI records `confirmed_by: managed-session`; validation errors and unresolved
-evidence still block confirmation. Never persist managed mode in `defineProject`
-or reuse it in another conversation.
-
-## Procedure References
-
-These are current structure planning rules. They define the source-bound
-semantic gates for Node planning, section ownership, and relationship handling.
-
-| Decision | Reference |
-|---|---|
-| Structure planning, Node ownership, density, candidate resolution | [skill-prose-align/references/internal-procedures/structure-planning.md](skill-prose-align/references/internal-procedures/structure-planning.md) |
-| Node type, title, tags, fake entity, action/domain gates, edge gates | [skill-prose-align/references/internal-procedures/structure-planning/references/gates.md](skill-prose-align/references/internal-procedures/structure-planning/references/gates.md) |
-| Source density and coarse reading judgment | [skill-prose-align/references/internal-procedures/structure-planning/references/density-profile.md](skill-prose-align/references/internal-procedures/structure-planning/references/density-profile.md) |
-| Candidate anomalies, stable ids, paths, duplicates, and conflicts | [skill-prose-align/references/internal-procedures/structure-planning/references/candidate-resolution.md](skill-prose-align/references/internal-procedures/structure-planning/references/candidate-resolution.md) |
-
-</reference>
-
-<procedures>
-
-### Step 1 — Open Material Investigation
-
-Run:
-
-```bash
-context run align:<type>:<source>:<collection> --view read-plan --format json
-```
-
-Use the returned views, budgets, snapshot hash, and next actions. If the CLI
-reports a missing or stale snapshot, route back to source capture/refresh. Do
-not read the snapshot file yourself.
-
-### Step 2 — Read Evidence Through The Index
-
-Read a compact index before requesting exact spans:
-
-```bash
-context run align:<type>:<source>:<collection> --view source-index --compact --format json
-```
-
-For exact evidence, copy CLI-returned source refs or next commands:
-
-```bash
-context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
-context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
-```
-
-Keep a short note of what evidence supports each proposed node, section, and
-edge. If the evidence is weak or conflicting, keep it as unresolved instead of
-turning it into a fact.
-
-Before drafting structure, read:
-
-- [skill-prose-align/references/internal-procedures/structure-planning.md](skill-prose-align/references/internal-procedures/structure-planning.md)
-- [skill-prose-align/references/internal-procedures/structure-planning/references/gates.md](skill-prose-align/references/internal-procedures/structure-planning/references/gates.md)
-- [skill-prose-align/references/internal-procedures/structure-planning/references/density-profile.md](skill-prose-align/references/internal-procedures/structure-planning/references/density-profile.md)
-- [skill-prose-align/references/internal-procedures/structure-planning/references/candidate-resolution.md](skill-prose-align/references/internal-procedures/structure-planning/references/candidate-resolution.md)
-
-Do not treat this as optional background. These files contain the current
-semantic gates for source-bound structure planning. A structure payload drafted
-without the applicable references is incomplete, even if the CLI schema accepts
-its shape.
-
-### Step 3 — Draft And Validate Structure
-
-Request the schema:
-
-```bash
-context run align:<type>:<source>:<collection> --view schema --format json
-```
-
-Create a `context.structure.v1` YAML file. The draft may include a one-page-per
-source shape, but that is represented as ordinary nodes and sections; it does
-not bypass structure confirmation.
-
-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 phase state and
-must not be read back as a substitute for CLI views.
-
-Validate:
-
-```bash
-context run align:<type>:<source>:<collection> --validate --input <structure.yaml> --format json
-```
-
-Validation returns a compact summary and writes a temporary HTML report under
-`.tmp/context-runtime/reports/`. A validation report with
-`confirmation_ready=false` is an Agent repair artifact, not a user review gate:
-do not ask the user to approve it. The staged report produced after
-`confirmation_ready=true` is the final review surface; use its
-`structure_report.file_url` as the primary user-facing link and include
-`structure_report.absolute_path` as a copyable fallback.
-If the user needs a focused view, run:
-
-```bash
-context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
-```
-
-The explicit `structure-summary` View returns the full summary for focused
-debugging. For user confirmation, prioritize the default first-screen fields:
-`review_notice`, `structure_report`, and `structure_summary_compact`. A valid
-user-facing confirmation prompt must include the report `file_url`, the absolute
-path fallback, and a compact summary of collections/views/unresolved/diagnostics.
-Do not ask the user to confirm from counts alone.
-
-Repair diagnostics by routing them to the right decision:
-
-- source ref or snapshot mismatch -> reread evidence views or refresh capture;
-- unsupported node/section/edge -> remove it or mark unresolved;
-- duplicate/conflict -> ask the user which structure should win;
-- illegal edge type, missing target node, or edge without source refs -> fix the
-  structure or keep the relation unresolved;
-- stale structure -> regenerate from the current snapshot hash.
-
-When validation returns `repair_confirmation_blockers`, follow its exact repair
-route without stopping for human confirmation. `--repair suggested-splits`
-mechanically splits non-contiguous source mirror Sections; write its
-`repaired_payload` to a scratch YAML file and validate again. For oversized
-Views, use the returned child-View and contains-edge suggestions, but classify
-each child Node from evidence instead of mechanically inheriting the parent
-type. Repair other diagnostics from evidence and validate again. Ask the user only when evidence
-supports multiple incompatible semantic choices, and label that question as a
-structure-design choice rather than final review. Do not stage until
-`confirmation_ready=true`.
-
-### Step 4 — Review Structure Before Confirmation
-
-After validation reports `confirmation_ready=true`, stage the draft. The stage
-command opens the final report. Then show the user:
-
-- node list and planned paths;
-- section ownership;
-- typed edges and unresolved relation candidates;
-- expected compile order;
-- downstream impact: these choices freeze paths, section ownership, and
-  relationships for this compile round.
-- the `structure_report.file_url` generated by validate or `--view
-  structure-summary`;
-- the `structure_report.absolute_path` fallback in case the host cannot click
-  file URLs.
-
-If the CLI stage result includes `next_action.human_gate: true`, treat it as a
-hard stop for structure review. Do not ask for a blind "confirm structure"
-reply. Surface the report `file_url`, absolute path, and enough structured
-summary for the user to inspect what will be confirmed.
-
-Do not turn `confirmation_blockers` into a preliminary approval round. A
-validator-required page split, continuous-source split, ref repair, or
-structure-spine connection is work to resolve before staging. If a genuinely
-ambiguous semantic choice needs the user, ask only that choice and then resume
-repair; it does not replace the final report-based confirmation.
-
-Use the host's multi-choice question tool when available. If unavailable, use a
-short Markdown fallback. Good options are:
-
-- Confirm this structure and continue to compile.
-- Revise the structure with additional guidance.
-- Go back to source scope or capture because the evidence set is wrong.
-
-Only after confirmation, run the CLI confirmation command, normally:
-
-```bash
-context run align:<type>:<source>:<collection> --confirm --format json
-```
-
-If confirming a structure file other than `unapproved/structure.yaml`, pass it
-with `--input <structure.yaml>`. A draft stage in `unapproved/structure.yaml` is
-not confirmation. Do not edit `unapproved/structure.yaml` after confirmation to
-change meaning; return to this gate instead.
-
-### Step 5 — Handoff To Compile
-
-After the user confirms the structure and the CLI reports `structure-ready` or
-`needs-prose-compile`, stop this procedure and follow:
-
-```text
-skill-prose-compile.md
-```
-
-Do not keep editing structure while compiling. If compile diagnostics show the
-planned structure is wrong, return to this align gate and ask the user to
-confirm the corrected structure.
-
-### Step 6 — Self-verify Checklist
-
-- [ ] Evidence came only from Context evidence views.
-- [ ] `context.structure.v1` was validated before user confirmation.
-- [ ] User confirmed the structure before compile.
-- [ ] Compile was delegated to `skill-prose-compile`; this procedure did not
-  write draft page body.
-- [ ] Relationships are expressed as structure edges or unresolved items.
-- [ ] No direct edits were made to `sources/`, `.tmp`, `unapproved/`,
-  `knowledge/`, review HTML, or `dist/`.
-
-### Final Report
-
-Report in the user's language. Include only:
-
-- evidence views actually read;
-- proposed and confirmed node count, section count, edge count, and unresolved
-  count;
-- user confirmation outcome;
-- validation warnings that still matter for compile;
-- next route reported by status or the align phase.
-
-Do not report payload digests, snapshot hashes, source-ref hashes, absolute
-paths, or scratch file paths unless the CLI explicitly asks the user to repair
-one.
-
-</procedures>

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

@@ -1,132 +0,0 @@
----
-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/skills/context-init/references/internal-procedures/skill-prose-compile/references/internal-procedures/compile-actions/references/action-domain-gates.md

@@ -1,52 +0,0 @@
-# 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/skills/context-init/references/internal-procedures/skill-prose-compile/references/internal-procedures/compile-actions/references/notes.md

@@ -1,48 +0,0 @@
-# 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/skills/context-init/references/internal-procedures/skill-prose-compile/references/internal-procedures/compile-actions/references/refresh-and-update.md

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