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

package/skills/basic/teamwork-preview/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: teamwork-preview
+description: Interactive 9-step prompt crafting and delegation protocol for autonomous multi-agent teams. Enforces objective verification, integrity modes, and acceptance criteria across Antigravity, Claude Code, Cursor, OpenCode, Codex, and Roo Code.
+category: bdb-core
+---
+
+# 🤝 Teamwork Preview — Multi-Agent Prompt Crafting & Delegation
+
+A structured workflow to turn high-level user ideas into robust, objectively verifiable multi-agent project specifications and delegate them cleanly to execution swarms.
+
+Two-phase workflow:
+1. **Interactive Prompt Crafting (Steps 1–9)**: Iteratively define project goals, eliminate ambiguity, select integrity modes, and enforce objective verification mechanisms.
+2. **Delegation**: Hand off the validated specification to the target multi-agent team or execution harness.
+
+---
+
+## ▶️ On Claude Code: run the script, don't narrate the protocol
+
+**Action:** call the `Workflow` tool with `scriptPath` set to
+`$HOME/.claude/workflows/teamwork-dispatch.mjs` — resolve `$HOME` yourself rather
+than hardcoding a username — and `args` set to whatever the user said after the
+command, passed through verbatim. If they said nothing, pass no `args`; step 1
+asks.
+
+Use `scriptPath`, not `name`. By-name lookup for a custom workflow script has been
+observed to fail with `Workflow "..." not found` even when the file exists and its
+`meta.name` matches.
+
+Then wait for the call to finish and relay its result — the draft path, the
+validation outcome, and any issues it reports. Do not summarise or reinterpret it.
+
+**Do NOT walk through the nine steps yourself in response to this skill.** The
+protocol below is the specification the script implements; it is not a set of
+instructions to follow inline. This repo has already paid for that mistake once,
+recorded in `skills/basic/startcycle-graph/SKILL.md`: an earlier version embedded
+its pipeline in prose, the model followed it "in spirit" instead of invoking the
+script, and the entire graph — subagents, state, review, quality gate — silently
+never ran. A 9-step protocol with integrity modes and acceptance criteria is
+exactly the shape of thing that gets approximated.
+
+If the `Workflow` tool is unavailable (some harnesses have none; Claude Code can
+have Dynamic Workflows switched off in `/config`), *then* run the protocol below
+manually, in order, one step at a time.
+
+## 🌐 Which harnesses get which
+
+| | |
+|---|---|
+| **Claude Code** | The script above. Deterministic: it runs or it doesn't. |
+| **Codex · Cursor · OpenCode · Roo · Antigravity** | The prose protocol below, interpreted by that harness's model. |
+
+The `.mjs` script depends on Claude Code's Dynamic Workflows runtime — the ambient
+`agent()` global and the `Workflow` tool. No other harness exposes an equivalent
+today, so the prose is not a fallback there, it is the implementation. Both are
+kept in this one file deliberately: two files would drift, and the drift would be
+invisible until someone on the other harness got different behaviour.
+
+**This is not Antigravity's `/teamwork-preview`.** That command is compiled into
+the `agy` binary, with its own conductor/orchestrator/auditor agent types, and is
+maintained by Google. This is an independent implementation of the same idea on a
+different runtime. It will behave differently, and it does not claim otherwise.
+
+---
+
+## 🧭 Core Principles
+
+| # | Principle | Rule |
+|---|---|---|
+| 1 | **Specify What, Not How** | Define requirements and acceptance criteria. Never prescribe implementation details (file structure, algorithms, libraries) unless the user explicitly mandates them. |
+| 2 | **Objective Verification** | Every requirement needs an independent verification mechanism. Programmatic verification (tests, assertion scripts, CLI benchmarks) is preferred; explicit agent-as-judge rubrics are accepted when programmatic testing is impossible. |
+| 3 | **Acceptance Criteria = Guardrails** | Acceptance criteria serve as the quality bar to prevent premature self-certification of incomplete or broken work. |
+| 4 | **Minimal Requirements** | Only specify what the user explicitly cares about. Give the agent team maximal solution space. |
+
+---
+
+## 📋 Artifact-Based Workflow
+
+Maintain a **prompt draft artifact** (`prompt_draft.md`) throughout the interaction. It provides real-time visibility to the user and tracks step progression.
+
+```markdown
+# Teamwork Project Prompt — Draft
+
+> Status: Step 1 — Eliciting project idea
+> Goal: Craft prompt → get user approval → delegate
+> Requested team: [none — routes automatically from description]
+
+[Project description — 1-2 sentences]
+
+Working directory: [TBD]
+Integrity mode: [development | demo | benchmark]
+
+## Requirements
+
+### R1. [TBD]
+
+### R2. [TBD]
+
+## Acceptance Criteria
+
+### [Category]
+- [ ] [Objective condition checkable without subjective bias]
+
+---
+*Next: when approved → delegate via execution protocol*
+```
+
+---
+
+## 🔄 The 9-Step Interactive Workflow
+
+### Step 1: Elicit the Idea
+- Ask: What do you want to build? What is the purpose (production, demo, eval, prototype)? Who is the audience?
+- Condense into a 1–2 sentence project description.
+- Initialize `prompt_draft.md` and set status to Step 2.
+
+### Step 2: Identify Ambiguity & Scale
+- Probe points with multiple reasonable interpretations (data sources, third-party services, scope limits).
+- Ask about effort and team scale:
+  - **Single self-contained fix/feature**: Keep focused (one implementer + repeated adversarial review). Prefix prompt: *"This is a single self-contained fix; keep it small and focused."*
+  - **Math, formal proofs, or massive search**: Offer standard pipeline vs. large-scale team. If large-scale selected, prefix prompt: *"Use a very large team of agents."*
+  - **Standard multi-agent build**: Standard workflow routes from task description.
+
+### Step 3: Determine Integrity Mode
+Clarify operational boundaries:
+- Can code be copied from existing open-source projects?
+- Are pre-built external libraries permitted for core logic?
+- Can test implementations be inspected before coding?
+- **Mapping**:
+  - Unrestricted / default → `integrity_mode: development`
+  - Some shortcuts allowed (demo showcase) → `integrity_mode: demo`
+  - Strict isolation / zero external leakage → `integrity_mode: benchmark`
+
+### Step 4: Draft Requirements (R1, R2, ...)
+- Write 2–5 concise requirement blocks.
+- Focus strictly on **what** is required, not **how** to implement it.
+- Apply litmus test: *"Would a senior engineer feel over-constrained by this requirement?"* If yes, prune.
+
+### Step 5: Design Verification Mechanisms (Forcing Function)
+> **Why this matters:** Verification is a forcing function. Its job is to create an objective test target that forces a genuine build → test → debug loop and prevents premature self-certification.
+
+- Design programmatic tests where feasible (unit test suites, test runners, CLI assertion scripts).
+- If programmatic tests are not feasible, draft an explicit agent-as-judge scoring rubric.
+- Inquire whether the user has existing test suites, schemas, or reference implementations to include in a `## Verification Resources` section.
+
+### Step 6: Set Acceptance Criteria
+- Convert verification mechanisms into checkable markdown checkboxes (`- [ ]`).
+- Calibrate strictly to the project purpose:
+  - Demo: Achievable within rapid time budget.
+  - Production: Full test coverage, strict error handling, production readiness.
+  - Eval: Strict reproducible metrics over polish.
+
+### Step 7: Infrastructure Constraints (If Applicable)
+- Define sandboxing or controlled APIs for remote file operations, job launching, and external network calls.
+- Skip if the project operates purely within local workspace files.
+
+### Step 8: Choose Working Directory
+- Confirm the target working directory (default: `~/teamwork_projects/{project_name}` or a relative path in the current repo).
+- Record as `Working directory: <path>` at top of prompt draft.
+
+### Step 9: Assemble, Validate & Seek Approval
+Assemble the final structured prompt:
+
+```markdown
+[1-2 sentence project description]
+
+Working directory: <path>
+Integrity mode: [development | demo | benchmark]
+[Optional: Team scaling directive]
+
+## Requirements
+
+### R1. [Primary Deliverable]
+[What it does, not how to build it]
+
+### R2. [Secondary Deliverable]
+[What it does, not how to build it]
+
+## Acceptance Criteria
+
+### [Category]
+- [ ] [Objective condition checkable without subjective bias]
+```
+
+**Pre-flight Checklist:**
+- [ ] No unsolicited implementation hints (file structures, algorithms).
+- [ ] Every acceptance criterion is objectively verifiable.
+- [ ] Scope matches actual user needs.
+- [ ] Team scale directive included if requested in Step 2.
+
+Seek explicit approval from the user before triggering execution.
+
+---
+
+## 🚀 Delegation Protocol
+
+Once approved by the user:
+
+### 1. In Antigravity Harness
+If running in Google Antigravity with native subagent support:
+- Call `invoke_subagent`:
+  - `TypeName`: `teamwork_preview`
+  - `Role`: `Teamwork Coordinator`
+  - `Prompt`: Full prompt content from `prompt_draft.md`
+- Set artifact status to `Launched`.
+
+### 2. In Other Agent Harnesses
+- **Claude Code**: Feed the finalized prompt to dynamic workflows or dispatch via `/startcycle-graph` / subagents.
+- **Cursor / Windsurf**: Inject the prompt into composer or project rules context.
+- **OpenCode / Codex CLI**: Pass the prompt to `opencode run` or Codex runner.

