@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/skills/loop/references/metric-and-guard-contract.md

@@ -0,0 +1,76 @@
+# Metric and Guard contract
+
+Freeze this contract before mutation. If any field changes, stop for drift; do
+not silently recompute the baseline under new rules.
+
+## Required Metric fields
+
+- `argv`: nonempty trusted argv vector; no shell string.
+- `cwd`: canonical detached worktree root, fixed by Loop.
+- `unit`: one nonempty unit label.
+- `direction`: exactly `higher` or `lower`.
+- `sample_count`: integer at least 3, identical for baseline and candidates.
+- `timeout_ms`: positive integer per sample.
+- `minimum_delta`: finite nonnegative number in the declared unit.
+- `numeric_format`: exactly IEEE-754 binary64, roundTiesToEven after every
+  operation, with negative zero normalized to positive zero.
+- `environment`: fixed allowlisted names and redacted non-secret values; no
+  inherited credential or mutable random/time seed unless explicitly frozen.
+
+Each successful sample must emit exactly one trimmed UTF-8 line matching
+`^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$`. Reject empty,
+multi-line, multi-value, `NaN`, `Infinity`, unit-suffixed, nonzero exit, signaled,
+or timed-out output. Parse to a finite number without locale-dependent separators.
+Reject a decimal with a nonzero significand when binary64 parsing underflows it
+to zero.
+
+## Fixed calculation
+
+For each sample set:
+
+1. Sort binary64 values and calculate the median. For an even count with central
+   values `lower <= upper`, use `lower + (upper - lower) / 2` when both have the
+   same sign (zero may join either sign); otherwise use
+   `lower / 2 + upper / 2`. Apply binary64 roundTiesToEven after every operation
+   and normalize negative zero to positive zero.
+2. Calculate noise as the maximum absolute distance from that median.
+3. For `higher`, improvement is `candidate_median - best_median`; for `lower`,
+   improvement is `best_median - candidate_median`.
+4. Calculate `required_delta = max(minimum_delta, best_noise + candidate_noise)`.
+5. Accept only when `improvement > required_delta` and Guard passes on the exact
+   candidate bytes. Equality is not an improvement.
+
+After every operation, require median, noise, improvement, and required delta to
+remain finite. A parsed nonzero value that became zero, an overflow, or a
+non-finite derived value blocks the baseline or rejects the candidate; never
+store it as current best. A rounded zero produced by subtraction is handled
+conservatively as no improvement, never as a win.
+
+The initial current best is the pinned baseline. Keep the accepted candidate's
+median and noise as the next current best. Never compare a candidate against an
+older, more favorable baseline or select one sample from a noisy set.
+
+## Guard independence
+
+For code mutation, Guard is mandatory, fixed before baseline, and distinct from
+Metric. It must validate correctness beyond the optimized outcome—for example a
+relevant real test command, typecheck, or invariant checker. A second invocation
+of Metric, a threshold over the same output, or an oracle the loop may edit is
+not an independent Guard.
+
+Run Guard after Metric on the identical candidate fingerprint. Guard passes only
+with its predeclared literal exit/oracle and zero required skips; `NO_TESTS`,
+warning-only, partial, flaky-history waiver, or changed Guard bytes do not pass.
+Metric and Guard may create disposable caches only at exact predeclared paths.
+Snapshot the complete detached-worktree tracked/untracked state around each
+oracle, subtract only that fixed cache allowlist, and treat every other byte,
+mode, type, or path mutation—including outside Scope—as drift.
+
+## Reproducibility and drift
+
+Record tool versions, immutable Metric/Guard/test/benchmark/dataset digests,
+fixed inputs/data digest, relevant configuration digest,
+base OID, scoped byte manifest digest, and environment fingerprint. Stop when any
+of them changes. Report variance and raw sample values; do not hide outliers or
+retry only bad samples. A failed sample rejects the candidate rather than being
+dropped from aggregation.

package/src/claude/skills/pdf/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:pdf
+name: cf:pdf
 description: Extract text/tables, create, merge, split PDFs. Fill PDF forms programmatically. Use for PDF processing, generation, form filling, document analysis, batch operations.
 license: Proprietary. LICENSE.txt has complete terms
 user-invocable: true

