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

package/plugin/skills/skill-align-workflow/references/gates.md

@@ -1,162 +0,0 @@
-# Node Classification Gates
-
-Use these gates before every candidate batch and before authoring the align payload requested by `next_action.input_schema`.
-Align owns Node type, tag, graph, planned Section, and ownership classification. It does **not** write Section prose.
-
-## Node Type Order
-
-Answer in this order and stop at the first match:
-
-1. **Action?** A large executable event / process with both:
-   - scale: can support `planned_sections` with at least two distinct Section kinds, or contains at least one child Action;
-   - process evidence: explicit steps, phases, trigger -> handling -> result, role collaboration, or repeatable plan. Parallel lists such as "three API modes" are not process evidence.
-2. **Entity?** A concrete independent subject with retrieval value: deployable code, product/application/system, library/module/CLI/symbol, or an atomic term/pattern.
-3. **Domain?** A container/scope that groups at least one child Node.
-4. Otherwise do not create a Node; leave the material for compile as a Section under the owning Node.
-
-Good examples:
-
-| Type | Examples |
-|---|---|
-| `domain` | "X business domain", "Y technical area", "Z research topic" |
-| `entity` concrete | `@acme/api-server`, `@acme/ui-kit` `Button`, "X sub-application" |
-| `entity` term | "X identifier", "Y business metric", idempotency |
-| `action` | "user submits X request end-to-end flow", "operator executes Y change flow", "team Z release flow" |
-
-## Title and Source Heading Rules
-
-Classify the Node by the evidence referent, not by the source file title, heading, or local section title. A source title is ordinary evidence just like body prose. It has no automatic right to become `node.title`, `aliases[]`, or `slug`.
-
-After choosing `node_type`, choose the title to fit that type:
-
-| Final type | Title shape |
-|---|---|
-| `entity` concrete | The concrete product, service, library, module, CLI, symbol, application, or system name. |
-| `entity` term | The atomic concept or pattern name, without extra scope/process suffixes. |
-| `domain` | The grouping scope that owns child Nodes. |
-| `action` | The executable process / runbook / flow name that passed the Action Gate. |
-
-Scope/process words in a source title are warning signals when proposed as an Entity title, not hard classification rules. Re-check the type/title when a proposed Entity title contains words such as "方案", "架构", "体系", "演练", "流程", "策略", "能力", "机制", "framework", "architecture", "system", "strategy", "process", or "drill". Keep the wording only when evidence shows it is the formal name of a concrete object or an atomic term.
-
-Do not promote broad architecture/system/方案 content to `domain` just because it sounds like a scope. When the source has writable Sections but no resolvable current/existing child Nodes, use an Entity such as `[system]` or `[application]` and put the architecture facts in Sections. Use `domain` only when it groups child Nodes through `domain_gate.child_refs`.
-
-Relation-only sources should not force title copying or dangling graph edges. Decide placeholder handling in this order:
-
-1. If resolved current/existing child Nodes make the page a real grouping scope, preserve it as a no-write Domain.
-2. If an explicit user-facing retrieval need or graph need makes the source/page identity valuable, and the title names an atomic concept or concrete object, preserve it as a no-write Entity with root-level `planned_sections: []`. This priority still applies when all child refs are unresolved/deferred; keep those target hints pending rather than writing dangling graph refs.
-3. Otherwise, skip navigation-only / placeholder-only material and classify its coverable blocks, usually as `ignored`.
-
-Do not put `planned_sections` inside `domain_gate`. A kept placeholder needs support: `context_only` block(s) with `visible_to`, owned/shared evidence, or finalized graph support. `ignored` blocks only dispose unused material and do not support close materialization by themselves. For Domain placeholders, write only resolved current/existing children in `domain_gate.child_refs`; if all children are unresolved/deferred relation clues, use `child_refs: []` and keep those target hints in pending relation refs. If the source names only an atomic concept and that term is useful on its own, prefer a concise term Entity title without scope/process suffixes.
-
-For no-write placeholder summaries, describe only the preserved page identity and unresolved navigation clues. Do not say the Node "provides navigation/links/relations to X" unless those targets are resolved graph children or rendered links; say the source contains deferred navigation clues instead.
-
-## Entity Tag Rules
-
-Use `tags` to state what the Entity is. Legal combinations:
-
-| Case | Tags |
-|---|---|
-| Runtime/code object | one A tag: `app`, `service`, `lib`, `cli`, `module`, or `symbol` |
-| Product-analysis object | one B tag: `application` or `system` |
-| Code + product object | one A tag plus one B tag |
-| Pure term / pattern | only `term` |
-
-`term` is mutually exclusive with A/B tags. React is `[lib]`, not `[lib, term]`; if a separate term entry is useful, create another Entity tagged `[term]` and let compile use Section-local `refers_to_nodes[]`.
-
-## Action Gate
-
-Use `node_type: action` only after the Node Type Order says action. Fill `action_probe` and `action_gate`.
-
-`action_probe` still uses the five schema booleans, but the semantic bar is:
-
-| Field | Meaning | Evidence rule |
-|---|---|---|
-| `has_steps_or_phases` | Process evidence exists: steps, phases, trigger -> handling -> result, role collaboration, or repeatable plan. | Hard requirement; support it from block evidence. |
-| `has_actor_or_role` | A user, system, operator, service, or role performs the work. | May be inferred; record the source. |
-| `has_outcome_or_goal` | The process has a target result, acceptance condition, or operational goal. | May be inferred; record the source. |
-| `is_repeatable_or_planned` | The work is repeatable, scheduled, policy-like, or intentionally planned. | May be inferred; record the source. |
-| `queries_answerable_with_refs` | The Node can answer how/when/who/what-to-do questions from cited blocks. | May be inferred; record the source. |
-
-Do not emit an Action for a single sentence, a one-off conclusion, a short operation, or a parallel enumeration. Those become Sections under the owning Entity or Domain.
-
-Action anti-examples:
-
-| Candidate | Correct routing |
-|---|---|
-| "migrate to X tool" as one conclusion | `decision` Section under the owning Entity |
-| "component X usage" as one sentence | `description` + maybe `example` under X |
-| "submit -> validate -> generate" as one unexpanded sentence | `spec` Section under X/Y |
-| "three API call modes" | `comparison`, `spec`, or `description` Section; not Action |
-
-## Fake Entity Gate
-
-A relationship-style title is only suspicious by itself. Downgrade or change type when at least **two** signals are true:
-
-1. Title contains relationship language such as "X impact on Y", "Y under X", "Y side of X", "X migration", or "X collection".
-2. No legal Entity tag fits.
-3. The Node does not stand alone away from its upstream Node.
-
-Repairs:
-
-| Pattern | Repair |
-|---|---|
-| "X impact on Y" | Section under X with `refers_to_nodes: [Y]` |
-| "Y under X condition" | Section under Y; X is a condition in the Section body |
-| "X subsystem migration" | Action only if it clears the Action Gate; otherwise `decision` Section under X |
-| "X error collection" / "X FAQ collection" | `faq` / `incident` Sections under X |
-
-## Domain Gate
-
-Use `node_type: domain` only for a scope that groups child Nodes. Fill:
-
-| Field | Meaning |
-|---|---|
-| `scope_blocks[]` | Blocks that describe the scope boundary or grouping. |
-| `child_refs[]` | Candidate ids, local refs, or final slugs for children in the scope. |
-| `grouping_reason` | Why these children belong together under this domain. |
-
-If a domain has no resolvable child refs, no clear grouping reason, or only one same-file child without a broader scope, do not emit a Domain. For navigation-only / placeholder-only sources with only deferred children, skip the Node after ruling out standalone retrieval or graph value for an atomic-term or concrete Entity; still classify that source's coverable blocks with a source-wide `ownership_groups[]` rule, usually `ignored` for pure placeholders. Emit an Entity only when evidence names an atomic term or concrete object and choose its Entity tag yourself. The CLI rejects invalid Domain gates; it does not auto-downgrade a Domain or choose fallback tags.
-
-Scope-name titles such as "X 业务域", "Y 领域", "business domain", or "technical area" are a warning sign when proposed as Entity. Keep them as Entity only when the subject is an atomic term or concrete object; otherwise use Domain with `domain_gate.child_refs`.
-
-## Inference Sources
-
-`action_gate.inference_sources` is required and must be a structured object with four keys:
-
-```yaml
-inference_sources:
-  actor:
-    source_type: explicit-block
-    evidence_blocks: [7a6f4c9d2e10]
-    rationale: "The block names the operator role."
-  outcome_or_goal:
-    source_type: inferred-from-block
-    evidence_blocks: [7a6f4c9d2e10]
-    rationale: "The block describes recovery as the expected result."
-  repeatability_or_plan:
-    source_type: heading-and-block
-    evidence_blocks: [7a6f4c9d2e10]
-    rationale: "The runbook heading and ordered list indicate planned reuse."
-  answerability:
-    source_type: explicit-block
-    evidence_blocks: [7a6f4c9d2e10]
-    rationale: "The steps answer how the operation is performed."
-```
-
-Allowed `source_type` values:
-
-| Value | Use when |
-|---|---|
-| `explicit-block` | The evidence block directly states the signal. |
-| `heading-and-block` | The heading plus block text together support the signal. |
-| `ref-node` | An existing or same-decision Node reference supplies the signal. Include `ref_nodes`. |
-| `inferred-from-block` | The signal is inferred from block content. Keep the rationale short and concrete. |
-
-Each source must include `rationale` when inferred and at least one of `evidence_blocks[]` or `ref_nodes[]`.
-
-## Final Reflection
-
-- Entity cannot pick a legal tag, or depends on its upstream title to make sense -> write it as a Section under the upstream Node or change type before submit.
-- Action only supports one Section -> write it as a Section instead of an Action. The discriminator is scale, not the presence of "step" words.
-- Action "steps" are parallel options/configs -> route to Entity `comparison` / `spec` / `description`.
-- Domain has no children -> delete it or merge it into a larger Domain.

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

