@antoneeo/kb-agentic-skill 1.0.0

package/skills/kb-agentic-skill/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: kb-agentic
+description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs and knowledge management.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+
+# KB Agentic
+
+**Why this skill exists:** to prevent *knowledge degradation and myopia* — acting from partial understanding, where new information contradicts un-indexed notes and hard-won knowledge evaporates between sessions. Triage, the Vision Gate, signal distillation, the documentation lifecycle, and operative guide routers are all one defense against that.
+
+This skill guides knowledge management and documentation with a Document-First process proportional to risk. It works fully even without devPNT. When devPNT is available and configured for the current project, the skill works in symbiosis with its governance: M-VISION, Master Plan, Action Plan and versioned artifacts become the authoritative frame for milestones and knowledge nodes.
+
+Support files in the skill directory:
+- `templates.md`: templates for Vision, Knowledge ANALYSIS, Research SPIKE, SOP GUIDE, audit plan, and handoff.
+- `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization. Run at L3 before drafting.
+- `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
+- `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check.
+- `distillation.md`: from a source to claim rows — intake (content-addressed originals, stored canonical extraction, every provenance a real file), the claim table, extraction discipline, signal rules (symbiosis with `distill`).
+- `reconciliation.md`: what happens when two claims meet — five outcomes, detect-and-hold (the machine never decides), rulings with mandatory `basis:`, the claim state machine, the batched escalation form.
+- `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
+- `dispatch.md`: opt-in subagent execution of an approved plan.
+- `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
+- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
+- `ENFORCEMENT.md`: optional setup for CI and hooks.
+
+Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
+
+## Knowledge Values
+
+- **Understand before writing/updating:** do not modify or create knowledge documents without checking root cause, user constraints, and existing notes — trust the primary sources and existing guides, not memory.
+- **Apply DRY and Single Source of Truth:** do not duplicate knowledge across files; extend existing notes (`ANALYSIS_[topic].md` or `GUIDE_[topic].md`).
+- **Signal & Distillation:** eliminate fluff, filler, and speculative statements; keep deterministic facts, constraints, decisions, and clear SOP steps (symbiosis with `distill`).
+- **Lifecycle & Freshness:** mark superseded knowledge (`status: SUPERSEDED` or `DEPRECATED`) so outdated information does not cause hallucination.
+- **Protect the Vision & User Style:** align all knowledge work with user strategic goals, operational preferences, and expected outcomes.
+- **Map-First Navigation:** rely on `ai_docs/README.md`, `INDEX.md`, and `reference/INDEX.md` router for targeted retrieval before creating new documents.
+
+## Rule Zero: Triage
+
+Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
+
+**Declare the level WITH the router verdict** (one line, for L2, L3 and Spike — L1 declares the level alone): the result of the guide-router lookup described under `## Operative Guides`, i.e. `Level: L2 · router: no match` or `Level: L3 · router: GUIDE_release_sop.md → read`. Name the guide you matched, or `no match`.
+
+| Level | Criteria | Required process |
+|---|---|---|
+| **L1 - Quick Fact / Snippet** | Small update to an existing note, typo fix in docs, quick preference update (at most 1-2 files). | Implement edit directly in existing note. No new documents. |
+| **L2 - Local Note / SOP Update** | Specific SOP update, local research note, or small document addition (at most 1-2 files). Low risk. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
+| **L3 - Major Knowledge Unit / Corpus** | Ingesting large document sets, complex multi-topic research, multi-part guide creation, or restructuring the KB. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
+| **Spike - Exploration** | Time-boxed exploratory research or draft without merging into official KB. | Outcome in `ai_docs/solutions/SPIKE_[topic].md`. |
+
+Cross-cutting rules:
+- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `mkt-agentic-sdlc`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
+- Personal data, credentials, security-sensitive processes, authN/authZ specs are high-risk: never L1.
+- **Escalation triggers — ANY of these makes it L3, whatever the file count:** the change touches the topic hierarchy (`parents:`, a `GENERALIZES` verdict, a re-parent); it touches more than one node's frontmatter; it creates or supersedes a node other nodes reference. Re-shaping the graph is a unit of change, never a side effect of placing one claim.
+- Adding one claim row to an existing topic is L1: the `id` may be left empty (the validator fills it — `claim-id --fill`), and no check errors on a hand-written row.
+- If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
+- When in doubt, pick the higher level.
+- **No useless questions.** Every question to the practitioner passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. Claim-conflict escalations additionally carry their own mandated form and are batched at run end (`reconciliation.md` §4).
+
+## Write Triggers
+
+Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
+
+| Document | Write trigger | Phase |
+|---|---|---|
+| `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
+| `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
+| `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
+| `audit/handoff.md` (workstream registry) | One row per OPEN workstream (topic, level, status, since, next step) — refresh at every L3 closure and session end. ≤ 20 lines. | 5 / session end |
+| `audit/HANDOFF_[topic].md` | Session ends with that topic unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 4 / 5 / session end |
+| `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
+| `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal accepted by user. | 4 / 5 |
+| `reference/GUIDE_[topic].md` (`source_kind: code`/`domain`) | Recognized high-complexity domain/concept with no CURRENT guide $\rightarrow$ duty to write autonomously. | 4 / 5 |
+| `audit/reviews/REVIEW_LOG.md` | Every completed review — recorded in log. | 3 / 5 |
+| ADR / Decision Log — `architecture/` or devPNT DB | A strategic decision was taken (pattern, policy, structural change): record before DONE. | 5 |
+| `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the knowledge catalog actually changed. | 1 / 5 |
+| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
+| `topics/<slug>.md` | A placement verdict creates it (MISSING/INADEQUATE-child, `taxonomy.md`); reconciliation updates its claim rows. One node per topic — a similar-but-distinct concept is a sibling with `related:` + a written distinction, never a merge and never a duplicate. Merged/renamed nodes become tombstones (`status: SUPERSEDED` + `redirect_to:`), never deleted. | 4 |
+| `corpus/given/*` + sidecar | A source arrives: verbatim copy, content-addressed, sidecar with digest/date/`supersedes:`; non-text originals also get their stored canonical extraction (`distillation.md` §1). Never edited after ingest — the digest check is what enforces it. | 4 |
+| `corpus/notes/*` | Something is said (`origin: elicited`), synthesised (`derived_from:`), or ruled (`basis:`). A note with none of the three is refused by the validator. | 4 / 5 |
+| `INDEX.md`, `reference/INDEX.md`, `topics/INDEX.md`, `corpus/INDEX.md` | Regenerated by `sdlc_check.py index` at closure — never by hand; `validate` fails on a hand-edited one. | 5 |
+
+## Operating Modes
+
+### Full Standalone
+Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
+- Source of truth: `ai_docs/` (`vision/`, `solutions/`, `reference/`, `audit/`, `strategic/`).
+
+### Hybrid in symbiosis with devPNT
+Use this mode when `devpnt_*` tools are available and point at the current project.
+- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
+- Local `ai_docs/` serves as readable context, Standalone fallback, local handoff, or shadow copy.
+
+## L3 Workflow
+
+### 1. Audit and Alignment
+- Read `ai_docs/audit/handoff.md` (workstream registry) to see active topics.
+- Read `ai_docs/README.md`, `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md` (the guide router) before exploring notes. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do.
+- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/` docs, `strategic/` docs, and `audit/audit_plan.md`, then run `sdlc_check.py index`.
+
+### 2. Vision Gate
+- Read `project_vision.md`, `roadmap.md`, `principles.md` (or devPNT `M-VISION`).
+- Verify request aligns with expected benefits, user goals, and success signals.
+
+### 3. Request Analysis & Taxonomy Pass
+- Run spec elicitation round (`elicitation.md`) before drafting analysis.
+- Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
+- Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
+- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
+
+### 4. Knowledge Processing & Distillation
+- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
+- Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
+- Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
+- **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
+- Handle conflicting or outdated information via **Reconciliation** (`reconciliation.md`). Mark obsolete files `status: SUPERSEDED`.
+
+### 5. Closure & Indexing
+- Run verification checks (`sdlc_check.py check --root <project_root>`).
+- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
+- Update `audit/handoff.md`.
+- Regenerate manifests: `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`.
+- Mark output clean and complete.
+
+## Operative Guides & Router
+Guides are consulted, created, and distilled per `guides.md`.
+- **Consult (before acting)**: check `ai_docs/reference/INDEX.md` — the guide router — and declare the verdict with the triage level.
+- **Propose proactively**: when the user hands over indications that will govern future work, propose distilling them into a guide. A proposal, never a silent write, and never from model knowledge — a guide's whole value is that every claim traces to what the user actually provided.
+- Distill from user instructions into `ai_docs/reference/GUIDE_[topic].md`.
+
+## Mechanical Enforcement
+- `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
+- `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).
+- `scripts/sdlc_check.py check`: checks dirty closures and missing indexes.

package/skills/kb-agentic-skill/dispatch.md

@@ -0,0 +1,87 @@
+# Subagent Execution Discipline
+
+Opt-in orchestration for L3 work with an approved design: the orchestrator
+drives a `PLAN_[feature].md` through subagents instead of implementing every
+task in the same session. Default stays same-session; this is an escalation,
+never a requirement.
+
+## Trigger
+
+Only for L3 (an approved E-TDD in Hybrid, or an ANALYSIS Action Plan in
+Standalone). Never for L1/L2 — the plan/ledger machinery is overhead a small
+change does not need. The plan is always `derived-from` the accepted design:
+it is never independently authored, exactly like an E-TDD is never authored
+without an E-ISP.
+
+## The loop
+
+1. `sdlc_check.py plan validate PLAN_[feature].md` — zero-execution schema +
+   confinement + ledger cross-check. Non-zero exit = **no dispatch**. This is
+   the hard gate: "no valid plan, no dispatch."
+2. For each task, in plan order:
+   - Read the task's status from the sidecar ledger
+     (`PLAN_[feature].ledger.json`). `status: done` (exact sentinel) → skip,
+     never re-dispatch. Anything else (pending, failed, missing, or a
+     corrupt-but-parseable entry) → treat as pending and dispatch.
+   - `sdlc_check.py plan brief PLAN_[feature].md --task <id>` — prints the
+     task block, the `produces` of prior-order tasks (interfaces), and
+     `guides` pointers (paths, never pasted content) to stdout.
+   - Spawn the subagent with that brief as its entire context window.
+   - Run `task.verify` out of band (the orchestrator executes it — the
+     validator only ever prints it, never runs it) plus the one-shot review
+     below.
+   - Write `{status, verify_result, timestamp}` back to the ledger. The
+     validator never writes the ledger — single-writer, orchestrator-owned.
+
+**Guide consumption under dispatch.** Selecting each task's `guides` field IS the
+consult trigger (`guides.md` §0) applied at plan-authoring time: the orchestrator
+runs the router lookup (project router `ai_docs/reference/INDEX.md` + the agent-KB
+router) when populating `guides`. A dispatched context-free subagent does **NOT**
+run its own router consult — it reads the guide pointers handed to it in the
+brief. The router verdict (Rule Zero) is therefore declared ONCE, by the
+orchestrator, when it authors the plan; a dispatched subagent does not declare
+one. (Proactive guide-creation stays at closure — the same broad final pass
+below — so it needs no separate dispatch hook.)
+
+## Model tiers (client-relative, no provider names)
+
+- Default dispatch: **economy** implementer tier.
+- After **two** consecutive `verify_result: fail` on the same task: escalate
+  to the **deep** tier for the retry (ADR 2026-07-02). Do not escalate on the
+  first failure — a single fail is often a brief or environment issue, not a
+  capability gap.
+
+## Review slots — one-shot, not iterative
+
+Exactly three review touches per task, never a loop:
+
+1. Inline self-review by the implementer subagent before it reports done
+   (the standard critical-review pass, not a separate call).
+2. One reviewer pass per task (Hybrid: reuse the devPNT code-review gate;
+   Standalone: the `review.md` discipline).
+3. One broad final pass over the whole plan at closure, after all tasks are
+   DONE — catches cross-task drift a per-task review cannot see.
+
+If a review FAILs, fix and re-run `verify` — that is a normal loop iteration
+via the ledger's fail path, not an extra review slot.
+
+## Ledger protocol summary
+
+Read → skip-if-done → dispatch-if-pending → write. The ledger is the only
+memory the loop needs across sessions or context compaction: a resumed
+orchestrator re-reads it and picks up exactly where it left off, never
+re-running a DONE task.
+
+## Degradation
+
+No subagent-spawning tool available → the orchestrator runs each task in the
+same session, against the same plan and ledger, with the same one-shot review
+slots. No capability is lost, only the parallelism/isolation subagents would
+have added.
+
+## Hybrid note
+
+The plan's `derived-from` points at the accepted E-TDD document key. Per-task
+review reuses the devPNT independent reviewers (§4.6 code review gate) rather
+than restating review doctrine — see `review.md` for the single definition
+both modes share.

package/skills/kb-agentic-skill/distillation.md

@@ -0,0 +1,79 @@
+# Distillation — from a source to claim rows
+
+**For whom**: the agent ingesting a source into the corpus.
+**Answers**: "what is a claim, how does a source become rows, and where does every kind
+of knowledge get its file".
+**Does not answer**: where a claim's concept lives (above — `taxonomy.md`) or what
+happens when it disagrees with an existing one (`reconciliation.md`).
+
+## 1. Intake — everything becomes a file first
+
+Ingest **never touches the graph**. First the source enters the corpus; the graph is fed
+from the corpus, so everything is re-derivable when the rules improve.
+
+| What arrives | Where it lands |
+|---|---|
+| a file from the practitioner | `corpus/given/<name>-<hash8>.<ext>` — verbatim, **content-addressed with a raw-byte sha256**; a newer version is a new file whose sidecar says `supersedes: <old>` — never an overwrite |
+| a non-text original (PDF, docx, xlsx) | additionally, its **canonical extraction**: `corpus/given/<name>-<hash8>.txt`, pages separated by form-feed; extractor id, version and normalization recorded in the sidecar. Offsets address THIS file — stored bytes, not a runtime step |
+| something the practitioner says | a transcription in `corpus/notes/`, frontmatter `origin: elicited`, dated |
+| an agent synthesis | a note in `corpus/notes/` with `derived_from:` listing its sources — a note with neither `origin:` nor `derived_from:` nor `basis:` is **model knowledge disguised as a source**, and the validator refuses it |
+| a practitioner ruling | a note with `basis:` (`reconciliation.md`) |
+
+Every sidecar (`<original>.meta.md`) carries: the digest, the date, provenance, and
+`supersedes:` when it replaces an earlier version. `corpus/INDEX.md` is generated.
+
+## 2. The claim — one falsifiable assertion
+
+The unit of knowledge is the **claim**, not the document. "Doc A and doc B disagree" is
+not actionable; "A says delivery Q1, B says Q3" is. A claim is a sentence that can be
+true or false: "the system is robust" is not one; "the retry runs 3 times with backoff"
+is.
+
+Claims live in the owning topic's `## Claims` table (`templates.md` has the template):
+
+| id | claim | valid | qty | about | source | prov | state |
+|---|---|---|---|---|---|---|---|
+
+- **id** — leave empty when writing by hand; `sdlc_check.py claim-id --fill <file>`
+  computes it (`sha256(path#locator#qty)`, text excluded — a paraphrase must not mint a
+  new identity). An empty id is a `[note]`, never an error.
+- **valid** — `-`, `from X`, `until X`, `from X until Y`, `if <condition>`. Half-open:
+  `until 2026-03-01` and `from 2026-03-01` do NOT overlap. A time-bounded fact is not a
+  conflict with its successor — write the scope, or reconciliation will manufacture one.
+- **qty** — `-` or `<value> <unit> <kind>`, kind ∈ effort/cost/duration/count. Effort in
+  person-days (8h=1d, 1w=5d, 1mo=21d), duration in calendar days, cost within ONE
+  currency. A figure without a unit cannot be summed, compared, or even classified as
+  agreement.
+- **about** — `-` or `<predicate> -> <slug>` for a claim about a relationship
+  ("depends-on -> phase-1"). Stored once, under the subject; the index computes the
+  reverse direction.
+- **source** — `<path>#<locator>`; corroborating sources append with `;`. Locators:
+  `p=<n>@<start>-<end>` (character offsets into page n of the stored extraction),
+  `L<a>-<b>` (line files), `Sheet<s>!<cell>`. The span must exist — the validator opens
+  the file and checks.
+- **prov** — `GIVEN | ELICITED | DERIVED | RULING`. Information for whoever resolves a
+  conflict; never a rank.
+- **state** — `OK`, `CONTESTED <ids>`, `SUPERSEDED <id>` (`reconciliation.md` owns the
+  transitions).
+
+## 3. Extraction discipline
+
+Read the stored extraction (not the original) and emit one row per assertion, each with
+the offset span it came from. The extractor **invents nothing**: no labels, no
+summaries-as-claims, no filling of gaps from model knowledge. What the source does not
+assert does not become a row — it may become a `gaps:` entry on the topic.
+
+Extraction is read-only on the corpus and blind to the graph: rows go to placement
+(`taxonomy.md`) afterwards. Ingesting a document set is **L3 by Rule Zero**; the
+ingestion plan derives from the ANALYSIS Action Plan, one task per source, each task's
+`verify` = "claim rows parse; every source resolves under the docs root". Serial in v1:
+correctness first.
+
+## 4. Signal discipline (what "distillation" still means)
+
+- Contract-first for any prose you write around the rows (reader, action, payload).
+- Zero speculation: unverified information is marked `[unverified]` or omitted — never
+  written as a claim.
+- No noise: no filler, no restated boilerplate; the claim table IS the signal.
+- Lifecycle: every document carries `status:` frontmatter; superseding knowledge marks
+  the old file `SUPERSEDED` (documents) or the old row (claims).