package/src/claude/skills/pptx/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:pptx
+name: cf:pptx
 description: Create, edit, analyze .pptx PowerPoint files. Use for presentations, slides, layouts, speaker notes, template modification, content extraction, slide generation.
 license: Proprietary. LICENSE.txt has complete terms
 user-invocable: true

package/src/claude/skills/question/SKILL.md

@@ -1,18 +1,18 @@
 ---
-name: hapo:question
+name: cf:ask
 description: "Answer questions with evidence. Use when the user asks about project behavior, source code, specs, docs, configuration, dependencies, or external technical information; inspect the repo first, use internet/current docs when repo evidence is insufficient, and ask back only when the question cannot be answered safely."
 user-invocable: true
 when_to_use: "Invoke to answer project or technical questions with repo-first evidence."
 category: utilities
-keywords: [question, evidence, answer, research]
+keywords: [ask, question, evidence, answer, research]
 argument-hint: "<question> [--repo|--web|--both|--brief|--deep]"
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-# Question Skill
+# Ask Skill
 
-`hapo:question` is an evidence-backed question-answering skill. It answers user questions by checking the local project first, then external/current sources when the repository cannot answer the question.
+`cf:ask` is an evidence-backed question-answering skill. It answers user questions by checking the local project first, then external/current sources when the repository cannot answer the question.
 
 ## Core Stance
 
@@ -29,7 +29,7 @@ The output is an answer, evidence, confidence, and a follow-up only when needed.
 
 ## When To Use
 
-Use `hapo:question` when the user asks:
+Use `cf:ask` when the user asks:
 - "What does X do in this system?"
 - "Where is this flow handled?"
 - "What is the current config/version/package?"
@@ -41,10 +41,13 @@ Use `hapo:question` when the user asks:
 
 Do not use it when:
 - The user asks to implement, fix, debug, test, commit, or publish.
-- The user wants ideation/tradeoff exploration; use `hapo:brainstorm`.
-- The user wants a formal spec; use `hapo:specs`.
-- The user wants full legacy documentation reconstruction; use `hapo:docs --reconstruct`.
-- The user wants root-cause diagnosis for a failure; use `hapo:debug`.
+- The user wants ideation/tradeoff exploration; use `cf:brainstorm`.
+- The user wants a formal spec; use `cf:specs`.
+- The user wants full legacy documentation reconstruction: use
+  `cf:docs --reconstruct` when the optional document bundle is installed;
+  otherwise use `cf:scout` plus source evidence, or explain how to install the
+  bundle with `npx @haposoft/cafekit --with-document-skills`.
+- The user wants root-cause diagnosis for a failure; use `cf:debug`.
 
 ## Modes
 
@@ -77,7 +80,7 @@ Repo evidence priority:
 3. source files, tests, scripts, package manifests, config files
 4. git history only when the question asks about changes or provenance
 
-Use focused search (`rg`, targeted file reads) instead of broad scans. Use `hapo:inspect` when the user asks where something lives or the source surface is unclear.
+Use focused search (`rg`, targeted file reads) instead of broad scans. Use `cf:scout` when the user asks where something lives or the source surface is unclear.
 
 External evidence:
 - Use external/current docs when repo evidence is absent, stale, or not authoritative.
@@ -138,7 +141,7 @@ Use `templates/question.md` when the user asks to save or document the answer.
 ### Source Question
 
 ```text
-/hapo:question "In this system, which file does cafekit use to toggle skill routing?"
+/cf:ask "In this system, which file does cafekit use to toggle skill routing?"
 ```
 
 Expected behavior:
@@ -149,7 +152,7 @@ Expected behavior:
 ### Mixed Source + Web Question
 
 ```text
-/hapo:question "Which React version does this project use, and does that version still match current best practice?" --both
+/cf:ask "Which React version does this project use, and does that version still match current best practice?" --both
 ```
 
 Expected behavior:
@@ -160,7 +163,7 @@ Expected behavior:
 ### Ask Back
 
 ```text
-/hapo:question "Is this system stable?"
+/cf:ask "Is this system stable?"
 ```
 
 Expected behavior:

package/src/claude/skills/research/SKILL.md

@@ -1,58 +1,85 @@
 ---