package/skills/bdbrainstorm/SKILL.md

@@ -16,9 +16,10 @@ You are strictly required to enforce the following 6 pillars in your process:
 - Instead of brainstorming alone, you MUST spawn specialized subagents (using `invoke_subagent`) to discuss ideas, architecture, and features.
 - Assign clear, distinct roles to subagents (e.g., "UI/UX Visionary", "Technical Architect", "Devil's Advocate") and have them debate and refine the concept before any code is written.
 
-### 2. The `/grill-me` Approach
-- Actively challenge the user's initial ideas.
-- Initiate a `/grill-me` style interactive interview to uncover blind spots, resolve design decisions, and align on a robust plan. Do not accept vague requirements. Ask deep, targeted questions.
+### 2. The Grilling Interview
+- **Invoke the `grill-with-docs` skill and follow it** — or `grill-me` when there is no working directory to leave a paper trail in. Do not paraphrase an interview here; those skills hold the protocol (design tree, frontier rounds, numbered questions each with a recommended answer), and a second description of it in this file would drift from the first.
+- Actively challenge the user's initial ideas. Do not accept vague requirements.
+- `grill-with-docs` additionally runs `domain-modeling`, so terminology and decisions settled during the debate land in `CONTEXT.md` and ADRs as they crystallise rather than evaporating with the session — which is usually what you want before a multi-agent build.
 
 ### 3. Target Folder Selection & Project Scaffolding
 - After the brainstorming and grilling phase produces a solid conceptual plan, you MUST explicitly ask the user: *"In which folder, workspace, or project directory should the output artifacts (e.g., plan, README.md, AGENTS.md) be stored?"*

