@c4a/context-cli 0.5.29-alpha.1

package/plugin/skills/align-scan/references/data-model.md

@@ -0,0 +1,343 @@
+# Data model — canonical tables
+
+The authoritative lookup for Node / Section / Edge / Section-kind
+semantics. Every other skill in the pipeline cites this file rather
+than re-stating the tables. When the rules change, change them here.
+
+## Scope
+
+All lookup data; no imperative steps. Consumers:
+
+- `align-scan` — Node type + Entity tag classification
+- `align-propose` — identity, establishment, Edge enumeration
+- `align-finalize` — layout rules, mount matrix re-check
+- `compile-draft` — Section kind priority, mount matrix, `source_ref`
+- `compile-close` — verify rule codes
+
+<reference>
+
+## Node types
+
+| Type | Nature | Judgement | Typical examples |
+|---|---|---|---|
+| `domain` | Space / container | Not executed; holds other Nodes | Payment domain; frontend engineering; product handbook |
+| `entity` | Thing / object | Concrete, nameable thing (deployable / installable / renderable / importable) | Checkout app; `@acme/payment-api`; React; a config-file instance |
+| `action` | Event / flow | Independently-scoped ordered event with actors + value output | "Buyer initiates refund"; "DB scale-up runbook"; "New-hire onboarding" |
+| `concept` | Abstract idea | Principle / term / pattern; not executable, not a thing | "Unidirectional data flow"; "SKU"; "Idempotent design" |
+
+Closed set. Anything that doesn't fit one of these is not a Node —
+demote to a Section on a host Node.
+
+## Entity vs Concept test
+
+| Signal | → Entity | → Concept |
+|---|---|---|
+| Has a concrete integration surface (CLI / config file / API / hook / importable package) | ✓ | |
+| Describes a behaviour / mechanism / capability without a specific thing | | ✓ |
+| User asks "what is X" → definitional | | ✓ |
+| User asks "how do I use / integrate X" → instantiable | ✓ | |
+
+Spec / convention / pattern names are always Concepts. A specific
+file instance of a spec is an Entity; the spec rules describing that
+file are a Concept.
+
+## Entity tag groups
+
+Entity candidates carry tags from two independent groups; at least
+one of (A ∪ B) must be set.
+
+**Group A — code-implementation layer** (≤1):
+
+| tag | Meaning |
+|---|---|
+| `app` | End-to-end application with a user interface |
+| `service` | Deployable with a network port; serves an API |
+| `lib` | Framework / SDK referenced by other code; no standalone runtime |
+| `cli` | Executable command-line tool |
+| `module` | Code organisation unit that fits none of the above |
+| `symbol` | Code symbol (function / class / method / component) |
+
+**Group B — product-concept layer** (≤1):
+
+| tag | Meaning |
+|---|---|
+| `application` | Directly creates user-visible value; users experience it |
+| `system` | Supports other applications; users don't experience it directly |
+
+**Legal states**:
+
+| State | Tags | Example |
+|---|---|---|
+| Pure code unit | A only | `[lib]` for React |
+| Pure product concept | B only | `[application]` for "Order management module" |
+| Shippable + user value | A + B (one each) | `[app, application]` for a checkout app |
+
+Illegal: two in A; two in B; neither group. Neither-group means the
+candidate is not a valid Entity — see [False-Entity smell](#false-entity-smell).
+
+## Action tags
+
+Exactly one, chosen from:
+
+| tag | When |
+|---|---|
+| `user-story` | A user / role acts on a product surface |
+| `runbook` | Emergency response / fault-handling / alert response |
+| `howto` | Routine operational guide (team process, release, how-to) |
+| `roadmap` | Time-bound planning / milestone / quarterly delivery |
+
+Never invent `procedure` / `milestone` / `release`.
+
+Action tags are Node tags only. Never place `user-story`, `runbook`,
+`howto`, or `roadmap` in `planned_sections[]`; that field only accepts
+Section kinds from the table below.
+
+## Concept tags
+
+0 or 1 of:
+
+| tag | When |
+|---|---|
+| `term` | Atomic term / jargon (SKU, GMV, "authorised transaction") |
+| `pattern` | Architectural / design / behavioural pattern |
+| (none) | Pure abstract idea with no finer sub-kind |
+
+## Domain tags
+
+Usually none. A Domain is a bucket, not a category.
+
+## Deprecated tags
+
+Reject at classification time; map to the canonical replacement.
+
+| Deprecated | Reason | Canonical replacement |
+|---|---|---|
+| `capability` | Mixed three meanings | Business-area → `application` or Domain; sub-capability → A-group; requirement → Action |
+| `third-party` | Annotational | Put origin in `summary` |
+| `product` | Overlaps B `application` | `application` |
+| `subsystem` | Parent/child already in `contains` | A / B specific tag |
+| `infrastructure` | Overlaps B `system` | `system` |
+| `procedure` | Indistinguishable from `howto` / `runbook` | `howto` or `runbook` |
+| `architecture` | `pattern` covers it | `pattern` |
+| `principle` / `faq` | Collide with Section kinds | Section `principle` / Section `faq` |
+
+## False-Entity smell
+
+Relational titles are almost always not Entities:
+
+| Pattern | Handle |
+|---|---|
+| "X affects Y" / "X under Y" | Section (spec / warning / decision) on target-Node with `refers_to_nodes: [y]` |
+| "Y-side of X" / "X's Y part" | Section on the actual target Node |
+| "X rework / migration / refactor" | Usually an `action` describing the work, not an Entity |
+
+Rule: if no A-group AND no B-group tag fits naturally, the candidate
+is not an Entity. Mark `ambiguous` with a re-route note, never silently
+drop.
+
+## Node establishment thresholds
+
+| Type | Minimum to establish |
+|---|---|
+| `domain` | `contains` ≥1 child Node |
+| `entity` | None beyond tag validity |
+| `action` | ≥2 Section intents OR ≥1 sub-Action, with temporal / multi-party signal |
+| `concept` | Passes the three-test gate AND will be referenced by ≥1 Node |
+
+Below-bar candidates demote to a Section on a host Node.
+
+## Concept three-test gate
+
+All three must pass.
+
+| Test | Pass (✅) | Fail (❌) |
+|---|---|---|
+| Universality | Stands on its own outside this system / business | Only meaningful under one Entity / Action |
+| Reusability | Other unrelated Nodes will cite it | One-off story context |
+| Non-incarnation | Pure idea; no specific thing / process equivalent | An Entity / Action already holds it |
+
+Any ❌ → demote to Section. Never invent Concepts to group Sections.
+
+## Identity uniqueness
+
+| Type | Scope |
+|---|---|
+| `domain` | Global within the source_id scope |
+| `entity` | `(name, source_id, parent Entity or Domain)` |
+| `action` | Same `name` unique under the same parent |
+| `concept` | Same `name` unique under the same parent |
+
+## Edge types
+
+Five logical types. AST-layer edges (`imports / calls / extends /
+implements`) are emitted by the extractor, never by a skill.
+
+| type | Semantics | Directions |
+|---|---|---|
+| `contains` | Hierarchy | Domain → Entity/Action/Concept/Domain ; Entity → Entity ; Action → Action |
+| `depends_on` | Runtime / business dependency | Entity → Entity ; Action → Action |
+| `realizes` | Abstract landing on concrete | Entity → Concept (target MUST be Concept) |
+| `refines` | Same-type refinement | Action → Action ; Concept → Concept |
+| `related_to` | Loose association | Any → Any |
+
+`refers_to_nodes` is a Section field, not an Edge. It names Nodes a
+Section discusses. Never emit it as an edge entry.
+
+## Layout rules
+
+Physical organisation of `contains`:
+
+| Relation | File layout | Physical form |
+|---|---|---|
+| Same-file parent/child (Action→Action, Entity→Entity) | One file | Heading depth (`##` parent, `###` child) |
+| Cross-file parent/child | Separate files | Parent has `## Contains` markdown list linking to child files |
+| Domain → any child | Separate files always | Domain file holds `# title` + `## Contains` list only |
+
+**Domain hard rule**: Domain files never nest children inline; every
+child under a Domain is a standalone file. `contains` never appears in
+frontmatter.
+
+## Section kinds
+
+Ten kinds; priority chain (highest → lowest) governs stage-2
+classification:
+
+| # | kind | Trigger |
+|---|---|---|
+| 1 | `changelog` | Versioned change record (`valid_from` / `valid_until`) |
+| 2 | `principle` | Long-term invariant / design rule |
+| 3 | `spec` | Verifiable constraint with an explicit validation method |
+| 4 | `decision` | Choice with rationale + rejected options |
+| 5 | `comparison` | ≥2 subjects × ≥2 dimensions (usually a table) |
+| 6 | `warning` | Risk / gotcha / caveat explicitly flagged |
+| 7 | `incident` | Actual fault / outage case with time / impact |
+| 8 | `example` | Concrete snippet / sample / config |
+| 9 | `faq` | Question + answer pair; title is a question |
+| 10 | `description` | Fallback narrative — definition / explanation / spine |
+
+First match wins. `description` is the bottom, NOT the default.
+
+## Section mount matrix
+
+Section kind × Node type. `✓` = allowed; `—` = rejected at write time.
+
+| Section kind | Domain | Entity | Action | Concept |
+|---|:---:|:---:|:---:|:---:|
+| description | ✓ | ✓ | ✓ | ✓ |
+| spec | — | ✓ | ✓ | ✓ |
+| warning | ✓ | ✓ | ✓ | ✓ |
+| principle | ✓ | ✓ | — | ✓ |
+| decision | ✓ | ✓ | ✓ | ✓ |
+| incident | — | ✓ | ✓ | — |
+| example | — | ✓ | — | ✓ |
+| changelog | — | ✓ | — | — |
+| comparison | — | ✓ | — | ✓ |
+| faq | ✓ | ✓ | ✓ | ✓ |
+
+Hard rules worth emphasising:
+
+- `principle` never mounts on Action
+- `spec` never mounts on Domain
+- `incident` only on Entity / Action
+- `example` / `comparison` only on Entity / Concept
+- `changelog` only on Entity
+
+## `source_ref` canonical form
+
+Written in each Section's comment header:
+
+```
+src-N#<anchor> L<a>-<b>
+```
+
+All three segments required. `src-N` is a 1-based index into the
+Node's `frontmatter.sources[]`. `<anchor>` is a raw-file heading slug
+covering the line range, or the literal `document` when the raw has
+no usable heading. `L<a>-<b>` is an inclusive line range; `a` can
+equal `b`.
+
+Invalid forms:
+
+```
+src-1 L200-260         # missing #<anchor>
+src-1#intro            # missing L range
+```
+
+Prefer `source_ref_text` (verbatim raw quote) when anchor + lines
+aren't obvious. The CLI's compile-draft resolver computes the
+canonical form.
+
+## Glossary
+
+Workspace-derived from committed Entity + Action + Concept Nodes.
+Each entry:
+
+```
+<type>:<slug>
+  title: <human title>
+  aliases: [<alt>, ...]
+  tags: [...]
+  summary: <one-liner, optional>
+```
+
+Matching precedence for a raw name:
+
+1. Exact title (case-insensitive, NFC) → `existing`
+2. Alias → `existing` (record which alias matched)
+3. Fuzzy with high confidence (minor whitespace / punctuation / known
+   language variants) → `existing`
+4. Miss + ≥2 mentions OR authoritative signal → `new`
+5. Miss + single peripheral mention → noise; omit
+
+Conflict handling: most-specific wins (entity > concept > domain).
+If genuinely ambiguous, emit an `ambiguous` entry listing all hits.
+
+## Section status and deprecation
+
+Section status lives in the `<!-- ... -->` comment header, never in
+the blockquote. The blockquote is always `> **[${kind}]** <content>`;
+the parser rejects any file where the marker kind differs from the
+comment kind.
+
+Comment-header shape:
+
+```
+<!-- section-N <kind> <source-ref-or-dash> [status=<s>] [confidence=<c>] [refers_to_nodes=<a>,<b>] [valid_until=<v>] -->
+```
+
+- `status` attribute appears only when non-`active` (e.g. `deprecated`)
+- `confidence` attribute appears only when non-`confirmed`
+- Source-ref token is either a canonical `src-N#<anchor> L<a>-<b>` OR
+  a single `-` when cleared
+
+To deprecate: set source-ref token to `-` (when evidence is gone),
+insert `status=deprecated`. Never touch the blockquote.
+
+To re-anchor: replace the source-ref token with a new
+`src-M#<anchor> L<x>-<y>`; add `confidence=inferred` to record the
+downgrade.
+
+## Verify rule codes
+
+Close-time `context verify` / `context compile --close` emits these.
+Warnings don't block; errors flip exit to 2.
+
+| Code | Level | Meaning | Minimum fix |
+|---|---|---|---|
+| `dropped-source-reference` | error | Node `sources[]` lists a dropped source | Run `/context:drop` to complete cleanup; it uses `context mdrive node update` to remove the id |
+| `dangling-source-alias` | error | Section `src-N` past end of `sources[]` | Re-run `context compile --draft <slug>` with correct `source_ref` |
+| `sourceless-node` | warning | Node `sources[]` is empty after cleanup | Keep only if intentionally orphaned by `/context:drop`; otherwise re-anchor or add a source via `context mdrive node update` |
+| `body-ad-hoc-heading` | error | Node body has a heading the parser reads as a nested Node | Re-run `/context:compile` so the draft loop moves that content into Sections |
+| `invalid-section-mount` | error | Kind × Node type mismatch | Re-run `/context:compile`; or deprecate via `context mdrive section deprecate` |
+| `contains-cycle` / `refines-cycle` | error | Edge graph has a cycle | Re-align; structural issue |
+| `duplicate-slug` | error | Two Nodes share a slug | User picks winner; run `context mdrive node rename --from <old> --to <new>` |
+| `domain-same-file-child` | error | Domain md has inline child Nodes | Move child to standalone file; register in Domain's `## Contains` |
+| `invalid-frontmatter-schema` | error | Missing / malformed field | Fix frontmatter via `context mdrive node update` |
+| `heading-title-mismatch` | error | Root H1 differs from `title:` | Run `context mdrive workspace compact` |
+| `description-dominates` | warning (experimental) | >50% of Node's Sections are `description` | Re-draft with priority chain honoured |
+
+For structural errors (`contains-cycle`, `refines-cycle`,
+`duplicate-slug`, `invalid-node-type`), do NOT resolve from
+compile-close — the fix requires `/context:align` again.
+
+</reference>

package/plugin/skills/align-scan/references/user-question-contract.md

@@ -0,0 +1,155 @@
+# User Question Contract
+
+This reference defines how agents ask users for decisions during
+agent-driven workflows. It does not change the data model. The agent still
+maps every answer back to the canonical Node / Section / Edge schema.
+
+## Goal
+
+Ask the user for business intent, not storage mechanics. A good question lets
+the user answer from domain knowledge: "how should people find this later?",
+"does this relationship mean dependency or comparison?", "is this old content
+still valid?" The agent owns the translation into types, tags, sections,
+edges, slugs, and source references.
+
+## Hard Rules
+
+- Before the first decision question, give a two-sentence framing note: what
+  was found, what the align / compile / drop step is trying to decide, and
+  that implementation-only choices are handled automatically.
+- Do not expose model terms in user-facing question text or option labels:
+  `Node`, `Section`, `Concept`, `Entity`, `Domain`, `contains`,
+  `related_to`, `depends_on`, `source_ref`, `src-N`, `raw`, `frontmatter`,
+  `slug`, `mount matrix`, `re-anchor`.
+- Use "source document", "material", "topic", "detail", "standalone entry",
+  "relationship", "old claim", and "supporting evidence" in user-facing
+  prose.
+- Ask only when the answer changes business meaning, retrieval granularity,
+  source validity, or user-visible organization.
+- Do not ask when the choice is only about duplicate headings, navigation
+  blocks, storage shape, source-ref arithmetic, or safe defaults. Apply the
+  default and mention it in the summary.
+- Each multi-choice question has one short context line, one direct question,
+  2-4 concrete choices, and an "Other" escape hatch when the host does not
+  add one automatically.
+- Option descriptions describe user-visible consequences, not schema actions.
+- Question text follows the user's conversation language. CLI commands,
+  paths, ids, and machine tokens stay English.
+
+## Ask vs Decide Locally
+
+| Situation | Ask the user? | Default if not asking |
+|---|---:|---|
+| A repeated "Related links" / "References" / navigation block appears in several source documents | No, unless it contains a new business claim | Treat it as navigation and represent the useful relationship once |
+| A subtopic may need to be found directly later | Yes | If weak evidence, keep it under the parent topic |
+| Two products / systems / ideas might be alternatives, dependency, or merely co-mentioned | Yes | If unclear and no user answer, keep only the shared parent; no direct relationship |
+| A stale source conflicts with a newer active source | Yes | Keep both candidates and ask which claim is current |
+| A source is being dropped and a claim has no replacement evidence | No | Mark the claim as no longer supported |
+| A source is being dropped and another source appears to support the same claim, but the match is inferred | Usually no; show it in the impact plan | Move support to the surviving source and mark the confidence as inferred |
+| A proposed rename changes the user's vocabulary | Yes | Keep the original title / alias |
+| A section kind, edge type, source-ref, or file layout choice is required | No | Agent maps from the user's intent to the model |
+
+## Question Templates
+
+### Align: standalone topic or detail
+
+Context: "I found several Vmok subsections such as 'Core capabilities',
+'Scenarios', and 'Integration example'. The decision is whether people will
+search these directly later."
+
+Question: "How should these Vmok subsections be organized?"
+
+Choices:
+
+- "Keep them as parts of Vmok" — choose this if people normally read them
+  while looking at Vmok.
+- "Make them separate searchable entries" — choose this if people will ask
+  for "Vmok integration example" or "Vmok scenarios" directly.
+- "Keep only the strongest one separate" — choose this when only one
+  subsection deserves direct lookup.
+
+### Align: relationship meaning
+
+Context: "Vmok and Garfish appear near each other in the source documents, but
+the text does not clearly say how they relate."
+
+Question: "What is the business relationship between Vmok and Garfish?"
+
+Choices:
+
+- "Comparable alternatives" — people may compare them or choose one.
+- "Vmok is based on Garfish" — Vmok needs Garfish or builds on it.
+- "Same area, no direct relationship" — both belong under the same broader
+  topic, but there is no direct link.
+
+### Align: repeated references block
+
+Do not ask this when the block only lists links or nearby topics. Apply the
+default and summarize:
+
+"I found repeated related-links sections in three source documents. They look
+like navigation, so I will not copy them as new content; I will keep the useful
+relationships once in the structure."
+
+Ask only if the block contains real prose:
+
+Question: "Do these 'related content' sections contain business information we
+must preserve, or are they only navigation?"
+
+Choices:
+
+- "Only navigation" — use them to understand relationships, not as content.
+- "Preserve the explanation" — keep the useful prose in the relevant topic.
+- "Not sure" — keep a short summary for now.
+
+### Align: old or conflicting source
+
+Context: "One source describes the old access path, while a newer source
+describes a different path."
+
+Question: "Which version should readers trust now?"
+
+Choices:
+
+- "Use the newer version" — old wording stays only as historical context.
+- "Keep both with dates" — both are valid for different periods or cases.
+- "Use the old version" — the newer source is not authoritative for this
+  workspace.
+
+### Compile plan: replacing existing content
+
+Context: "The new material changes a statement that already exists in the
+knowledge base."
+
+Question: "How should the existing statement be handled?"
+
+Choices:
+
+- "Replace it" — readers should see only the newer statement as current.
+- "Keep both with context" — both statements matter for different cases.
+- "Do not change it" — the new material should not override the current
+  knowledge.
+
+### Drop: source removal impact
+
+Context: "Dropping this source affects 2 topics and 4 pieces of knowledge. Some
+claims can still be supported by other source documents; others cannot."
+
+Question: "Proceed with this cleanup?"
+
+Choices:
+
+- "Proceed" — unsupported claims are marked old, and supported claims move to
+  surviving evidence.
+- "Stop" — no files are changed.
+- "Show details first" — list the affected topics before deciding.
+
+## Bad to Good
+
+| Bad | Good |
+|---|---|
+| "Keep as Section or promote to Concept?" | "Will people search this as its own topic, or only read it inside the parent topic?" |
+| "Choose related_to / depends_on / no edge." | "Are these alternatives, does one build on the other, or are they only in the same area?" |
+| "3 raw files all have Relations blocks. Drop or keep as Section?" | "I found repeated related-links sections. They look like navigation, so I will treat them as structure and not copy them as content." |
+| "Re-anchor section-3 from src-1 to src-2?" | "Another source still supports this claim, so I will keep it but mark the support as inferred." |
+| "Rename slug vmok-core-capability?" | "Should readers see this as 'Vmok core capabilities', or do you prefer another title?" |

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

@@ -0,0 +1,122 @@
+---
+name: compile-close
+description: >
+  Final skill of `/context:compile`. Runs after every `compile-draft`
+  iteration. Triggers `context compile --close`, which in one invocation
+  verifies the workspace, refreshes locator-only evidence, compacts
+  knowledge, rebuilds `knowledge/_index.md`, 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 edits `knowledge/`.
+  Activates once all draft actions are applied and before user-visible
+  success is declared.
+tools:
+  - Read
+  - Bash
+---
+
+# 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 write or edit anything under `knowledge/`.
+
+## TL;DR — Non-negotiables
+
+- Script-driven. `context compile --close` verifies first, then performs close writes, rebuilds section fingerprints + incremental cache, and archives compile scratch files. Read the command's stdout + exit code; that's the close's full output.
+- **Agent NEVER edits `knowledge/` from compile-close.** The CLI is the sole writer under `knowledge/` — `_index.md`, `changelog.md`, every `<type>/<slug>.md`. 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; compile-close does not patch)
+  - Structural issues (`contains-cycle`, `refines-cycle`, `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, and archive path when printed; then stop.
+- Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not open the affected Node md.
+- Never re-run `context compile --draft` from close to paper over verify failures. Draft failures belong in the draft loop.
+- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `compile --close` before the append. 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 `compile.*` scratch files under the workspace `output/archive/` directory, copies the consumed `align.md` + `bind.yaml`, and rebuilds the user-level incremental cache. The current root `align.md` + `bind.yaml` remain available for recompile/status. 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. **Workspace verify** — runs the full rule set before close writes. Any error flips exit to 2 and no success stamp is written.
+2. **Locator refresh** — if evidence moved but block hashes are unchanged, updates only section locators.
+3. **Workspace compact** — re-renders every `knowledge/<type>/*.md` canonically (Section order, frontmatter field order, `## Contains` list ordering, heading depth).
+4. **Rebuild `_index.md`** — regenerates the index from the current workspace state; previous content overwritten.
+5. **Append changelog** — appends one compile list item to `knowledge/changelog.md`; existing entries preserved.
+6. **Rebuild incremental cache** — rebuilds section fingerprints and cache indexes from workspace truth sources.
+7. **Archive scratch files** — moves `compile.*` context/draft payloads under `output/archive/` and copies the align/bind inputs used for this compile.
+
+## 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. Point at `/context:status` or `context cache status` when the warning is incremental-cache-related. Stop. |
+| 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 Node md. |
+| 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. |
+
+Compile-close never edits `knowledge/` on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. See the [Verify rule codes](${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/data-model.md#verify-rule-codes) lookup for the error→command mapping.
+
+## Changelog entry shape
+
+`context compile --close` appends one markdown list item per run to
+`knowledge/changelog.md` 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
+
+Read 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 Edit any file under `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).
+- 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 compile-close itself.
+
+### Step 4 — Report
+
+Summarise in the user's language:
+
+- Nodes touched and counts per op (add / update / supersede / deprecate / skip / locator-only).
+- `_index.md` rebuilt / updated; `changelog.md` appended at `<timestamp>`.
+- Incremental close counts printed by the CLI: `recompiled`, `locator_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 — Self-verify
+
+- [ ] `context compile --close` ran exactly once per close call — if not, **Step 1**.
+- [ ] If exit 2, every error is surfaced to the user with a re-entry command (compile / align / drop); no silent ignores — **Step 3**.
+- [ ] No agent-hand edits anywhere under `knowledge/` — if any, revert; compile-close is read-only on `knowledge/`.
+- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR`; CLI-owned archival under `output/archive/` is allowed.
+
+</procedures>