-name: hapo:research
-description: "Research technical solutions and analyze architectures. Acts as a command facade to trigger the 'researcher' subagent for multi-source verification and deep report synthesis."
+name: cf:research
+description: "Research technical decisions with proportional depth, traceable evidence, explicit uncertainty, and project-fit recommendations."
 user-invocable: true
-when_to_use: "Invoke for deep technical research and solution evaluation before building."
+when_to_use: "Use for external technical facts, architecture comparisons, or decisions whose uncertainty needs multi-source evidence."
 category: research
-keywords: [research, evaluation, analysis, solutions]
-argument-hint: "<topic_or_question>"
+keywords: [research, evidence, evaluation, architecture, comparison]
+argument-hint: "<topic_or_decision>"
 metadata:
   author: haposoft
-  version: "2.0.0"
+  version: "3.0.0"
 ---
-# Research (Delegation Facade)
+# Research — proportional evidence for a decision
 
-**Mantra:** Return ranked recommendations with sources; never an unsorted list of options.
+Return a decision-ready answer, not a search diary or an unsorted option list.
+Research evaluates choices; it does not implement them or invent certainty.
 
-This skill acts as a **Command Facade**. When invoked, the main Orchestrator MUST NOT attempt to run WebSearch itself. Instead, it must instantly delegate the operation to the Specialized Subagent.
+## 1. Frame the decision
 
-## Execution Sequence
+Restate the decision, project constraints, affected consumers, and what evidence
+would change the answer. Inspect current repository sources first whenever local
+fit matters. Ask the user only when a missing choice materially changes scope or
+safety; otherwise label bounded assumptions and continue.
 
-### Phase 1: Clarification (Scope Lock)
-Before delegating, briefly assess the `[topic]`.
-- Is it vague? (e.g. "Research React"). If yes, immediately reject and demand the user specify the context (e.g. "Research SEO capabilities of React Server Components").
-- If solid, proceed.
+## 2. Select depth
 
-### Phase 2: Agent Delegation
-Call the `Agent` tool to invoke the `researcher` subagent. Use `TaskCreate` only for task-list tracking when the workflow needs persistent task state.
-**Instructions to pass to Researcher:**
-```text
-Conduct comprehensive research on: [topic]
-Constraint 1: ALWAYS use native `WebSearch` as the primary search method.
-Constraint 2: Validate key claims with multiple credible sources. Prioritize official docs, maintainers, release notes, and strong production references.
-Constraint 3: Use direct `WebFetch` only when search results are insufficient or raw source inspection is required.
-Constraint 4: Limit total search calls to a maximum of 5 distinct queries.
-Constraint 5: Stop excessive "chain-searching". Synthesize decisively once the evidence is sufficient.
-Output Format: Must strictly follow the 'Standard Research Report' layout.
-```
+Choose the smallest depth that can support the decision:
 
-### Phase 3: The Standard Report Format (Mandatory)
-The subagent MUST return the findings formatted EXACTLY according to the built-in specification template.
+| Depth | Route when | Evidence work |
+|---|---|---|
+| Quick | One low-risk, reversible fact or known option | Resolve the fact from one authoritative source; add a repository anchor when project fit matters. |
+| Standard | Several viable options or a material integration choice | Verify material claims across at least two independent authoritative sources where available; compare fit and tradeoffs. |
+| Deep | High blast radius, hard-to-reverse architecture, security/compliance, substantial cost, or conflicting evidence | Complete Standard, then run a separate contradiction-and-gap round; use at least three independent sources for disputed material claims where available. |
 
-Instruct the Researcher Subagent with this strict requirement:
-> "Use the template at .claude/skills/specs/templates/research.md verbatim. Do not add sections beyond it."
+Escalate depth when evidence conflicts, a primary source is missing, or a finding
+changes the decision boundary. Do not inflate source counts with mirrors or
+articles that repeat the same upstream claim. Stop when new evidence no longer
+changes the ranking, limitations, or unresolved gaps.
 
-## Post-Execution
-Once the `researcher` completes the Task and returns the Markdown output, save it based on context:
+## 3. Gather evidence
 