package/skills/global_config/ask-tim/SKILL.md

@@ -1,12 +1,64 @@
 ---
 name: ask-tim
-description: Meta-skill for discovering and routing to the right skill out of the ~154 available options. Use when a user or agent is unsure which skill fits their intent, or needs to pick between overlapping choices (e.g. build pipelines, scraping tools, UI components).
+description: Ask which skill or flow fits your situation. A route through AOS's skills for work that travels idea to ship, plus a catalogue of the ~169 available options for lookup. Use when unsure where to start, or when picking between overlapping choices.
 category: bdb-core
+disable-model-invocation: true
 ---
 
-# `ask-tim`: The BDB Skill Routing Meta-Skill
+<!-- The flow map below is derived from mattpocock/skills' ask-matt (MIT, see
+     THIRD_PARTY_NOTICES.md). The route is AOS's own: most stations on
+     upstream's main flow have no AOS equivalent, so copying it verbatim would
+     have produced a router pointing at skills that do not exist. -->
 
-This is a discovery and routing guide. It does not perform work itself. Use it to map a user's intent to the correct specialized skill(s).
+# `ask-tim`: which way do I go?
+
+You don't remember every skill, so ask. This does no work itself.
+
+Two layers, answering different questions. **The flow map** answers *"which way?"* — the route work travels from an idea to something shipped, and which branch to take at each fork. **The catalogue** below it answers *"which skill?"* — grouped by domain, with overlap guidance for the cases where several look alike. Start with the flow; drop to the catalogue when you already know roughly where you are.
+
+---
+
+## The main flow: idea → ship
+
+The route most work travels.
+
+**1. Sharpen the idea.** `/grill-with-docs` whenever you are in a working directory — the interview *plus* a paper trail, writing settled terminology into `CONTEXT.md` and ADRs as it goes. Without a repo to write to, `/grill-me`. Both run the same `grilling` primitive; the difference is only whether the understanding survives the session.
+
+For a bigger or fuzzier idea, `/bdbrainstorm` runs the same interview inside a multi-agent debate (`/bdbmediastorm` for live show-control and event tech). Don't grill twice — those skills already do this step.
+
+**2. Branch: how much machinery does the build need?** This is the fork that matters, and picking wrong is expensive in both directions.
+
+- **`/startcycle`** — the linear chain, and the right answer for most daily work. Architect → TechLead → Build → Reviewer, hand-offs as plain files, no state machine.
+- **`/startcycle-graph`** — when you need the durable `state.json`, a Reviewer repair loop with a no-progress guard, an automated quality gate, and escalation to a human. Mission-critical or multi-session work. Runs headless.
+- **`/startcycle-graph-user`** — a throwaway 2–4 node fan-out for one-off parallel work. Nothing persistent left behind.
+- **Two-file edit?** No pipeline. Just do it.
+
+**3. Review the plan before it is built.** At the Architect→TechLead gate, `aos-plan-canvas open production_artifacts/00_execution_plan.md` opens the plan in a browser where you point at what should change instead of retyping it. Mandatory at the end of `/bdbrainstorm` and `/bdbmediastorm`; optional in `/startcycle`; deliberately not forced in `/startcycle-graph`, which runs headless.
+
+**4. Build, then review adversarially.** The pipelines invoke their own build and review nodes — you do not call these by hand. Reviewer's pass is a correctness check against the plan's contract; `godmode-shipping`'s gate is mechanical (lint, typecheck, tests). Two different checks, deliberately not merged.
+
+Reach for `test-driven-development` or `tdd-workflow` on their own when you want one behaviour built test-first without a whole pipeline, and `git-pr-review` when reviewing a branch or PR against a fixed point.
+
+**Forcing a specific skill into a run:** `--skill=<name>` on any startcycle variant makes it a hard requirement — for a private skill of your own no node would otherwise reach for. Validated before the run starts; a name that does not resolve halts rather than proceeding without it.
+
+---
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Issues piling up** → `/triage`. For work you did *not* create: bug reports, incoming requests, anything raw. Tickets a pipeline already produced are agent-ready — **do not triage them**.
+- **Something is broken** → `systematic-debugging` for a structured hunt, `debugger` for a plain error. Both refuse to theorise before there is a reproduction.
+- **You need a runnable answer, not an argument** → `/prototype`. Throwaway code to settle a question that conversation cannot, then bring what you learned back to the idea thread.
+- **Deploying or shipping infrastructure** → `godmode-shipping` gates a release; `bdb-deploy`, `vercel-deployment` and `cloudflare-workers-expert` do the actual shipping.
+
+---
+
+## What this flow does not cover
+
+Named so you don't go looking: AOS has no equivalent of a cross-session `handoff` file, and no `wayfinder`-style skill for charting a months-long effort as decision tickets. For work too large for one session, `/startcycle-graph`'s durable `state.json` is the closest thing — it is resumable, but it does not chart the fog for you.
+
+---
 
 ## 🧭 Intent Index (Table of Contents)
 
