@rune-kit/rune 2.13.0 → 2.15.0

package/skills/ba/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: ba
-description: Business Analyst agent. Deeply understands user requirements before any planning or coding begins. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume.
+description: "Business Analyst agent. Use when starting a new feature requiring requirements elicitation BEFORE plan or cook. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume."
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.11.0"
   layer: L2
   model: opus
   group: creation
   tools: "Read, Glob, Grep"
+  emit: outofscope.match
 ---
 
 # ba
@@ -16,6 +17,8 @@ metadata:
 
 Business Analyst agent — the ROOT FIX for "Claude works a lot but produces nothing." BA forces deep understanding of WHAT to build before any code is written. It asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document.
 
+> Wrong requirements shipped correctly is the most expensive bug. BA's job is to prevent it — measure clarity (Step 2.5), measure completeness (Step 3.5), and measure cross-dimension consistency (Step 3.6) before handoff.
+
 <HARD-GATE>
 BA produces WHAT, not HOW. Never write code. Never plan implementation.
 Output is a Requirements Document → hand off to rune:plan for implementation planning.
@@ -70,6 +73,58 @@ If Refactor → light version (Step 1 + Step 4 only). Skip Steps 2, 2.5, 3, 5, 6
 
 If existing codebase → invoke `rune:scout` for context before proceeding.
 