-### Output Routing
-| Context | Save to | Example |
-|---|---|---|
-| Active spec exists (`specs/<feature>/`) | `specs/<feature>/research.md` | `specs/auth-login/research.md` |
-| No active spec (system-wide / general) | `specs/_shared/Research-<slug>-<date>.md` | `specs/_shared/Research-mv3-best-practices-2026-04-11.md` |
-
-### Rules
-1. **Feature research** → Always save inside the active spec folder. If `specs/<feature>/` doesn't exist yet, create it.
-2. **System-wide research** → Save to `specs/_shared/`. Create the directory if it doesn't exist.
-3. **Never** save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
-4. Conclude the workflow by providing the user with the saved file path.
+- Repository claims: cite a resolvable `path:line` anchor from current bytes.
+- External claims: prefer current official documentation, standards, research
+  papers, maintainer material, and release notes. Browse when facts may have
+  changed; record the source date or applicable version.
+- For each material claim record: claim, URL or repository anchor, authority,
+  date/version, applicability to this project, and status
+  `confirmed | inferred | unresolved`.
+- A source count is not confidence. Explain conflicts, missing primary evidence,
+  version mismatch, and why a source does or does not apply.
+
+Use delegated researchers only as optional acceleration when two or more
+independent evidence tracks can be bounded. The controller owns the question,
+source reconciliation, and final recommendation. If delegation is unavailable,
+unauthorized, or not useful, research sequentially with the same evidence bar.
+
+## 4. Synthesize
+
+For comparisons, rank only viable options and name a winner when evidence and
+project fit support one. For every ranked option include fit, decisive evidence,
+tradeoffs, adoption/operational risks, and limitations. If evidence cannot choose
+a winner, return `unresolved` plus the smallest fact or experiment that would.
+
+Use the four mandatory H2 sections from
+`.claude/skills/specs/templates/research.md`. Keep claim records and comparisons
+inside `## Evidence Summary`; do not add or reorder mandatory H2 headings.
+
+## 5. Output and persistence
+
+Default to a concise answer in chat. Persist only when:
+
+1. one explicitly resolved active Spec requires durable `research.md`; save to
+   that exact `specs/<feature>/research.md`, preserving its existing lifecycle; or
+2. the user explicitly requests a durable report and approves its destination.
+
+Do not create a Spec or `_shared` archive merely to save an answer. The
+controller performs any authorized write after reviewing and redacting the
+output; delegated researchers never write reports or task state. Always state
+depth used, decisive evidence, recommendation, limitations, and unresolved gaps.
+
+## Handoff boundary
+
+Research may recommend Brainstorm or Specs when a material product/design choice
+remains. It never starts Develop, edits implementation code, claims user approval,
+or presents source/installed evidence as live-system proof.