@@ -231,12 +283,27 @@ Specific utilities for the BDB environment.
 
 ## 🧊 Media & EventTech
 
-Use these for 3D, motion, and live show control.
+Use these for 3D, motion, video and live show control.
 
-* **Top Picks:** `godmode-eventtech`, `godmode-3d-creation`, `godmode-media-creation`
+* **Top Picks:** `godmode-media-creation` (video and montage), `godmode-eventtech` (live shows), `godmode-3d-creation` (meshes and scenes)
 
 * **Godmodes**: Determine the overarching flow (3D, Media, EventTech).
-* **Implementations**: `MCP_Manage` (Unreal, Rhino, Resolve, TouchDesigner), `spline-3d-integration` (web 3D), `threejs-skills` (WebGL).
+* **Implementations**: `MCP_Manage` drives the creative applications over MCP, `spline-3d-integration` (web 3D), `threejs-skills` (WebGL), `remotion` (React → MP4, deterministic frame counts).
+
+### Which video route?
+
+The choice is driven by where the pixels come from, not by the output format — all four end in a video file.
+
+| Source material | Route |
+|---|---|
+| Code-generated motion graphics, text, brand animation | `remotion` — React components rendered to MP4, deterministic and exactly frame-accurate |
+| Existing footage: cutting, colour, beat-sync | `godmode-media-creation` + `MCP_Manage` → **DaVinci Resolve** (`davinci-resolve-mcp`) or **Adobe Premiere** (`adobe_uxp_mcp`) |
+| Compositing, motion design over footage | `MCP_Manage` → **After Effects** (`ae-mcp`, `after-effects-mcp`), or **Photoshop** for stills (`adobe_uxp_mcp`) |
+| Generative visuals: audio-reactive, shaders, real-time | `godmode-eventtech` → TouchDesigner MCP, then `record_movie` |
+| Generative *assets*: text→3D, image→3D, AI video | The **Creator Extension** engines — TRELLIS and TripoSR (3D), Text-to-CAD, OpenMontage (multimodal montage), Video-Shotcraft (shot direction), Palmier-Pro (timeline and grading), driven through `comfyui-mcp`. Installed as a separate power-up module, not a skill in this catalogue. |
+| Concept not settled yet | `bdbmediastorm` first — it runs the grilling interview for show-control and media work |
+
+Resolve and Premiere are interchangeable at this level: pick whichever is actually installed. Both have a working MCP under `mcps/`.
 
 ---
 

