@c4a/context-cli 0.5.29-alpha.2 → 0.5.29-beta.16

package/plugin/skills/align-scan/SKILL.md

@@ -1,161 +0,0 @@
----
-name: align-scan
-description: >
-  First skill of `/context:align`. Reads `WORKSPACE_DIR/output/align.scan.yaml` + the
-  workspace glossary, inspects the raw outlines/full raw evidence, classifies
-  raw material into existing / new / ambiguous / orphan, and writes a
-  structured JSON decisions file for align-propose to consume. The CLI only
-  provides weak candidate seeds and deterministic context; semantic
-  classification is the agent's job. Activates when `/context:align` starts,
-  or when an agent has raw material ready and needs a first-cut candidate list before the
-  structural proposal step.
-tools:
-  - Read
-  - Bash
----
-
-# align-scan — classify raw material
-
-Classify raw material in `WORKSPACE_DIR/output/align.scan.yaml` against the
-workspace glossary. The scan file is a context package, not a final classifier:
-`new_candidates[]` are weak seeds and `raw_outlines[]` is the main reading map.
-Output one JSON payload; no markdown.
-
-`WORKSPACE_DIR` is provided by the caller from `context workspace locate --format json` (`ctxDir`). It is `.context/` in embedded layout and the repository root in root layout.
-
-## TL;DR — Non-negotiables
-
-- Output is JSON only; the CLI owns every rendered markdown file.
-- Input is `WORKSPACE_DIR/output/align.scan.yaml` produced by `context align --scan`; scan v2 is structural-first and deliberately avoids semantic type guesses.
-- Read `raw_outlines[]` for every scanned raw file. When the outline or previews are insufficient, read the full raw file with `context workspace read <path> --format text`.
-- Treat `scan.new_candidates[]` as weak seeds only. `semantic_type: "unresolved"` / `classification_required: true` means the CLI intentionally did not classify it.
-- `type` is one of `domain / entity / action / concept` (see [Node types](references/data-model.md#node-types)); nothing else.
-- Every `entity` candidate carries ≥1 tag from group A or B (see [Entity tag groups](references/data-model.md#entity-tag-groups)).
-- Every candidate has ≥1 `mention` with `{file, line, quote}` (quote ≤180 chars); no fabrication.
-- Glossary hits become `existing`, not new candidates (see [Glossary](references/data-model.md#glossary)).
-- Relational titles ("X affects Y", "Y-side of X", "X migration") are not Entities — re-route via [False-Entity smell](references/data-model.md#false-entity-smell).
-- Raw file paths in the scan are relative to `WORKSPACE_DIR`; read raw evidence only with `context workspace read <path>`. Never use Read / Glob / Grep against workspace files.
-- Save the decisions file only with `context align --save-scan-decisions -`; do not touch `knowledge/`, raw files, or cache files.
-- Output language: user-facing prose matches the user's conversation language; JSON keys / slug / tag values stay English.
-
-<reference>
-
-## Output schema (agent decisions)
-
-This is the JSON you write with `context align --save-scan-decisions -`.
-It is not the raw CLI scan schema. In `output/align.scan.yaml`,
-`scan.new_candidates[]` may omit `suggested_type` / `suggested_tags`;
-the agent must fill them after reading raw evidence. When a candidate has
-`semantic_type: "unresolved"` and `classification_required: true`, that is the
-expected scan-v2 shape, not an error.
-
-```jsonc
-{
-  "scan_version": 2,
-  "workspace": "<workspace-name from scan>",
-  "existing_nodes": [
-    { "slug": "...", "type": "entity|action|concept|domain",
-      "confirmed_mentions": [ { "file": "...", "line": 12, "quote": "..." } ] }
-  ],
-  "new_candidates": [
-    { "name": "<human title>", "suggested_slug": "<kebab-case>",
-      "suggested_type": "entity|action|concept|domain",
-      "suggested_tags": ["lib"],
-      "confidence": "high|medium|low",
-      "mentions": [ { "file": "...", "line": 45, "quote": "..." } ],
-      "suggested_parent": "<slug>",
-      "suggested_realizes": "<slug>",
-      "notes": "<optional>"
-    }
-  ],
-  "ambiguous": [
-    { "phrase": "...",
-      "candidates": [
-        { "kind": "existing", "slug": "..." },
-        { "kind": "new", "name": "...", "suggested_type": "...", "suggested_tags": [] }
-      ],
-      "mentions": [ ... ],
-      "reroute_as": "<optional: Section on target-slug>"
-    }
-  ],
-  "orphans": [ { "slug": "...", "reason": "...", "mentions": [ ... ] } ],
-  "decisions": { "notes": "<free-form rationale>" }
-}
-```
-
-## Confidence calibration
-
-| `confidence` | When |
-|---|---|
-| `high` | Multiple direct mentions + clear integration signal (authoritative "X is our X library" prose) |
-| `medium` | ≥2 mentions OR a single authoritative mention (section heading) |
-| `low` | Single peripheral mention; prefer `ambiguous` over a low-confidence `new` |
-
-</reference>
-
-<procedures>
-
-### Step 1 — Read the scan
-
-Read `output/align.scan.yaml` with `context workspace read output/align.scan.yaml --format text`
-and verify `scan_version: 2` (legacy `scan_version: 1` is readable). If missing, stop and tell the user to run `context align --scan` first.
-Skim `glossary[]` to remember the existing slug + alias set.
-For `scan_version: 2`, first inspect `incremental`:
-
-- `structure_changed[]` and `new_sources[]` are the only reasons to classify structure.
-- `content_changed_only[]` means compile work, not align work; do not create candidates from those sources.
-- `skipped_sources[]` are unchanged; do not classify them.
-- `unknown_sources[]` cannot be treated as unchanged. Return control to the caller with the reason unless the caller chose a full scan.
-
-When source context is needed, run `context workspace read <path> --format text` where
-`<path>` comes from `raw_files_scanned[]` or `mentions[].file`; for example,
-`raw/local/2026-04-25-vmok.md`. Do not attempt to read only `2026-04-25-vmok.md`
-from the current directory, and do not use the Read tool against `WORKSPACE_DIR`.
-
-Then inspect every `raw_outlines[]` entry:
-
-- `headings[]` shows the full H1-H6 shape so H3/H4 content is not ignored.
-- `relation_lines[]` shows protocol-like navigation hints. Treat them as structure, not content claims, unless the surrounding raw prose adds a business claim.
-- `relation_hints[]` is the structured version of those navigation lines (`parent` / `children` / `related` / `relations` plus link targets). Use it to preserve explicit raw links, but do not infer semantic type from it.
-- `evidence_blocks[]` gives short previews for all parsed blocks. If a candidate decision depends on text outside the preview, read the full raw file through `context workspace read`.
-
-### Step 2 — Promote `existing_nodes`
-
-Copy every `scan.existing_nodes[]` entry into `output.existing_nodes[]`
-with its `confirmed_mentions`. If any raw quote contradicts the
-glossary summary (sunset / replaced), also emit an `orphan` entry;
-never silently drop.
-
-### Step 3 — Classify raw material
-
-Use `scan.new_candidates[]` as a seed list, then check `raw_outlines[]` and full raw evidence before deciding. A new Node can come from a seed, a heading visible only in `raw_outlines[]`, or a repeated/raw-supported concept discovered while reading the full source. Conversely, a seed can be demoted to a Section or ignored as navigation.
-
-For each potential topic:
-
-1. Match against glossary per [Glossary](references/data-model.md#glossary). A hit moves the item to `existing_nodes`.
-2. Pick `suggested_type` per [Node types](references/data-model.md#node-types). Use [Entity vs Concept test](references/data-model.md#entity-vs-concept-test) when torn between entity and concept.
-3. For `entity`, pick tags per [Entity tag groups](references/data-model.md#entity-tag-groups). If neither group has a legal tag, route via [False-Entity smell](references/data-model.md#false-entity-smell) into `ambiguous`; do not force a tag.
-4. Map any deprecated tag from the raw to its canonical form per [Deprecated tags](references/data-model.md#deprecated-tags).
-5. Assign `confidence` per [Confidence calibration](#confidence-calibration).
-6. Record demoted headings / seeds in `decisions.notes` so align-propose can explain why they became Sections or navigation instead of Nodes.
-
-### Step 4 — Carry ambiguities and orphans
-
-For each `scan.ambiguous[]`, fill in a best-guess `suggested_type + suggested_tags` on the `new`-side candidates so align-propose can render them. Do not resolve ambiguities here — the user owns that decision. Copy `scan.orphans[]` through; add discoveries from Step 2.
-
-### Step 5 — Save the JSON
-
-Pass one UTF-8 JSON document to `context align --save-scan-decisions -`.
-No markdown wrapper, no leading prose.
-
-### Step 6 — Self-verify
-
-- [ ] Every `new_candidates[]` entry has ≥1 mention — if not, back to **Step 3**.
-- [ ] Every `entity` `new_candidates[]` has an A or B tag — if not, **Step 3** (re-route via False-Entity smell).
-- [ ] Every `ambiguous[]` entry has a candidate that is either `existing` OR a fully-typed `new` — if not, **Step 4**.
-- [ ] Output is pure JSON — if any markdown leaked, **Step 5**.
-- [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR` — if any, restart with `context workspace` commands.
-
-Return control to the caller; do not invoke subsequent skills yourself.
-
-</procedures>

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

@@ -1,343 +0,0 @@
-# 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> --plan` 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

@@ -1,159 +0,0 @@
-# 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 explicitly supports the same claim | No | Move support to the surviving source and mark the confidence based on evidence strength |
-| A source is being dropped and another source only appears to support the claim by inference | Yes | Do not silently re-anchor; ask the user or mark the claim as unsupported |
-| 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 payment runtime subsections such as 'Isolation
-model', 'Retry policy', and 'Integration example'. The decision is whether
-people will search these directly later."
-
-Question: "How should these payment runtime subsections be organized?"
-
-Choices:
-
-- "Keep them as parts of payment runtime" — choose this if people normally
-  read them while looking at payment runtime.
-- "Make them separate searchable entries" — choose this if people will ask
-  for "payment retry policy" or "payment runtime integration example" directly.
-- "Keep only the strongest one separate" — choose this when only one
-  subsection deserves direct lookup.
-
-### Align: relationship meaning
-
-Context: "Portal Shell and Plugin Runtime 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 Portal Shell and Plugin
-Runtime?"
-
-Choices:
-
-- "Comparable alternatives" — people may compare them or choose one.
-- "Portal Shell is based on Plugin Runtime" — Portal Shell needs Plugin
-  Runtime 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 only raw-backed prose in the relevant topic and flag the
-  uncertainty in the summary.
-
-### 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 explicitly supports this claim, so I will keep it; if the support is only inferred, I will ask before changing it." |
-| "Rename slug payment-retry-policy?" | "Should readers see this as 'payment retry policy', or do you prefer another title?" |