package/src/claude/skills/route/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cf:route
+description: "Route ambiguous, multi-step, multi-domain, or risk-elevated work through the shortest valid chain of installed CafeKit skills and agents."
+user-invocable: true
+when_to_use: "Use when no single obvious installed skill covers the request; skip for an explicitly named skill, one clear low-risk intent, or a direct factual answer."
+category: utilities
+keywords: [routing, workflow, orchestration, delegation, risk]
+argument-hint: "<task>"
+metadata:
+  author: haposoft
+  version: "1.0.0"
+---
+# Route — proportional native routing
+
+Choose the shortest valid path through capabilities that are installed now.
+Route is a decision layer: it classifies, composes, and hands off; each selected
+skill or agent still owns its domain contract and evidence.
+
+## 1. Proportional gate
+
+Apply these exits before discovery, classification, or delegation:
+
+1. **Explicit installed skill:** when the user names a valid installed skill,
+   invoke that skill directly. Do not reclassify it or add routing ceremony.
+2. **One obvious intent:** when exactly one installed skill clearly covers a
+   low-risk request, use it directly without constructing a chain.
+3. **Direct factual conversation:** answer a factual question directly, or use
+   the installed evidence-answering skill when repository or current evidence is
+   needed. Do not create a route chain or spawn agents merely to answer it.
+4. Continue in Route only for ambiguity, multiple dependent steps, multiple
+   domains, elevated/high risk, or no obvious installed capability.
+
+An explicitly named capability that is absent, invalid, duplicate, ambiguous,
+or retired is not an installed route. Name the gap; do not invent a substitute
+with broader authority.
+
+## 2. Classify material work
+
+Load `references/task-taxonomy.md`. Record exactly one class based on the final
+deliverable, then record size (`trivial | standard | epic`), the highest-link
+risk (`low | elevated | high`), and the number of material domains. Never
+average risk down across links.
+
+Use the runtime's live installed skill and agent catalogs. Never synthesize a
+skill, agent, command, or optional bundle from examples in these instructions.
+If inventory is unavailable, use only capabilities the runtime visibly exposes;
+otherwise name the capability gap and keep the path inline where safe.
+
+## 3. Compose the shortest valid chain
+
+Load `references/chaining-patterns.md` only when two or more links are required.
+Start from `understand -> decide -> execute -> verify -> deliver`, remove every
+link whose output is already evidenced, and add a link only when a modifier
+requires it. Every retained link has an entry condition, an observable exit
+artifact, and exactly one owner.
+
+Prefer the user-named skill, then the narrowest domain skill, then a generic
+workflow skill. One intent has one primary skill. Supporting skills may produce
+inputs for it but may not compete for ownership.
+
+## 4. Agents and risk gates
+
+Load `references/agent-timing.md` only when delegation may materially improve
+fresh context, specialization, tool isolation, or safe parallel work. Discover
+agents from the current runtime; if the preferred agent is missing, continue
+inline when safe or return the named gap. Never synthesize an unavailable agent.
+
+- `low`: the owning link's normal proof is sufficient.
+- `elevated`: add explicit verification appropriate to the changed surface.
+- `high`: require independent review and user confirmation before advancing
+  past the high-risk gate. When an irreversible or external action is present,
+  obtain that confirmation immediately before the action.
+
+## 5. Authority is monotonic
+
+The route may narrow user authority but never expand it. Read-only stays
+read-only; diagnosis does not authorize repair; implementation does not
+authorize commit, push, deploy, publish, or release; local work does not
+authorize an external action. Stop before any mutation or delivery link that
+the user did not already authorize and state what authority is missing.
+
+## 6. Return and handoff
+
+Return a compact route record before the first material handoff:
+
+```text
+Route: <class> | size=<trivial|standard|epic> | risk=<low|elevated|high> | domains=<n>
+Chain: <owner: entry -> exit> [-> ...]
+Gates: <authority, verification, confirmation, or named gap>
+```
+
+Do not claim that source text or installed projection proves live-model
+adherence. That behavior remains `[UNPROVEN]` until a separate host run observes
+it.

package/src/claude/skills/route/references/agent-timing.md

@@ -0,0 +1,46 @@
+# Agent timing
+
+Delegation is optional acceleration, not a mandatory stage. Keep work inline
+when it is small, tightly coupled, dependent on shared evolving context, or no
+installed specialist offers a material advantage.
+
+Delegate only when at least one trigger is evidenced:
+
+- a specialist needs fresh isolated context;
+- a distinct tool or runtime boundary must be owned separately;
+- two or more scopes are genuinely independent and can run in parallel;
+- an independent reviewer or tester is required by risk.
+
+Discover the current runtime's installed agent catalog before delegation. Use
+Claude-native agent types in Claude Code and Codex-native agents/subagents in
+Codex. If the preferred agent is absent, do the work inline when safe or name
+the gap and stop; never synthesize a role or pretend delegation occurred.
+
+## Delegation brief
+
+Every delegated link receives exactly these seven fields:
+
+1. **Outcome** — observable result.
+2. **Scope** — owned files, systems, or questions.
+3. **Inputs** — current evidence and prerequisite artifacts.
+4. **Constraints** — safety, compatibility, authority, and non-goals.
+5. **Acceptance** — proof required for completion.
+6. **Handoff** — expected returned artifact and destination.
+7. **Status vocabulary** — `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`.
+
+Parallel delegates require disjoint write ownership and no hidden dependency.
+The controller reconciles their outputs and remains responsible for route state;
+an agent never gains commit, push, deploy, publish, release, or other mutation
+authority from delegation alone.
+
+## Status handling
+
+- `DONE`: validate the exit artifact, then advance.
+- `DONE_WITH_CONCERNS`: resolve correctness or scope concerns before advancing;
+  record observational concerns without inventing failure.
+- `BLOCKED`: change evidence, owner, scope, or dependency before retrying.
+- `NEEDS_CONTEXT`: supply the missing bounded context before retrying.
+
+Never blindly retry `BLOCKED` or `NEEDS_CONTEXT`. A retry without a material
+change preserves the same normalized cause and therefore the same route failure
+key.