@@ -1,127 +0,0 @@
----
-name: skill-compile-close
-description: >
-  Packaged skill invoked by `/context:compile`; not a user slash command. Runs after every draft
-  iteration. Triggers `context compile close`, which in one invocation
-  refreshes locator-only evidence, canonicalizes source refs, compacts and verifies the final workspace,
-  rebuilds the knowledge index, appends a changelog
-  entry, rebuilds section fingerprints + incremental cache, and
-  archives compile scratch files. Agent intervention is
-  limited to interpreting the CLI's output and routing any verify
-  error back to its upstream command (`/context:compile` for Section
-  issues, `/context:align` for structural issues, `/context:drop`
-  for dropped-source references). The skill never hand-edits rendered knowledge.
-  Activates once all draft actions are applied and before user-visible
-  success is declared.
-tools:
-  - Bash
----
-
-# skill-compile-close — global verify + index + changelog
-
-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 compile close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. 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 articles, the index, and the changelog. If verify reports an error here, route it back, not around:
-  - Content / Section issues (`invalid-section-mount`, `body-ad-hoc-heading`, `dangling-source-alias`) → user re-runs `/context:compile` (draft loop fixes its own Section actions; the close stage does not patch)
-  - Structural issues (`contains-cycle`, `edge-dangling-node`, `duplicate-slug`, `invalid-node-type`, `domain-same-file-child`) → user runs `/context:align` to revise the plan
-  - Source issues (`dropped-source-reference`) → user runs `/context:drop <id>` to complete the drop
-- Exit 0 → summarise node/section totals, verify, `recompiled`, `locator_updates`, `rebuilt`, fingerprint rebuild count, archive status / archived file count, and any `ready_with_debt` coverage warnings when printed. If the close receipt reports severely low coverage, surface the returned `--cover-uncovered-only` command as the recommended repair before treating the debt as accepted.
-- Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not hand-open the affected rendered article.
-- Coverage warnings are CLI-owned diagnostics. `ready_with_debt` means close succeeded and unresolved coverage remains visible. For severely low coverage, recommend one `--cover-uncovered-only` repair pass unless the user explicitly accepts the debt; otherwise report the warning and follow returned coverage view commands / `available_actions[]` only if the user chooses a repair or skip round.
-- Coverage and engagement denominators count primary citable content evidence. URL/reference-only, marker, frontmatter, embed, navigation, and context-only evidence is excluded or bucketed as non-blocking bookkeeping by the CLI.
-- Materialized knowledge means either a CLI-written knowledge article, or an explicit no-write placeholder from align: `planned_sections: []` plus source/context/graph support. A compile skip action records reviewed evidence, but it does not by itself materialize an arbitrary finalized Node.
-- If close is blocked only because finalized block ownership/support is wrong, use `context compile repair ownership --input - --format json` with `align.ownership-patch.v2`. This keeps the active compile workflow and completed node progress. Do not abandon compile just to run `context align patch ownership`.
-- Never re-run `context compile draft` from close to paper over verify failures. Draft failures belong in the draft loop.
-- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, knowledge files, or `/tmp` workflow artifacts.
-- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `context compile close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
-- LLM-assisted repair (`--fix-with-llm`) is not available in the current release.
-- Output language: summary prose matches the user's language; CLI output, issue codes, file paths stay as printed.
-- Successful close archives CLI scratch artifacts through the output lifecycle and rebuilds the user-level incremental cache. 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 derived indexes.
-
-<reference>
-
-## Stages inside `context compile close`
-
-Close is one in-process command with one exit code:
-
-1. **Coverage guard with self-heal** — drops stale candidates and treats high-signal candidates already backed by active Sections as covered.
-2. **Locator refresh** — if evidence moved but block hashes are unchanged, updates only section locators.
-3. **Source ref canonicalization** — if a Section `source_ref` resolves to the same raw evidence block but has a stale anchor/range rendering, rewrites it to the canonical locator.
-4. **Workspace compact** — re-renders every knowledge article canonically (Section order, frontmatter field order, `## Contains` list ordering, heading depth).
-5. **Rebuild knowledge index** — regenerates the index from the current workspace state; previous content overwritten.
-6. **Append changelog** — appends one compile list item to the changelog; existing entries preserved.
-7. **Workspace verify** — runs the full rule set against the final close output. Any error flips exit to 2 and close rolls back its writes.
-8. **Rebuild incremental cache** — rebuilds section fingerprints and cache indexes from workspace truth sources.
-9. **Archive scratch files** — moves CLI-owned context/draft/prepare/review scratch payloads into the output archive lifecycle.
-
-## Outcome routing
-
-| Outcome | Agent action |
-|---|---|
-| Exit 0, 0 issues | Summarise those counts in the user's language: Nodes touched; Sections added / updated / superseded / deprecated / skipped; `recompiled`; `locator_updates`; `rebuilt`; verify green. Stop. |
-| Exit 0, warnings only | Summarise + list warnings verbatim. For severely low coverage, recommend the CLI-returned `--cover-uncovered-only` repair command before final acceptance; for other coverage warnings, surface returned coverage view commands / `available_actions[]` instead of inventing a local decision matrix. |
-| Exit 2, Section / content issue | Surface the full issue list; point the user at re-running `/context:compile` (the draft loop owns Section writes). Do NOT Edit the affected rendered article. |
-| Exit 2, `compile-close-finalized-node-missing-knowledge` | If the missing Node has real citation evidence, point the user at `/context:compile` for that Node. If it is intentionally navigation-only or placeholder-only and only block ownership/support is wrong, use `context compile repair ownership --input - --format json` to make support explicit with `context_only` + `visible_to` or owned/shared evidence. `ignored` blocks do not support the placeholder by themselves. If the Node itself is structurally wrong, route back to `/context:align` after the active compile workflow is resolved. |
-| Exit 2, structural issue (cycle, duplicate slug, `invalid-node-type`, `domain-same-file-child`) | Surface the full issue list; point the user at `/context:align` to revise structure. Do not re-run compile. |
-| Exit 2, `dropped-source-reference` | Surface the source-id; point the user at `/context:drop <id>` to complete the drop cleanup. |
-
-The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile close` for the error→command mapping.
-
-## Changelog entry shape
-
-`context compile close` appends one markdown list item per run to
-the changelog with aggregate counts — not a multi-line
-block:
-
-```
-- [compile] nodes=N sections=M recompiled=R locator_updates=L @ <ISO timestamp>
-```
-
-`[drop]` lines from `/context:drop` follow the same single-line list-
-item convention (see the drop skill for the exact shape).
-
-</reference>
-
-<procedures>
-
-### Step 1 — Invoke close
-
-Run `context compile close`. The caller (typically `/context:compile`) 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 → user re-runs `/context:compile` (draft loop produces new Section actions; the CLI re-writes).
-- `compile-close-finalized-node-missing-knowledge` → content Nodes go back through `/context:compile`; ownership-only placeholder support fixes use `context compile repair ownership --input - --format json`; structural Node changes still go through `/context:align` after the active compile workflow is resolved.
-- Structural issue → user runs `/context:align` (revise the plan; re-compile afterwards).
-- `dropped-source-reference` → user runs `/context:drop <id>` to finish drop cleanup.
-
-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:
-
-- Nodes touched and counts per op (add / update / supersede / deprecate / skip / locator-only).
-- Knowledge index rebuilt / updated; changelog appended at `<timestamp>`.
-- Incremental close counts printed by the CLI: `recompiled`, `locator_updates`, `canonical_source_ref_updates`, `rebuilt`, and section fingerprint rebuild count.
-- Verify result: green / `<n>` warnings / `<n>` errors (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/plugin/skills/skill-compile-draft/SKILL.md

@@ -1,175 +0,0 @@
----
-name: skill-compile-draft
-description: >
-  Packaged skill invoked by `/context:compile`; not a user slash command. For one Node at a time, reads
-  the CLI-provided `NodeContext` (planned metadata, raw snippets, and
-  existing Sections if any), classifies every raw fragment into a Section
-  kind via the priority chain, writes source-bound actions with `kind`,
-  optional `summary` / `content`, and `source_block_ids[]`,
-  and emits a compile draft JSON document for the caller to submit to the current envelope's
-  `next_action.command`.
-  Activates when `/context:compile` iterates across the confirmed align plan.
-tools:
-  - Bash
----
-
-# skill-compile-draft — write Section actions for one Node
-
-Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update` / `supersede` / `deprecate`) actions; emit JSON; the CLI performs every write.
-
-## TL;DR — Non-negotiables
-
-- One Node per invocation — `node_slug` MUST equal `node.slug`; no cross-Node writes. Finish the current Node's draft quality checks before the caller moves to another Node's review/apply loop.
-- Agent emits JSON only; no markdown, no direct workspace file writes. The caller submits the JSON to the current envelope's `next_action.command`; the CLI validates and stores workflow payloads.
-- Evidence boundary: treat the CLI-provided NodeContext and evidence views as complete. Cite only block ids surfaced as citation-eligible in `source-refs-index` `items[]`, `citable_source_refs[]`, or `raw_snippet_indexes.citation_eligible`; treat `supporting_context_refs[]`, `context_only`, and secondary-shared snippets as background. `request_full_text` may expose visible text for inspection through the narrow text view (`context compile context <slug> --request-full-text <block_id> --view text --format json`), and it does not change citation eligibility. If supporting/context-only evidence is needed as a citation, emit `pending_ownership_challenge` or `structure_challenge` — see [references/structural-challenges.md](references/structural-challenges.md). Never `grep` / `sed` / `jq` / `cat` / `head` raw `--format json` stdout or workflow scratch files in `/tmp` or `.context/.cache/`; use semantic views and follow returned `next_command` / `how_to_explore[]`. For write commands that take `--payload-digest`, omit the flag unless the CLI explicitly asks for a stale guard. When an explicit digest is needed, use `context workflow show --payload <name> --digest-only --format text`; do not parse JSON stdout to recover it.
-- Actions are candidate write actions, not final semantic decisions; `context reconcile prepare` re-derives near-duplicate / conflict / merge relations from `candidates[]` on its own. Op naming is scoped by schema: compile-draft `actions[]` already targets Sections, so Section lifecycle ops are verb-only (`add`, `update`, `supersede`, `deprecate`, `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 provided `raw_snippets[]`: if there are 3+ citation-eligible snippets, a one-action draft is valid only when the later snippets are duplicates, navigation, placeholders, or continuations of the same fact. Small dense docs still need multiple actions when later snippets state distinct capabilities, constraints, examples, risks, FAQ, or usage notes. Large manuals/design docs should compile to several orthogonal actions in the same draft. Do not switch into "speed mode" because the first action validates; coverage is part of the draft task.
-- Pick `kind` from the CLI's `context schema compile-draft` contract, especially `section_kind_priority` and the mount matrix. Treat kind precision as a drafting quality preference, not a reason to loop forever when the CLI accepts the write. A `decision` fits when the source explicitly records a choice, tradeoff, adopted path, or policy conclusion with a reason; multiple surfaced alternatives are a strong signal but not required. Bare rules or checks without a recorded choice are usually `spec`. Reach `description` only after every more specific kind fails.
-- `node.planned_sections[]` is an align-time scaffold hint, not a hard completion gate. Prefer a planned kind when the evidence fits; if a source-backed stronger kind differs, emit it and let the CLI warning guide review.
-- `kind × 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.
-- Every write action cites raw via `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`; the CLI expands it to canonical `source_refs[]` before saving. Use explicit `source_refs[]` only when the CLI gives no block id for the needed citation. Multiple ids/refs in one action must be one contiguous citation-eligible run from the same source; split around any intervening citation-eligible block used by another action. Never mix both fields in one action, fabricate ids, or cite navigation-only blocks as evidence for a content Section.
-- For large source-ref views, prefer the returned `source_refs_index_command` / `source_refs_command` / `--view source-refs-index` when you only need block ids; open `source_refs_detail_command` only when you need quote preview or explicit `source_refs[]`. Treat `--draft-scaffold` as a compact action skeleton for large Nodes; use returned full-text/detail commands for only the blocks an action needs.
-- `content` is optional and omitted by default on source-backed writes. If the cited raw block is already the right reader-visible text, cite it with `source_block_ids[]` / `source_refs[]` and let the CLI mirror raw into content. Write `content` only for an intentional source-faithful reader-surface rewrite, such as translation, structural reorganization, or preserving a table, list, command, config, or code fence that would otherwise be unclear. Add `summary` when it helps readers/query output; summary is recall text, not evidence. The CLI rejects retired fields (`body`, `detail`, `raw`, singular `source_ref`, quoted-evidence) with canonical repair hints — read those hints rather than memorising the blacklist. Omit optional fields when empty.
-- 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; content may keep 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 block text.
-- Preserve source-backed URLs, code identifiers, `source_ref`, or `block_id` literals when they are part of the reader-facing knowledge or a repair challenge. Do not rely on memorized URL rules, and do not add literals only for scoring or traceability.
-- `refers_to_nodes[]` only carries known slugs. Prefer already materialized or compiled target Nodes; in first-pass compile, skip a slug that is only known from the current align plan and not yet materialized unless the CLI explicitly surfaces it as safe or needed. Never invent a slug.
-- `skip` is the honest default when raw adds nothing. Bare `skip` (no evidence) is only for deterministic no-ops such as unchanged input, pure navigation, or context-only/background snippets; empty `source_block_ids[]` / `source_refs[]` on skip is treated as bare skip. When a citation-eligible snippet was reviewed and intentionally not written, emit `skip` with `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id` so semantic review can record `reviewed_no_write`. Never attach `context_only` / supporting block ids to skip; raise a challenge if they should become citation evidence.
-- 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 `NodeContext.generation_policy.language` when present; otherwise match the raw 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. Do not patch an already clear stored summary solely to switch language, but do not draft English prose summaries for Chinese evidence. Draft `content` is source-bound: prefer the cited source language when it differs from the workspace language, and do not translate quoted English facts into Chinese just to satisfy workspace language. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
-- 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 NodeContext should vary between repeated Node draft calls.
-
-## Edge cases — consult references when:
-
-| Condition | Reference |
-|---|---|
-| `node.type` is `action` or `domain` | [references/action-domain-gates.md](references/action-domain-gates.md); use `node.action_gate` (including `trigger_blocks`) and treat `node.domain_gate` as grouping metadata |
-| any `raw_snippets[].source_type` is `"note"` | [references/notes.md](references/notes.md) |
-| `existing.sections[]` non-empty, **or** `incremental.status` is `unchanged` / `full-context`, **or** `incremental.locator_only_changes[]` non-empty | [references/refresh-and-update.md](references/refresh-and-update.md) |
-| evidence implies missing Action / wrong parent / `depends_on` gap / ownership upgrade from `context_only` or secondary-shared | [references/structural-challenges.md](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 — `NodeContext`
-
-Canonical shape: `context schema node-context --format yaml` (or `--format json`). The CLI is the source of truth for fields, enums, and produced-by paths.
-
-Boundary recap (rules not captured by the schema enums):
-
-- `mentions[]` are raw positions that named this Node; `raw_snippets[]` are the wider context blocks around those positions, or the changed raw blocks selected by `context compile scan`. These two arrays are the evidence floor — never reach outside them.
-- `node.sources[]` are the only sources that may be cited as `src-N`. `node.context_sources[]` contribute `raw_snippets[]` for comparison or background only and must not be cited unless the CLI has also placed that source in `node.sources[]`.
-- `source_id` is the source registry id (e.g. `local:billing`); `src-N` aliases only appear inside `source_ref` strings. Prefer `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id` in draft `source_block_ids[]`; if you must use explicit `source_refs[]`, copy `raw_snippets[].source_ref` verbatim.
-
-## Output — Compile Draft JSON (main path)
-
-Canonical shape: `context schema compile-draft --format yaml` (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`** and **`skip`**. A typical new Section action is `{ op: "add", kind: "<chain-picked>", summary: "...", source_block_ids: ["<block_id>"] }`; omit `content` unless this action intentionally rewrites the cited raw for the reader. 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 carries `source_block_ids[]` only from citation-eligible `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`.
-
-Minimal valid draft envelope:
-
-```json
-{
-  "schema_version": "compile.draft.v2",
-  "node_slug": "<matches node.slug>",
-  "actions": []
-}
-```
-
-`update` / `supersede` / `deprecate` ops live in [references/refresh-and-update.md](references/refresh-and-update.md). `structure_challenge` / `pending_ownership_challenge` ops live in [references/structural-challenges.md](references/structural-challenges.md). Do not emit them from the main path.
-
-`source_block_ids[]` is a mechanical shorthand over the same citation-eligible evidence; a single citation is still a single-element array. Treat `planned_section_groups[].draft_action_templates` as the align section scaffold. Keep hard citation-gap templates separate because non-contiguous evidence cannot form one source_ref; `heading_spans` and `local_headings` are facts for your judgment, not split commands. When one Section summarises contiguous multi-block evidence, list only the block ids the action actually consumes, and only when no citation-eligible block between them belongs to another action. If using explicit `source_refs[]`, copy them verbatim from `raw_snippets[].source_ref`. Preserve raw wording in `content` when it is already clear. 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, include the relevant fenced block in `content` only when writing reader-visible content. 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 schema compile-draft --view minimal --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 block:
-
-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 code / config / command block belongs in `example`; a comparison table belongs in `comparison`; a Q+A pair belongs in `faq`; a real incident with timeline belongs in `incident`; ordinary "typical scenario" / case-study / impact-result examples are `example`, not `incident`, unless the source is explicitly an outage, incident review, postmortem, or dated fault-handling timeline; a versioned change record belongs in `changelog`; an explicit source-backed choice / tradeoff / adopted path with rationale belongs in `decision` even when only one chosen option is surfaced; 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.
-
-## Glossary and `refers_to_nodes`
-
-When a Section meaningfully discusses another known Node, or should be discoverable through that Node in query/navigation, put that known slug in `refers_to_nodes[]` — do NOT substitute it into the prose. This preserves explicit cross-Node anchors for query answers and citations without rewriting the claim. Slugs come from existing Sections or the context glossary. Slugs that are only declared by the current align plan but not yet materialized are pending targets: skip them on first-pass draft unless the CLI explicitly surfaces the relationship as safe or needed. Do not remove an existing valid ref just because verify says the target is pending; continue compiling the target or let the CLI refresh renderer blocks. A Section can reference multiple Nodes (common on `comparison` / `decision`). Do not add a slug for incidental product-name mentions that add no Section-local relationship or navigation value.
-
-If the CLI returns `compile-missing-refers-to-node`, treat it as a relation-recall check, not a style advisory. Add the suggested slug when the drafted Section text meaningfully discusses that known Node or should be discoverable through it. Omit it only for incidental mentions, code/package names inside examples, or navigation-only evidence that should remain no-write.
-
-If the CLI returns summary quality or low-coverage advisories with `agent_recommended_action: ignore`, 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; flag it in `decisions.notes` for a re-align pass.
-
-</reference>
-
-<procedures>
-
-### Step 1 — Sanity-check the context
-
-Confirm `node.slug` is set; abort if not. Note `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 provided `raw_snippets[]` 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 `raw_snippets[]` entry:
-
-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.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 snippets by their `block_locator_id` heading prefix 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 raw evidence establishes a separate durable Node identity.
-
-### Step 3 — Build actions
-
-For each classified snippet:
-
-1. Decide whether `content` is needed. The default for source-backed writes is no `content`: cite `source_block_ids[]` / `source_refs[]` and let the CLI mirror raw into the Section content. Add explicit `content` only when the cited raw needs an intentional reader-surface rewrite, such as translation, structural reorganization, or preserving Markdown/code/table shape that the mirror path would not express clearly. Keep one coherent, cited fact group per action.
-2. When you do write `content`, keep it faithful to the cited raw terms: do not introduce acronyms, abbreviations, translations, or aliases that do not appear in the cited raw snippet unless raw itself defines the equivalence or the user confirms it later during semantic review.
-   - Do not lightly rewrite same-language prose for fluency, casing, entity-name consistency, or sentence cleanup. If the raw text is already clear, omit `content` instead of writing a near-copy.
-   - Preserve meaningful Markdown formatting from the cited raw when explicit `content` is necessary: inline code markers, fenced blocks, Markdown link targets, blockquote markers, nested list structure, tables, and emphasis on key terms. Do not flatten these into plain prose unless the formatting is purely decorative.
-   - There is no separate default `evidence-echo` warning. Treat "echo" as an anti-pattern: raw copied only to show basis/evidence, while `source_ref` already provides traceability.
-   - For `description` / `spec`, a concise summary plus the cited bullet list is acceptable when the bullets are the useful user-facing knowledge. It becomes echo only when the copied text is not meant to be read as active knowledge.
-   - For `example` Sections that cite a code, config, or command fence, keep `content` centered on the cited fenced block. Put framing prose such as "basic configuration example" in `summary`, or cite a separate prose block in a separate action when that prose is itself source-backed knowledge. If the source only has prose/list text with inline code, preserve prose/list plus inline code; do not turn it into a fenced script.
-3. For long `content`, add `summary` when it helps readers or query output. Summary is LLM-authored reader/query aid: one plain paragraph, no Markdown, and should stay compact. In YAML payloads, write `summary` as a plain single-line scalar; reserve literal block scalars for multi-line `content`. If you cannot write a meaningful summary, omit the field entirely; generic placeholders like "description section covering N evidence blocks" are worse than no summary. The CLI reports advisory hints for missing or weak summaries; it does not treat summary quality as an evidence failure. Keep summaries faithful to the source-backed action, but do not copy raw-only keywords into `summary` for scoring.
-4. Preserve meaningful source-backed literals in `content`, `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.
-5. Omit `confidence` for ordinary confirmed claims. Assign it only when the evidence is clearly verified, inferred, or speculative according to the schema enum.
-6. Fill `refers_to_nodes[]` per [Glossary and refers_to_nodes](#glossary-and-refers_to_nodes).
-7. Cite evidence with `source_block_ids[]`, picking values from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`. Use CLI-provided `planned_section_groups[].draft_action_templates` as the starting scaffold; hard citation-gap templates stay separate, while heading/local-heading annotated evidence may stay together or be split by semantic knowledge unit. When one Section summarizes contiguous multi-block evidence, list only the block ids consumed by that Section action. If the evidence is non-contiguous or contains separable claims, split the draft into separately cited actions instead of stretching one action across unrelated blocks. For `skip`, include `source_block_ids[]` 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`, mix `source_block_ids` with `source_refs`, or use quoted-evidence fields; invalid evidence references remain blocking.
-
-Rendered knowledge starts with optional `c4a:summary`, then the active `content`. If `content` differs from the cited raw, the CLI may render a debug-only `c4a:raw` block for audit; agents must not emit `raw`.
-
-### 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 `compile.draft.v2`, `node_slug` matches `node.slug`, fields conform to `context schema compile-draft`, citations point only at CLI-provided evidence, and NodeContext was the only evidence source.
-
-</procedures>

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

@@ -1,34 +0,0 @@
-# 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 revise the structure; the CLI does not auto-downgrade an Action or choose replacement Entity tags.
-
-## 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

@@ -1,34 +0,0 @@
-# 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_block_ids[]` containing the note's citation-eligible block id. 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 block id or explicit 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_block_ids[]`.
-
-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`.