+### Step 1.5 — Out-of-Scope Match Check
+
+Before any elicitation, check whether the request matches a concept previously rejected.
+
+1. `Glob` `.out-of-scope/*.md` — if directory absent, skip silently.
+2. For each file, parse YAML frontmatter (`concept`, `aliases`).
+3. Build a token map (lowercased, split on `-` and whitespace).
+4. Tokenize the user's request the same way.
+5. Compute lexical overlap per concept; keep the top match's `confidence` (0.0–1.0).
+
+**Action by confidence**:
+
+| Confidence | Verdict | Action |
+|------------|---------|--------|
+| ≥ 0.8 | exact-match | Surface to user: *"This matches a prior rejection (`.out-of-scope/<slug>.md`) — closed because [body's "Why out of scope" first sentence]. Do you still feel the same way?"* Pause for user response before continuing. |
+| 0.5 – 0.79 | similar | Mention inline: *"This is similar to a prior rejection (`<slug>`). Would you like to review it before we proceed?"* Continue regardless of answer. |
+| < 0.5 | no-match | Continue silently, no user-facing mention. |
+
+Emit `outofscope.match` signal with `{concept, confidence, verdict}` so downstream skills (cook, plan) inherit the context.
+
+If verdict is exact-match AND user says "yes I still want it" → record their override reason in the Requirements Document `## Risks` section AND mark `priority_to_revisit: high` in the existing `.out-of-scope/<slug>.md` (do NOT delete the file). The override forces the candidate up the revisit ladder; it doesn't erase the prior decision.
+
+If verdict is exact-match AND user accepts the prior rejection → end the BA session with a one-line summary referencing the file. No further questions.
+
+Format reference: [references/out-of-scope-format.md](references/out-of-scope-format.md).
+
+### Step 2.0 — Explore-First Pre-Check (HARD-GATE)
+
+Before emitting ANY of the 5 elicitation questions, run the 4-item pre-check on each intended question:
+
+1. Is the answer in `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `pom.xml`?
+2. Is the answer in `README.md` / `CLAUDE.md` / `docs/`?
+3. Is it inferable from file extensions, directory structure, or config files?
+4. Has the user answered it earlier in this conversation?
+
+<HARD-GATE>
+For every question Q the agent intends to ask, there MUST be prior tool-call evidence in the same session:
+- At least 1 Read / Glob / Grep related to Q's domain, OR
+- Explicit declaration: "Q cannot be answered from project artifacts because [specific reason]."
+Without one of these, Q is BLOCKED — re-route to inference.
+</HARD-GATE>
+
+The gate is "tried to infer" — not "must succeed in inferring." If the file genuinely doesn't have the answer, the attempt itself is the gate.
+
+Cache inferred answers in the requirements doc:
+```
+**Inferred from package.json**: TypeScript 5.4, Next.js 14.2, React 18.3
+**Inferred from .github/workflows/**: CI runs on PRs targeting main
+```
+
+Worked examples + edge cases: [references/explore-first.md](references/explore-first.md).
+
 ### Step 2 — Requirement Elicitation (the "5 Questions")
 
 Ask exactly 5 probing questions, ONE AT A TIME (not all at once):
@@ -195,6 +250,23 @@ Clarity Score: [100 - ambiguity]%
   Status: ACCEPTABLE (ambiguity 23%) — proceeding with noted gaps
 ```
 
+### Step 2.6 — CONTEXT.md Cross-Reference Gate
+
+After elicitation, before hidden-requirement discovery, scan the user's answers for assertions about *current behavior* — phrasings like "the system X", "the code does X", "we already X", "right now it X".
+
+For each such assertion:
+
+1. `Grep` the codebase for evidence (function names, route handlers, schema definitions matching the asserted behavior).
+2. Compare grep results to the user's claim.
+
+| Outcome | Action |
+|---------|--------|
+| Grep confirms claim | Proceed; record term in CONTEXT.md if domain-relevant |
+| Grep contradicts claim | <HARD-GATE>Surface the conflict immediately. *"You said the system does X, but the code path I see does Y. Which is canonical?"* Pause until resolved.</HARD-GATE> |
+| Grep returns nothing | Note as unverified; ask user for the file/function name; do not record in CONTEXT.md until verified |
+
+This gate prevents the agent from silently transcribing user-asserted behavior that contradicts code — a common source of "the docs say X but the code does Y" drift.
+
 ### Step 3 — Hidden Requirement Discovery
 
 After the 5 questions, analyze for requirements the user DIDN'T mention:
@@ -243,6 +315,53 @@ When presenting options, alternatives, or scope decisions to the user, rate each
 **Anti-pattern**: "Choose B — it covers 90% of the value with less code." → If A is only 70 lines more, choose A. The last 10% is where production bugs hide.
 
 
+### Step 3.6 — Logic Consistency Check
+
+After ambiguity + completeness pass, scan for **cross-dimension contradictions**. Ambiguity measures CLARITY of each dimension in isolation; this step measures CONSISTENCY across dimensions. A perfectly clear requirement can still contradict itself.
+
+#### Checks
+
+Run each, label verdict 🟢 pass / 🟡 warn / 🔴 fail:
+
+| # | Check | 🔴 Fail | 🟢 Pass |
+|---|-------|---------|---------|
+| 1 | Every Acceptance Criterion traces to a User Story | AC orphaned | 1:N mapping clear |
+| 2 | Every Business Rule (Q5) is enforced in an AC or Exception Flow | Rule has no enforcement path | Rule → specific AC or exception |
+| 3 | Scope IN ∩ Scope OUT = ∅ | Direct overlap in phrasing | Sets disjoint |
+| 4 | Every user-story flow has a terminal state | State loop without exit condition | Terminal state explicit |
+| 5 | Dependencies (Step 4) ⊂ Constraints acknowledged (Q5) | Dependency never mentioned in constraints | All deps covered |
+| 6 | NFRs measurable against at least one AC | NFR has no test hook | Every NFR → testable AC |
+| 7 | Hidden requirements (Step 3) resolved in/out | Silent inclusion | User confirmed inclusion or exclusion |
+| 0 | Prior rejection check (Step 1.5) — exact-match resolved with explicit override or session ended | Silent re-litigation of rejected concept | User chose: override (priority bumped) OR accept prior decision (session ends) |
+
+#### Output Format
+
+```
+Logic Consistency Report:
+  1. AC → User Story:      🟢 all AC trace to US-1 or US-2
+  2. Business rule → AC:   🟡 "no duplicate emails" cited — exception flow missing
+  3. Scope disjoint:       🟢
+  4. Terminal states:      🟢
+  5. Deps in constraints:  🔴 "PostgreSQL 15" missing from Q5 answer
+  6. NFR measurable:       🟢
+  7. Hidden reqs resolved: 🟢
+
+Verdict: 1 🔴, 1 🟡, 5 🟢 → BLOCK handoff until 🔴 fixed
+```
+
+#### Gate Rule
+
+| Result | Action |
+|--------|--------|
+| 0 🔴 | Proceed to Step 4 — 🟡 warnings become "Risks" in Requirements Doc |
+| 1-2 🔴 | BLOCK — ask targeted question or re-scope to resolve each 🔴 |
+| 3+ 🔴 | Scrap Steps 2-3 and restart — requirements structurally incoherent |
+
+<HARD-GATE>
+NEVER hand off to plan with unresolved 🔴. Ambiguity ≤ 40% does not imply consistency — they are orthogonal gates.
+If user pushes "just build it" with 🔴 present, respond: "Contradiction in [dimension]: [specific conflict]. One clarification fixes this: [targeted question]"
+</HARD-GATE>
+
 ### Step 4 — Scope Definition
 
 Based on all gathered information, produce:
@@ -330,9 +449,19 @@ For product-oriented requirements (Feature Request, Integration, Greenfield), ge
 - Every tier includes "Risk if skipped" — makes trade-offs explicit
 - Skip this step for Bug Fix and Refactor types (no strategic dimension)
 
-### Step 7 — Requirements Document
+### Step 7 — Artifact Triad
 
-Produce structured output and hand off to `plan`:
+Produce three structured artifacts — not one prose doc. Plan consumes all three; each answers a different question.
+
+| Artifact | Question Answered | Consumer |
+|----------|-------------------|----------|
+| `requirements.md` | WHAT to build and WHY | plan, cook |
+| `requirements.mermaid` | WHAT does the flow look like visually | plan, design, review |
+| `tasks.md` | WHAT work layers exist | plan (as task backbone, not from scratch) |
+
+#### Artifact 1: requirements.md
+
+Structured document combining Steps 1-6.5. Save to `.rune/features/<feature-name>/requirements.md`:
 
 ```markdown
 # Requirements Document: [Feature Name]
@@ -350,11 +479,8 @@ Created: [date] | BA Session: [summary]
 
 ## Scope
 ### In Scope
-[from Step 4]
 ### Out of Scope
-[from Step 4]
 ### Assumptions
-[from Step 4]
 
 ## Non-Functional Requirements
 [from Step 6]
@@ -368,101 +494,119 @@ Created: [date] | BA Session: [summary]
 ## Strategic Recommendations
 [from Step 6.5 — skip for Bug Fix/Refactor]
 
-### Quick Win (0-30 days)
-- **Action**: [specific deliverable]
-- **Resources**: [effort estimate]
-- **Expected Impact**: [measurable outcome]
-
-### Differentiation (1-3 months)
-- **Action**: [...]
-- **Resources**: [...]
-- **Expected Impact**: [...]
-
-### Long-term Moat (6-12 months)
-- **Action**: [...]
-- **Resources**: [...]
-- **Expected Impact**: [...]
+## Logic Consistency Report
+[from Step 3.6 — verbatim, for audit trail]
 
 ## Next Step
-→ Hand off to rune:plan for implementation planning
+→ Hand off to rune:plan (consumes all 3 artifacts)
 ```
 
-Save to `.rune/features/<feature-name>/requirements.md`
+#### Artifact 2: requirements.mermaid
 
-## Output Format
+Auto-generate from User Stories. Save to `.rune/features/<feature-name>/requirements.mermaid`.
+
+**Sequence diagram** (primary happy path from US-1):
 
+```mermaid
+sequenceDiagram
+  actor User
+  participant System
+  participant Database
+  User->>System: [action from US-1]
+  System->>Database: [read/write from AC-1.1]
+  Database-->>System: [response]
+  System-->>User: [result from AC-1.1]
 ```
-# Requirements Document: [Feature Name]
-Created: [date] | BA Session: [summary]
 
-## Context
-[Problem statement — 2-3 sentences]
+**State machine** (only if any User Story implies state):
 
-## Stakeholders
-- Primary user: [who, technical level, workflow context]
-- Affected systems: [existing services, databases, APIs]
+```mermaid
+stateDiagram-v2
+  [*] --> initial
+  initial --> processing: [trigger from AC]
+  processing --> success: [happy path AC]
+  processing --> failed: [error AC]
+  success --> [*]
+  failed --> initial: retry
+```
 
-## User Stories
-US-1: As a [persona], I want to [action] so that [benefit]
-  AC-1.1: GIVEN [context] WHEN [action] THEN [result]
-  AC-1.2: GIVEN [error case] WHEN [action] THEN [error handling]
+Skip state machine if feature is stateless (simple CRUD with no lifecycle). Sequence is always produced.
 
-## Scope
-### In Scope
-- [feature/behavior 1]
-- [feature/behavior 2]
-### Out of Scope
-- [explicitly excluded 1]
-### Assumptions
-- [assumption — risk if wrong]
+#### Artifact 3: tasks.md
 
-## Non-Functional Requirements
-| NFR | Requirement | Measurement |
-|-----|-------------|-------------|
-| [Performance/Security/etc.] | [specific target] | [how to verify] |
+Pre-broken implementation tasks by layer. Plan refines this backbone, does not create from scratch. Save to `.rune/features/<feature-name>/tasks.md`:
 
-## Dependencies
-- [API/service/library]: [status — available/needs setup]
+```markdown
+# Implementation Tasks: [Feature Name]
+
+## Data Layer
+- [ ] Schema — [tables/models from AC]
+- [ ] Migration up + down
+- [ ] Seed/fixtures if tests need them
+
+## Logic Layer
+- [ ] [each Q5 Business Rule → one task]
+- [ ] Validation for [each AC error case]
+- [ ] State transitions from requirements.mermaid (if present)
+
+## Interface Layer (API / UI)
+- [ ] [each User Story → one endpoint or UI component]
+- [ ] Contract schema from AC (request/response)
+- [ ] Error handling for [each AC error]
+
+## Test Layer
+- [ ] Unit: [each business rule → one test]
+- [ ] Integration: [each AC happy path]
+- [ ] Regression: [each AC error case]
+
+## NFR Verification
+- [ ] [each NFR from Step 6 → one measurement task]
+```
 
-## Risks
-- [risk]: [mitigation strategy]
+Derivation rules:
+- 1 User Story → ≥1 Interface task
+- 1 Business Rule → 1 Logic task + 1 Unit test task
+- 1 AC → ≥1 Test task (happy path + error)
+- 1 NFR → 1 NFR Verification task
 
-## Decision Classification
+#### Handoff
 
-| Category | Meaning | Example |
-|----------|---------|---------|
-| **Decisions** (locked) | User confirmed — agent MUST follow | "Use PostgreSQL, not MongoDB" |
-| **Discretion** (agent decides) | User trusts agent judgment | "Pick the best validation library" |
-| **Deferred** (out of scope) | Explicitly NOT this task | "Mobile app — future phase" |
+Emit signal to `plan` with paths to all three artifacts. Plan MUST read all three before producing phase files — the triad is the contract.
 
-Plan gates on Decision compliance — Discretion items don't need approval.
+### Step 7.5 — Glossary Sharpen (CONTEXT.md update)
 
-## Strategic Recommendations
-[Skip for Bug Fix/Refactor]
+After the artifact triad is saved, append/update the project glossary `CONTEXT.md` with any domain terms that were sharpened during this session.
 
-### Quick Win (0-30 days)
-- **Action**: [immediate deliverable]
-- **Resources**: [effort + dependencies]
-- **Expected Impact**: [measurable KPI]
-- **Risk if skipped**: [consequence]
+1. Determine glossary location:
+   - If `CONTEXT-MAP.md` exists at root → multi-context; pick the right per-context CONTEXT.md
+   - Else if root `CONTEXT.md` exists → use it
+   - Else if any term needs recording → create root `CONTEXT.md` lazily
+   - Else → skip silently (no-op when no terms emerged)
+2. For each new term, add a row to the **Language** table (term, definition, aliases-to-avoid, status).
+3. For each user-asserted relationship, add to the **Relationships** section.
+4. For each ambiguity surfaced during elicitation, add to **Flagged ambiguities**.
 
-### Differentiation (1-3 months)
-- **Action**: [competitive advantage work]
-- **Resources**: [...]
-- **Expected Impact**: [...]
-- **Risk if skipped**: [...]
+**Conflict gate** — if a new term has ≥0.7 token overlap with an existing one, surface to user (merge / rename / keep distinct). NEVER silently re-define an existing term.
 
-### Long-term Moat (6-12 months)
-- **Action**: [defensible position work]
-- **Resources**: [...]
-- **Expected Impact**: [...]
-- **Risk if skipped**: [...]
+Format reference: [references/context-md-format.md](references/context-md-format.md).
 
-## Next Step
-→ Hand off to rune:plan for implementation planning
-```
+## Output Format
+
+Triad of artifacts under `.rune/features/<feature-name>/`:
+
+| File | Template Reference |
+|------|-------------------|
+| `requirements.md` | Step 7 Artifact 1 |
+| `requirements.mermaid` | Step 7 Artifact 2 (sequence + optional state machine) |
+| `tasks.md` | Step 7 Artifact 3 (Data / Logic / Interface / Test / NFR layers) |
 
-Saved to `.rune/features/<feature-name>/requirements.md`
+Inside `requirements.md` the **Decision Classification** table MUST appear verbatim — plan gates on Decision compliance, Discretion items skip approval:
+
+| Category | Meaning | Example |
+|----------|---------|---------|
+| **Decisions** (locked) | User confirmed — agent MUST follow | "Use PostgreSQL, not MongoDB" |
+| **Discretion** (agent decides) | User trusts agent judgment | "Pick the best validation library" |
+| **Deferred** (out of scope) | Explicitly NOT this task | "Mobile app — future phase" |
 
 ## Constraints
 
@@ -482,9 +626,10 @@ Saved to `.rune/features/<feature-name>/requirements.md`
 | Artifact | Format | Location |
 |----------|--------|----------|
 | Requirements document | Markdown | `.rune/features/<feature-name>/requirements.md` |
-| User stories with acceptance criteria | Markdown (GIVEN/WHEN/THEN) | inline + requirements.md |
-| Scope definition (in/out/assumptions) | Markdown sections | requirements.md |
-| Non-functional requirements table | Markdown table | requirements.md |
+| Visual model | Mermaid (sequence + optional state machine) | `.rune/features/<feature-name>/requirements.mermaid` |
+| Implementation task backbone | Markdown checklist by layer | `.rune/features/<feature-name>/tasks.md` |
+| Logic Consistency Report | Markdown section | Embedded in requirements.md |
+| Ambiguity + Completeness scores | Markdown display blocks | Embedded in requirements.md |
 
 ## Sharp Edges
 
@@ -508,6 +653,18 @@ Known failure modes for this skill. Check these before declaring done.
 | Skipping ambiguity scoring because "user seems clear" | HIGH | Always compute the score — perceived clarity ≠ measured clarity. The formula catches gaps humans miss |
 | Tiered recommendations too vague ("improve things") | MEDIUM | Each tier needs specific Action + measurable Expected Impact. "Build better UX" → "Reduce checkout steps from 5 to 3, targeting 15% conversion lift" |
 | All three tiers have same resources/effort | MEDIUM | Quick Win should be low-effort. If all tiers need "2 engineers, 3 months" → re-scope Quick Win to something achievable in 1 sprint |
+| Skipping Logic Consistency check because ambiguity is low | CRITICAL | Step 3.6 HARD-GATE: clarity ≠ consistency. A 90% clarity spec can still contain pairwise contradictions (scope IN/OUT overlap, rules with no enforcement, orphan ACs) |
+| Handing off to plan with unresolved 🔴 consistency fails | CRITICAL | Step 3.6 gate: 1+ 🔴 = BLOCK. 🟡 allowed only when logged as Risk in requirements.md |
+| Producing only requirements.md, skipping mermaid and tasks.md | HIGH | Step 7 is a triad — plan's contract expects all 3. Sequence diagram is always produced; state machine only if stateful; tasks.md always produced |
+| Mermaid diagram unrelated to actual user stories (decorative only) | MEDIUM | Sequence must trace AC-1.1 of US-1; state machine nodes must map to state-bearing ACs. Auditable by pattern-match |
+| tasks.md as flat list instead of layered | MEDIUM | Derivation rules enforce 1 US → Interface task, 1 rule → Logic + Unit test, 1 AC → Test task, 1 NFR → verification. Skipping layers loses plan's backbone structure |
+| Re-litigating a previously rejected concept without surfacing it | HIGH | Step 1.5 HARD-GATE: scan `.out-of-scope/` first; exact match (≥0.8) MUST be surfaced before elicitation begins |
+| Skipping Step 1.5 because `.out-of-scope/` directory looks empty | MEDIUM | Empty directory is silent-skip OK; directory absent entirely is silent-skip OK; never skip due to "I don't think this matches anything" — let the matcher decide |
+| User asserts behavior; agent records user's version without grep verification | HIGH | Step 2.6 HARD-GATE: every "the system does X" assertion gets grep'd; conflicts surface to user before recording |
+| Silently re-defining an existing CONTEXT.md term | HIGH | Step 7.5 conflict gate: ≥0.7 overlap → user chooses merge/rename/keep-distinct |
+| Auto-creating an empty CONTEXT.md when no terms emerged | LOW | Lazy creation rule: only write when there's a non-trivial term to record |
+| Asking inferable questions ("what stack are you using?") without first checking package.json | HIGH | Step 2.0 HARD-GATE — every question requires prior tool-call evidence (Read/Glob/Grep) or explicit unavailability declaration |
+| Re-asking a question already answered earlier in the conversation | MEDIUM | Step 2.0 check 4 — cache and reuse, never re-ask |
 
 ## Done When
 
@@ -518,8 +675,10 @@ Known failure modes for this skill. Check these before declaring done.
 - Scope defined (in/out/assumptions/dependencies)
 - User stories with testable acceptance criteria produced
 - Non-functional requirements assessed (relevant ones only)
+- Logic Consistency Report produced — 0 🔴 before handoff (🟡 logged as Risks)
 - Tiered recommendations generated (Quick Win / Differentiation / Moat) — skip for Bug Fix/Refactor
-- Requirements Document saved to `.rune/features/<name>/requirements.md`
+- Artifact triad saved: `requirements.md` + `requirements.mermaid` + `tasks.md`
+- Out-of-scope match check completed (verdict logged: no-match | similar | exact-match-overridden | exact-match-accepted)
 - Handed off to `plan` for implementation planning
 
 ## Cost Profile

package/skills/ba/references/context-md-format.md

@@ -0,0 +1,136 @@
+# CONTEXT.md — Project Glossary Format
+
+Persistent vocabulary for the project's domain — what nouns mean, how concepts relate, which words are aliases of which. Lives at the repo root (or per-bounded-context root in multi-context repos).
+
+## Where it lives
+
+```
+<repo-root>/
+├── CONTEXT.md                   ← single-context repo
+└── src/
+
+# OR for multi-context repos:
+<repo-root>/
+├── CONTEXT-MAP.md               ← lists each context + relationships
+└── src/
+    ├── ordering/CONTEXT.md
+    └── billing/CONTEXT.md
+```
+
+If `CONTEXT-MAP.md` exists at root, the repo has multiple contexts; otherwise it's single-context.
+
+## Lazy creation
+
+CONTEXT.md is created **only when there's a non-trivial term to record**. Empty file = bad signal. Absent file = silent OK.
+
+`ba` checks via Glob; absence is **not** flagged as a project gap. Don't suggest "you should create one." Wait until a term needs sharpening.
+
+## Format
+
+```markdown
+# Project Glossary
+
+One-line description of what this project is and why this glossary exists.
+
+## Language
+
+| Term | Definition | Aliases to avoid | Status |
+|------|------------|-------------------|--------|
+| **Order** | A customer's request to purchase items | Purchase, transaction | canonical |
+| **Invoice** | A request for payment sent after delivery | Bill, payment request | canonical |
+| **Customer** | A person or organization that places orders | Client, buyer, account | canonical |
+| **User** | An authentication identity in the system | Login, account | canonical |
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+- A **Customer** may or may not be a **User** (guests can place orders)
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+
+## Flagged ambiguities
+
+- "account" was used for both **Customer** and **User** — resolved: distinct concepts. **Customer** places orders; **User** is an authentication identity.
+- "transaction" sometimes meant **Order** and sometimes **Payment** — resolved: avoid the word entirely.
+```
+
+## Term schema
+
+Each row in the **Language** table:
+
+| Column | Required | Description |
+|--------|----------|-------------|
+| Term | ✅ | Bold, kebab-case-friendly singular noun (or short phrase) |
+| Definition | ✅ | One sentence. Defines what it IS, not what it does. |
+| Aliases to avoid | optional | Other words the team has used; agents and humans must avoid them in code, comments, and conversation |
+| Status | ✅ | `canonical` (settled) \| `pending` (waiting on domain-expert confirmation) \| `conflicted` (active disagreement, needs resolution) |
+
+## Update protocol
+
+### Inline sharpen (during a BA session)
+
+When the user uses a term whose meaning is ambiguous, propose a precise canonical version. When confirmed, update CONTEXT.md right there. Don't batch.
+
+> "You used 'account' twice — once meaning **Customer** (the person ordering), once meaning **User** (the login). I'll record these as distinct in CONTEXT.md."
+
+### Cross-reference (HARD-GATE)
+
+When the user asserts behavior — "the system cancels Orders when X" — `ba` MUST grep the codebase to verify before recording in CONTEXT.md. If grep contradicts the user, surface the conflict and ask which is canonical.
+
+> User: "Yes, partial cancellation is supported."
+> Agent (after grepping `src/orders/cancel.ts`): "The code path I see only handles full cancellation (`cancel(orderId)` returns `Order` with status `cancelled`, no partial-quantity argument). Either the code is incomplete, or partial cancellation isn't implemented yet. Which is the canonical behavior?"
+
+This gate stops AI agents from silently recording user-asserted behavior that contradicts the code — a frequent source of "the docs say X but the code does Y" drift.
+
+### Conflict gate
+
+When a new term has ≥0.7 token overlap with an existing one, force a user choice:
+
+| Choice | Action |
+|--------|--------|
+| Merge | Combine the new term's aliases into the existing entry |
+| Rename | Pick a distinct slug for the new term |
+| Keep distinct | Confirm the overlap is coincidental; record both |
+
+Agents must NOT silently re-define existing terms.
+
+## Single vs multi-context
+
+**Single context (most repos)**: one `CONTEXT.md` at the repo root.
+
+**Multiple contexts**: a `CONTEXT-MAP.md` at the root lists where each context lives:
+
+```markdown
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+
+## Relationships
+
+- **Ordering → Billing**: Ordering emits `OrderPlaced` events; Billing consumes them
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+`ba` infers structure:
+- If `CONTEXT-MAP.md` exists → multi-context; read it to find the right CONTEXT.md
+- If only root `CONTEXT.md` exists → single-context
+- If neither exists → silent skip; create root CONTEXT.md lazily on first term resolution
+
+## What does NOT belong in CONTEXT.md
+
+- Generic programming concepts (timeouts, error types, function signatures) — these aren't domain terms.
+- Module / class names — they belong in code, not glossary, unless they have meaning to a domain expert.
+- Implementation details — CONTEXT.md is the *what* (concept), not the *how* (data shape).
+
+Before adding a term, ask: would a non-engineer domain expert recognize this and care? If no, don't add it.
+
+## Relationship to CLAUDE.md
+
+CLAUDE.md describes *how to work in this repo* — conventions, danger zones, deploy commands. CONTEXT.md describes *what these words mean* — the domain glossary. The scopes are mutually exclusive; never duplicate.