@c4a/context-cli 0.5.29-beta.17 → 0.5.29-beta.20

package/plugin/skills/skill-compile-draft/references/action-domain-gates.md

@@ -0,0 +1,34 @@
+# Action and Domain gates
+
+Consult this reference when **`node.type` is `action` or `domain`**. For `entity` Nodes, ignore this file and follow the main SKILL.md procedure.
+
+## Action Nodes (`node.type === "action"`)
+
+Treat `node.action_gate` as the compile boundary for procedural claims. An Action Node exists because align found both scale and process evidence: at least two meaningful Sections or a child Action, plus steps/phases/trigger-handling-result/role collaboration/repeatable plan evidence. Actor, goal/outcome, repeatability, answerability, trigger, step, and phase claims **must** come from cited `raw_snippets[]` or the structured `action_gate.inference_sources` entries.
+
+| Gate block | What it authorizes |
+|---|---|
+| `step_blocks` / `phase_blocks` / cited step snippets | `spec` or `example` Sections for procedure content |
+| `actor_blocks`, `goal_blocks`, `outcome_blocks`, `repeatability_or_plan_blocks` | concise `description` / `spec` Sections when the same source refs are citation-eligible |
+| Empty `trigger_blocks` | **No trigger Section.** Write goal or applicability if supported, but do not fabricate a trigger sentence. |
+| `inference_sources.answerability.ref_nodes` | Becomes `refers_to_nodes[]` when the current Section depends on those Nodes; do **not** summarize those Nodes' facts inside this Node. |
+
+If `action_gate` is absent on a Node whose `type` is `action`, treat it as a structural defect — emit a `structure_challenge` (see `references/structural-challenges.md`) instead of inventing process semantics.
+
+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` or `structure_challenge` so align can downgrade it to the owning Entity/Domain Section.
+
+## Domain Nodes (`node.type === "domain"`)
+
+Treat `node.domain_gate` as **grouping metadata only**. It explains scope and child grouping; it does **not** authorize new Section facts by itself.
+
+- `scope_blocks` may help orient your Section coverage of the Domain's range but are not write authority.
+- `child_refs` belong to the align graph, not to active Sections — do not turn the list into a Section.
+- `grouping_reason` is align-time reasoning. Do **not** turn it into a `description` Section unless citation-eligible raw snippets 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.slug` / mount-matrix check, run the action_gate / domain_gate 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/plugin/skills/skill-compile-draft/references/notes.md