package/skills/kb-agentic-skill/elicitation.md

@@ -0,0 +1,131 @@
+# Spec Elicitation
+
+`## The question discipline` below governs EVERY question to the practitioner —
+any phase, any level, inside or outside the round. The rest of the file is the
+spec elicitation round: it applies when an L3 request enters phase 3 (Request
+Analysis), BEFORE drafting the ANALYSIS document (Standalone) or the D-UC/E-ISP
+(Hybrid).
+
+Skip path: if the spec is already complete — an approved Vision or explicit
+user requirements already answer goal, scope, and constraints — skip the
+round and add a one-line note in the analysis stating why it was skipped.
+Do not run the round as a formality when the answers are already on record.
+
+Unattended path: when the user is not reachable (a scheduled or autonomous run,
+and a bootstrap Vision is `DRAFT` by mandate, so the skip path above cannot
+apply on a project's first L3), do not stall and do not invent consensus. Write
+the six answers as **declared assumptions** in `## Objective`, mark the ANALYSIS
+`BLOCKED on the user`, and stop before implementation. An assumption on the
+record is reviewable; a guess folded silently into a design is not.
+
+## The question discipline
+
+A question to the practitioner spends their attention and stalls the work; the
+round below is the only place the process *plans* that cost. Everywhere, a
+question is legal only when BOTH hold:
+
+1. **Searched first, and the search is named — with its result.** The answer is
+   not on record and not derivable from the corpus, the topic graph, `ai_docs/`,
+   the Vision or the conversation — and the question states the terms, tools and
+   areas you searched **and what they returned**. Same standard as a router
+   verdict or a taxonomy-pass MISSING, and it carries their floors: a search
+   whose scope does not cover the question is not a search; a hit you did not
+   open narrows nothing; and **never fake the search** — "I looked and found
+   nothing" that names no terms and no areas is a search not run. A question the
+   corpus can answer is a search outsourced to the practitioner.
+2. **It names what is blocked.** The question states the specific decision or
+   fact that cannot be resolved without the reply — what you will do differently
+   depending on the answer. If nothing downstream changes, there is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is this OK?". The process
+  authorizes proceeding; if a real risk motivates the ask, name the risk and the
+  fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the practitioner to pick among options that
+  are equivalent in their effect on the benefit and already decided by the
+  project's conventions. Cheapness to undo is NOT the test.
+- **Re-asking the record** — goal, scope or constraints that an APPROVED
+  Vision, an earlier reply, or the request itself already states; or a fact a
+  claim row already carries with its source.
+
+What questions are FOR — what the practitioner uniquely owns: the benefit,
+priorities between conflicting goods, non-goals, acceptance, the approvals
+doctrine reserves to them, and **rulings on contested claims — where their
+answer counts only as a fact they know (`basis:`), never as a preference**
+(`reconciliation.md` §2). Facts about intent come from the practitioner; facts
+about the documents come from the corpus. **Precedence:** a choice the
+practitioner uniquely owns is never preference-fishing; the list above reaches
+choices that are *not* theirs.
+
+**Default non-blocking.** An unknown on which no fork of the work depends:
+write it as a **declared assumption** in the artifact it touches, proceed, and
+present the open points **batched**, answered by exception. This branch carries
+the SAME evidence duty as a question: each assumption states **what it is taken
+from** and **the alternative it excludes**, and every declared assumption
+reaches the batch — an assumption nobody is shown is a silent decision. This is
+the same structure as the claim ledger's own escalation rule — keep BOTH sides
+with their sources and surface them, never silently pick one — and it is this
+branch, not the blocking one, where that rule structurally lives: an open
+`CONTESTED` set never stops an ingest (`reconciliation.md` §4).
+
+**Blocking is reserved** for three cases: proceeding under ANY assumption would
+waste the work (the forks diverge at once); the doctrine reserves the decision
+to the practitioner; or the doctrine itself mandates the stop. **Exactly two
+mandating files prescribe their own hand-over, and there the general form does
+not apply**: `reconciliation.md` §4's escalation form (the claims in the set,
+each source, date and provenance, and why the machine cannot decide) — the
+mandated form for claim conflicts; and `review.md`'s round cap (the artifact
+plus the open findings). That list is closed. Every other blocking question
+carries the general form:
+
+- the fork: the concrete options and what each implies for the work;
+- the evidence: what you searched, read or tried, and what it leaves undecided;
+- why no assumption survives — what work is discarded if you assume and are
+  wrong;
+- why it is the practitioner's call;
+- what stays blocked until answered.
+
+## The round
+
+Ask ONE structured set of questions, not a drip of follow-ups. Keep each
+question short and numbered; offer concrete options where a real choice
+exists (this narrows the reply and speeds up the round). Cover:
+
+1. **Goal / benefit** — what problem this closes and why now. The answer must
+   name what the actor *obtains*, not a mechanism: "a dashboard" is not an
+   answer to "never lose the thread" — ask again until it is a benefit
+   (`vision.md`: the Vision is the distilled benefit; solutions and preferences
+   are what gets filtered out).
+2. **Actors** — who interacts with this: their role, primary goal, and what
+   "good UX" means to them. These become the Vision's `## Actors`; each
+   use-case below attaches to one (actor = who they are, use-case = what
+   they do). Skip only when an approved Vision already names them.
+3. **Scope boundaries** — what is explicitly included in this unit of work.
+4. **Non-goals** — what is explicitly excluded, so scope does not silently
+   creep in later.
+5. **Constraints** — technical, compatibility, and security constraints that
+   bound the solution space.
+6. **Acceptance signals** — how you and the user will both recognize the
+   work is done and correct.
+
+## Reflect
+
+Fold the answers into the ANALYSIS `## Objective` / `## Vision-Alignment`
+sections (Standalone) or into the D-UC/E-ISP (Hybrid) — do not leave them
+sitting only in the chat transcript. The written document, not the
+conversation, is what the next session and the next reviewer will read.
+
+Run a second round only when an answer opens a real fork in the design (a
+genuinely new question the first round could not have anticipated). Do not
+run a second round to double-check answers that were already clear.
+
+## Anti-patterns
+
+- **Interrogation**: an endless list of questions, or drip-feeding one
+  question at a time across many turns instead of one structured round.
+- **Asking what the approved vision already answers**: re-asking goal or
+  non-goals that a `Status: APPROVED` Vision or M-VISION already states.
+- **Collecting answers without folding them in**: getting replies in chat
+  and proceeding to design without writing them into the analysis document —
+  the next reader has no record of why the scope is what it is.