package/src/claude/skills/route/references/chaining-patterns.md

@@ -0,0 +1,53 @@
+# Chaining patterns
+
+Use a chain only when one link's output is required by another. The default
+skeleton is:
+
+```text
+understand -> decide -> execute -> verify -> deliver
+```
+
+## Link contract
+
+Every retained link must state:
+
+- **Entry:** the evidence or artifact required to start.
+- **Exit:** one observable artifact or decision passed forward.
+- **Owner:** exactly one installed skill, installed agent, or the controller.
+
+Pass only the exit artifact plus the target, constraints, authority, acceptance,
+and unresolved gaps needed by the next owner. For one or two short links, chat
+context is enough. For longer or interruption-prone work, use an already
+authorized repository artifact; routing never grants permission to create one.
+
+## Collapse and insertion
+
+Remove a link when its exit is already current and evidenced. An explicit valid
+skill or one obvious low-risk intent normally collapses to one link. Do not keep
+Scout, Brainstorm, Research, Specs, Test, Review, Git, or delivery merely for
+ceremony.
+
+Insert a link only for a real modifier:
+
+- unresolved repository shape -> discovery;
+- unresolved material choice -> decision;
+- implementation or repair -> execution;
+- elevated risk or changed behavior -> verification;
+- high risk -> independent review and confirmation;
+- commit, push, deploy, publish, or release -> delivery, only with matching
+  user authority.
+
+## Failure detours and stop
+
+On a failed link, preserve its valid exit evidence, normalize the root cause,
+and choose one bounded detour that can change that cause. Track the failure key
+as `(link, owner, normalized cause)` within the current chain.
+
+Two failures with the same failure key stop the chain and return `BLOCKED` with
+the evidence and missing decision or capability. Different normalized causes do
+not share a key and must not stop early merely because the link name matches.
+This route-level stop does not replace a separate orchestrator's authoritative
+task-retry budget.
+
+No detour may add authority. In particular, review cannot imply push,
+diagnosis cannot imply repair, and build cannot imply deploy.

package/src/claude/skills/route/references/task-taxonomy.md

@@ -0,0 +1,48 @@
+# Task taxonomy
+
+Classify by the final deliverable the user expects, not by the first verb, file
+type, or tool mentioned. Choose exactly one class; use domains as modifiers.
+
+| Class | Final deliverable |
+|---|---|
+| `answer` | Evidence-backed explanation or factual response |
+| `discover` | Located files, call path, inventory, or blast-radius map |
+| `decide` | Chosen product, architecture, or technical direction |
+| `specify` | Approved bounded plan and executable task packet |
+| `change` | Working implementation or content change |
+| `diagnose` | Root cause and verification-ready repair plan |
+| `repair` | Cause-aligned fix plus regression proof |
+| `verify` | Test or review verdict with owned evidence |
+| `deliver` | Authorized commit, push, deploy, publish, or release result |
+
+When a request contains several verbs, classify by its terminal observable
+result. For example, “research options and implement the winner” is `change`,
+while research is a decision link. “Inspect this failure and tell me why” is
+`diagnose`, not `repair`.
+
+## Size
+
+- `trivial`: one clear reversible outcome, normally one owner and one link.
+- `standard`: multiple dependent links or a bounded cross-file/domain change.
+- `epic`: three or more independently deliverable subsystems; split them into
+  bounded routes instead of creating one oversized chain.
+
+## Risk
+
+Risk is the maximum risk of any retained link, never an average:
+
+- `low`: local, reversible, no material compatibility or data boundary.
+- `elevated`: shared contract, integration, migration, sensitive data, or a
+  meaningful regression surface.
+- `high`: security boundary, irreversible data/action, production delivery,
+  public compatibility, or large blast radius.
+
+## Domains and ambiguity
+
+Count only material domains that need distinct evidence or ownership. A file
+extension alone is not a domain. Ambiguity adds an understand or decide link
+only when unresolved information can change the final deliverable, authority,
+or verification; otherwise choose the shortest valid direct path.
+
+Modifiers constrain a route. They never grant mutation, external-action,
+commit, push, deploy, publish, or release authority.