@@ -0,0 +1,34 @@
+# Note snippets
+
+Consult this reference when **any `raw_snippets[].source_type` is `"note"`**. Note snippets came from `context capture --note` and carry 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 / supersede / complement / skip, but they never authorize a write without semantic review.
+
+## How to route a note snippet
+
+When a `raw_snippets[]` 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` / `supersede` / `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` or `supersede` 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 `source_refs[]` containing the note's `raw_snippets[].source_ref`. 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 `source_refs[]`) 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 source_ref.
+
+## 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` / `supersede` / `skip` (reviewed), record the action 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[]`.
+
+Notes never become structure_challenge or pending_ownership_challenge on their own. If a note describes a structural problem (missing Action, wrong parent, etc.), capture the underlying evidence in raw form and emit the challenge from that — see `references/structural-challenges.md`.

package/plugin/skills/skill-compile-draft/references/refresh-and-update.md

@@ -0,0 +1,71 @@
+# 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 rewrites 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-N` id you read here is a potential `update` / `supersede` / `deprecate` target. 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) | `supersede` — old flips to `deprecated`; new gets fresh `section-N+k` |
+| Raw removes the supporting evidence | `deprecate` with `reason` |
+
+### `supersede` vs `update` semantics
+
+`supersede` preserves the audit trail so readers see the prior policy — **critical for specs / decisions / principles**. Use `supersede` whenever the new statement *replaces* the old one's content; use `update` only for typo / wording fixes / detail additions that do not change meaning.
+
+`deprecate` is for "old rule removed without replacement". It needs a `reason`.
+
+### `update` / `supersede.new` mechanics
+
+- `update` keeps the same `section-N` id; provide a new `body` (and optional new `source_refs[]`) but do not include `kind` unless the kind itself is changing.
+- `supersede.new` is a fresh Section; it needs `kind`, `body`, `source_refs[]`, and may carry `refers_to_nodes[]` and `confidence` per the same rules as `add`.
+- `deprecate` only needs `target_section_id` and `reason`. Do not pass `body` or `source_refs[]`.
+
+## Output schema (refresh ops)
+
+```jsonc
+{
+  "actions": [
+    { "op": "update", "target_section_id": "section-3",
+      "body": "...",
+      "refers_to_nodes": null,
+      "source_refs": ["src-1#api L18-21@c0d4e5f61728"] },
+    { "op": "supersede", "target_section_id": "section-5",
+      "reason": "raw published a new retention value",
+      "new": { "kind": "spec", "body": "...",
+               "refers_to_nodes": ["..."],
+               "source_refs": ["src-1#limits L30-34@9d1e2f3a4b5c"] } },
+    { "op": "deprecate", "target_section_id": "section-2", "reason": "..." }
+  ]
+}
+```
+
+## How this slots into the main procedure
+
+- **Step 1 — Sanity-check**: when `existing.sections[]` is non-empty, read every `section-N` id and `status` (active vs deprecated) 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` / `supersede` / `deprecate` targets a known `section-N` from `existing.sections[]`. If not, return here.

package/plugin/skills/skill-compile-draft/references/structural-challenges.md

@@ -0,0 +1,76 @@
+# Structural and ownership challenges
+
+Consult this reference when the cited evidence **cannot be written as a Section under the current align 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. Emit a challenge action instead; the CLI stores it as a workflow payload and compile-close exposes it as debt until an align resolution handles it.
+
+## When to challenge vs. when to skip
+
+| Situation | Action |
+|---|---|
+| Evidence is a repeatable procedure with steps that clearly warrant a sub-Action | `structure_challenge` with `kind: missing_action_node` |
+| Evidence depends on a Node that the current align graph does not link to this Node | `structure_challenge` with `kind: missing_depends_on_edge` |
+| Evidence belongs under a different parent | `structure_challenge` with `kind: wrong_parent` |
+| A finalized shared block split removed all primary evidence from this Node | `structure_challenge` with `kind: wrong_shared_block_split` |
+| The Node should not exist (its evidence belongs elsewhere) | `structure_challenge` with `kind: extra_action_node` |
+| A `context_only` or secondary-shared block holds facts this Node needs to cite | `pending_ownership_challenge` with `requested_role: "shared"` or `"owned"` |
+
+Supported `structure_challenge.kind` values: `missing_action_node`, `extra_action_node`, `wrong_shared_block_split`, `missing_depends_on_edge`, `wrong_parent`.
+
+`pending_ownership_challenge.requested_role` is `owned` (the Node should be sole author) or `shared` (the Node should join an existing owners list).
+
+## Required fields
+
+```jsonc
+{
+  "op": "structure_challenge",
+  "challenge_id": "ch_0001",
+  "kind": "missing_action_node",
+  "node_slug": "<matches node.slug>",
+  "action_tag": "rollout-runbook",
+  "summary": "The cited evidence is a repeatable procedure.",
+  "source_ref": "src-1#ops L40-55@c0d4e5f61728",
+  "reason": "Align must review structure before compile writes process prose."
+}
+```
+
+```jsonc
+{
+  "op": "structure_challenge",
+  "challenge_id": "ch_0002",
+  "kind": "wrong_shared_block_split",
+  "node_slug": "<matches node.slug>",
+  "unresolved_target": "rollout-runbook",
+  "reason": "The finalized shared block split leaves this Node with only secondary, non-citable evidence."
+}
+```
+
+```jsonc
+{
+  "op": "pending_ownership_challenge",
+  "challenge_id": "och_0001",
+  "node_slug": "<matches node.slug>",
+  "block_id": "2f4b8c1e9a03",
+  "requested_role": "shared",
+  "reason": "A visible context_only or secondary shared block contains facts that need citation."
+}
+```
+
+Different `kind` values demand different sub-fields. The CLI returns `agent_hints[].correct_shape` on shape errors; follow that hint rather than guessing.
+
+## What these are NOT
+
+- **Not a substitute for `skip`** when raw simply has no write-worthy fact for this Node.
+- **Not a Section.** Challenges never appear in active knowledge; they only travel through workflow state.
+- **Not a free upgrade path.** `request_full_text` may expose visible evidence text for inspection, but it does not change citation eligibility. If you need to cite secondary content, emit `pending_ownership_challenge` — do not paraphrase the secondary content into a Section.
+
+## How this slots into the main procedure
+
+- **Step 3 — Build actions**: when evidence implies a missing Action, missing `depends_on`, wrong parent, or needed ownership upgrade, emit the corresponding challenge instead of writing a Section.
+- **Step 5 — Self-verify**: no Section write cites a `context_only` or secondary-shared block; if any did, replace the Section with a `pending_ownership_challenge`.

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

@@ -0,0 +1,106 @@
+---
+name: skill-compile-judge
+description: >
+  Packaged skill invoked by `/context:compile`; not a user slash command. Consumes the full compile prepare payload,
+  judges each draft action's source support and relation to listed candidates,
+  and emits a compile.judge-decisions.v1 document for `context reconcile review`.
+tools:
+  - Bash
+---
+
+# skill-compile-judge — judge compile support and relation
+
+Decide whether each prepared compile item is supported by cited raw evidence
+and how it relates to the candidate Sections listed by the CLI. Emit judge
+decisions only; the CLI reviews, applies, and writes every workspace change.
+
+## TL;DR — Non-negotiables
+
+- Input is the full compile prepare payload. Compact summaries are only a pointer; if needed, load the full payload with the `workflow_payload.show_command` from `context compile --draft ... --prepare`.
+- Do not inspect workspace storage directly or run ad-hoc scripts to reconstruct candidates. Use only `items[]`, `evidence[]`, `source_support` diagnostics, `candidates[]`, `previous_decisions[]`, and `judge_handoff`.
+- Output exactly one JSON or YAML document with `schema_version: "compile.judge-decisions.v1"` and `decisions[]`.
+- Keep one decision per prepared `item_id`, preserving prepare order.
+- For support, output `support_verdict: supported | weak | unsupported` plus `support_reason`.
+- For relation, output `relation_verdict: new | duplicate | supersede | conflict | merge_into` plus `relation_reason`.
+- Compare only the candidates listed on that item. Do not perform workspace-wide BM25, grep, or source-file searches.
+- Fill `compared_section_ids` with every visible candidate Section id you inspected and set `compared_count` to the total candidate count inspected across pages. If candidates are paged, continue until `compared_count >= candidate_total` before final output.
+- Escape hatch: when an item has no candidates, `relation_verdict: new` with `compared_section_ids: []` and `compared_count: 0` is valid and expected.
+- For `duplicate`, `supersede`, `conflict`, or `merge_into`, set `target_section_id` to the matched candidate Section id.
+- Same `source_ref` can support different Section kinds only when the semantic role differs. Detect and explain same-source-ref multi-kind cases instead of treating them as automatic duplicates.
+- Weak support is a warning-level verdict, not permission to invent missing facts. Unsupported support should normally pair with `conflict` or a later user question rather than a write decision.
+
+<reference>
+
+## Output Shape
+
+```yaml
+schema_version: "compile.judge-decisions.v1"
+mode: compile
+decisions:
+  - item_id: claim-001
+    support_verdict: supported
+    support_reason: "The cited raw block explicitly states the same invoice handling behavior."
+    relation_verdict: new
+    relation_reason: "No listed candidate covers this claim."
+    compared_section_ids: []
+    compared_count: 0
+```
+
+For a relation against an existing candidate:
+
+```yaml
+schema_version: "compile.judge-decisions.v1"
+mode: compile
+decisions:
+  - item_id: claim-002
+    support_verdict: supported
+    support_reason: "The cited evidence covers the correction."
+    relation_verdict: supersede
+    relation_reason: "section-3 states the older behavior and should be replaced."
+    target_section_id: section-3
+    compared_section_ids: [section-3, section-7]
+    compared_count: 2
+```
+
+## Verdict Meanings
+
+| field | value | Meaning |
+|---|---|---|
+| `support_verdict` | `supported` | Cited raw evidence covers the claim's hard facts. |
+| `support_verdict` | `weak` | The evidence plausibly supports an ordinary summary, but review may ask for confirmation. |
+| `support_verdict` | `unsupported` | The claim adds facts or boundaries not present in cited raw evidence. |
+| `relation_verdict` | `new` | No listed candidate already covers the proposed knowledge. |
+| `relation_verdict` | `duplicate` | A listed candidate already covers the same claim. |
+| `relation_verdict` | `supersede` | A listed candidate is stale or wrong and should be replaced by the new claim. |
+| `relation_verdict` | `conflict` | The prepared claim and candidate disagree and need user resolution. |
+| `relation_verdict` | `merge_into` | The prepared claim should update or refine one listed candidate. |
+
+</reference>
+
+<procedures>
+
+### Step 1 — Load Full Prepare Payload
+
+If the caller gave compact prepare output, use its workflow payload command to
+load the full `prepare` payload. Do not infer missing candidates from memory.
+
+### Step 2 — Judge Support
+
+For each item, read the proposed content and cited evidence. Use
+`source_support` only as a diagnostic hint; 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 Section id in `compared_section_ids`, and set
+`compared_count` to the total candidate count inspected across pages. If the
+candidate list is empty, emit `new` with an empty compared list and
+`compared_count: 0`.
+
+### Step 4 — Emit Judge Decisions
+
+Return only the `compile.judge-decisions.v1` document. The caller passes it
+directly to `context reconcile review --decisions -`.
+
+</procedures>