package/skills/global_config/bdbresilience/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: bdbresilience
+description: Autonomous CI/CD error recovery, distributed file-based locking, diagnostic triage, and two-phase GO gate resilience engine for BDB Agent OS multi-agent pipelines.
+category: bdb-core
+triggers:
+  - error recovery
+  - transient error
+  - rate limit 429
+  - exponential backoff
+  - distributed lock
+  - lockfile
+  - concurrency control
+  - state race
+  - ci/cd triage
+  - log parser
+  - flaky test
+  - self-healing
+  - verification gate
+  - go gate
+  - two-phase gate
+capabilities:
+  - monitoring
+  - security
+  - context-management
+  - testing
+  - automation
+disable-model-invocation: false
+user-invocable: true
+---
+
+# 🛡️ BDB Resilience & Concurrency Engine (`/bdbresilience`)
+
+The `/bdbresilience` master skill suite provides deterministic runtime fault tolerance, concurrency coordination, diagnostic log triage, and pre-tool deployment gating for autonomous multi-agent pipelines operating across the BDB Agent OS ecosystem.
+
+---
+
+## 1. Core Tenets
+
+1. **Fail Deterministically, Recover Gracefully**: Never swallow errors silently or crash abruptly. Intercept all tool, network, and runtime faults through a 4-tier taxonomy (`transient`, `tool_level_fault`, `auth_credential`, `unrecoverable`). Execute structured recovery before attempting escalation.
+2. **Zero-Race Concurrency**: Shared mutable state—including `production_artifacts/state.json`, git branches, and worktrees—must never suffer lost updates or dirty reads. Enforce mutual exclusion through atomic POSIX/APFS file locking (`O_CREAT | O_EXCL`) or fragment isolation (`state.d/<nodeId>.json`).
+3. **No Hallucinated Triage**: Parse raw CI/CD logs directly (Vitest, Jest, tsc, ESLint, GitHub Actions). Extract verified file coordinates, line numbers, failure diffs, and exact root causes into structured JSON reports. Never synthesize speculative fixes without log verification.
+4. **Strict Two-Phase Gate Precedence**: High-consequence actions (`git push`, `npm publish`, `npm version`, recursive `rm`) require an uncompromised human verification gate. Enforce the BDB Pre-Tool Gate protocol: lock execution in strict read-only mode until a literal, isolated human token `"GO"` is validated.
+
+---
+
+## 2. When to Use vs. When to Exclude
+
+### ✅ When to Use
+- **External API & Network Flakiness**: Handling HTTP 429 rate limits, socket timeouts (`ETIMEDOUT`), connection resets (`ECONNRESET`), and temporary provider dropouts.
+- **Tool Failures with Fallbacks**: Automatically rerouting failed tool invocations to secondary providers (e.g., primary MCP down → secondary CLI fallback) with immutable diversion audit trails.
+- **Concurrent Agent Execution**: Protecting shared files (`state.json`), databases, or worktrees during parallel build node execution (Engineering, UI/UX, Media).
+- **CI/CD Pipeline Failures**: Ingesting build and test runner failure logs, distinguishing transient infrastructure errors from code regressions, and generating actionable repair proposals.
+- **Release Verification & Deployment**: Enforcing the two-phase approval gate prior to running destructive or outward-facing operations.
+
+### ❌ When to Exclude
+- **Single-Agent Read-Only Probes**: Reading static documentation, viewing local files, or querying local git status where no concurrency or network calls occur.
+- **Internal Synchronous Transforms**: Pure CPU operations, in-memory string formatting, or deterministic array manipulations without side effects.
+- **Explicit User-Directed Interrupts**: Direct manual cancellation or kill signals received from the operator.
+
+---
+
+## 3. Resilience Architecture & Operational Playbooks
+
+```
++---------------------------------------------------------------------------------------+
+|                               /bdbresilience Skill Suite                              |
+|                             Master Operational Architecture                           |
++-------------------------------------------+-------------------------------------------+
+                                            |
+        +-----------------------------------+-----------------------------------+
+        |                                                                       |
+        v                                                                       v
++---------------------------------------+     +-----------------------------------------+
+|      Pattern 1: Error Recovery        |     |     Pattern 2: Distributed Locking      |
+|  - 4-Tier Failure Classification      |     |  - POSIX Atomic Creation (O_CREAT|EXCL) |
+|  - Full Jitter Exponential Backoff    |     |  - Monotonic Fencing Tokens             |
+|  - Secondary Tool Router & Diversion  |     |  - Background Heartbeat Renewal         |
+|  - Fail-Closed Human Escalation       |     |  - Atomic Stale / Orphan Eviction       |
+|  [references/error-recovery.md]       |     |  [references/distributed-locking.md]    |
++---------------------------------------+     +-----------------------------------------+
+        |                                                                       |
+        +-----------------------------------+-----------------------------------+
+                                            |
+        +-----------------------------------+-----------------------------------+
+        |                                                                       |
+        v                                                                       v
++---------------------------------------+     +-----------------------------------------+
+|       Pattern 3: CI/CD Triage         |     |       Pattern 4: Two-Phase GO Gate      |
+|  - Multi-Runner ANSI Normalization    |     |  - Phase 1: Strict Read-Only Planning   |
+|  - Flaky vs Deterministic Classifier  |     |  - Phase 2: Literal Token Execution     |
+|  - JSON Diagnostic Report Schema      |     |  - Fail-Closed Transcript Scanner       |
+|  - isCleanRun() Pass Predicate        |     |  - Caller-Written approvals Ledger      |
+|  [references/cicd-triage.md]          |     |  [references/two-phase-go-gate.md]      |
++---------------------------------------+     +-----------------------------------------+
+```
+
+### Specialized Reference Guides
+- 📘 **[Error Recovery & Retry Routing](references/error-recovery.md)**: Taxonomy classification, Full Jitter backoff formula, diversion logging, and zero-hallucination escalation payloads.
+- 📘 **[Distributed Locking & Concurrency](references/distributed-locking.md)**: Atomic lockfile creation, lease TTLs, heartbeat renewal, atomic rename break eviction, and `state.json` protection.
+- 📘 **[CI/CD Self-Healing Triage](references/cicd-triage.md)**: Multi-runner log parsers, flaky vs. deterministic classifier, and structured JSON diagnostics.
+- 📘 **[Two-Phase Pre-Tool GO Gate](references/two-phase-go-gate.md)**: PreToolUse hook specifications, transcript token verification, and fail-closed gate mechanics.
+- 📘 **[Node Integration Contracts](contracts/nodes-integration.md)**: **PROPOSAL, not applied.** How Reviewer and Shipping *would* be equipped in `nodes.json`, plus hooks for `/startcycle-graph` and `/bdbrainstorm`. No AOS node carries `bdbresilience` today.
+
+---
+
+## 4. Operational Commands & Procedures
+
+### `/bdbresilience recover`
+Invokes the automated error classification and recovery pipeline for a failed operation.
+```typescript
+import { classifyError, withRetry, executeWithFallback } from 'bdb-cicd-resilience/recovery/index.js';
+
+// 1. Classify error
+const classification = classifyError(error, { toolName: 'api_fetch', attempt: 1 });
+
+// 2. Retry with full jitter if transient
+//    (withRetry classifies internally too, and rethrows at once on canRetry: false)
+if (classification.category === 'transient') {
+  const result = await withRetry(
+    () => callApi(),
+    { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 10000 }
+  );
+}
+
+// 3. Fallback route if tool fault. The fallback is a tool NAME; your execute
+//    function does the dispatch, and a canRetry:false classification suppresses
+//    the diversion instead of re-sending the call to a second provider.
+if (classification.category === 'tool_level_fault') {
+  const fallbackResult = await executeWithFallback({
+    originalTool: 'mcp_primary',
+    fallbackTool: 'cli_fallback',
+    execute: (toolName) => invokeTool(toolName, args),
+    auditFilePath: 'production_artifacts/diversions.jsonl',
+  });
+}
+```
+
+### `/bdbresilience lock`
+Coordinates exclusive access to a shared resource using deterministic atomic locking.
+```typescript
+import { withStateLock, withDistributedLock } from 'bdb-cicd-resilience/locking/index.js';
+
+// Guard state.json mutations
+await withStateLock('production_artifacts/state.json', (state) => {
+  state.artifacts.backend = 'production_artifacts/02_backend_schema.md';
+  state.findings.push({ id: 'F-ENG-01', status: 'fixed' });
+  return state;
+}, { ttlMs: 15000, acquireTimeoutMs: 10000 });
+```
+
+### `/bdbresilience triage`
+Parses build or test logs to isolate failures and propose fixes.
+```typescript
+import { generateDiagnosticReport, isCleanRun } from 'bdb-cicd-resilience/triage/index.js';
+
+const report = generateDiagnosticReport(rawBuildOutput, 'vitest');
+console.log(`Failures: ${report.summary.totalFailures} (Transient: ${report.summary.transientCount})`);
+if (isCleanRun(report)) {
+  // The ONLY sanctioned "it passed". `totalFailures === 0` alone is also true
+  // for an empty or unrecognised log (summary.parseStatus 'empty' / 'unparsed').
+} else if (report.summary.canAutoRetry) {
+  // Safe infrastructure retry
+} else {
+  // Escalate exact deterministic failure coordinates to engineer
+}
+```
+
+### `/bdbresilience gate`
+Evaluates pre-tool execution authorization against the conversation transcript.
+```typescript
+import { verifyGoGate, checkPreToolGate } from 'bdb-cicd-resilience/triage/index.js';
+
+const gate = checkPreToolGate('git push origin main', transcriptPath);
+if (!gate.allowed) {
+  throw new Error(`Gate Closed: ${gate.reason}. Reply with GO to unlock.`);
+}
+```
+
+---
+
+## 5. Common Rationalizations vs. Reality
+
+| Rationalization | Engineering Reality | Resilience Protocol |
+|-----------------|---------------------|---------------------|
+| *"A simple `setTimeout(1000)` retry is fine without jitter."* | Synchronous fixed backoffs cause thundering herds on rate-limited endpoints. | **Mandatory Full Jitter**: Sleep for $T = \text{random}(0, \min(T_{\max}, T_{\text{base}} \cdot 2^{\text{attempt}}))$. |
+| *"State file collisions won't happen because agents finish quickly."* | Parallel agent fan-out runs in separate processes; uncoordinated writes cause lost updates. | **Atomic POSIX Lock**: Use `open(..., 'wx')` with fencing tokens or isolated `state.d/<nodeId>.json` fragments. |
+| *"The test failed due to an intermittent CI glitch, let's ignore it."* | Masking real assertion failures as "flaky" leads to shipping broken code to production. | **Deterministic Classifier**: Only classify network/OOM/timeout as flaky; assertion and type errors must never be bypassed. |
+| *"The user said 'starte jetzt', so that counts as approval."* | Compound action verbs violate the two-phase safety protocol; user intent may be unconfirmed. | **Strict Literal Token**: Gate unlocks ONLY if the single trimmed word is `"GO"`. Fail-closed on everything else. |
+
+---
+
+## 6. Red Flags Checklist
+
+- [ ] **Hardcoded Delays**: Retrying without random jitter or exponential backoff.
+- [ ] **Missing Finally Block**: Acquiring a distributed lock without releasing in a `finally` block or relying on process exit.
+- [ ] **Unlink Without Verification**: Deleting a stale lockfile without checking process liveness (`process.kill(pid, 0)`) or using the atomic rename break protocol.
+- [ ] **Synthetic Error Hallucination**: Fabricating an error root cause when log parsing failed or was inconclusive.
+- [ ] **Soft Gate Bypass**: Proceeding with deployment when gate evaluation returned `allowed: false` or when transcript was missing.
+- [ ] **Sidechain Approval**: Permitting an automated subagent message (`isSidechain: true`) to satisfy human approval.
+
+---
+
+## 7. Verification & Testing Protocol
+
+To verify the `/bdbresilience` suite and its underlying TypeScript engine:
+
+```bash
+# 1. Typecheck TypeScript implementation
+npm run typecheck
+
+# 2. Compile to dist/ distribution
+npm run build
+
+# 3. Execute full unit, integration, and E2E verification
+npm test
+```