Write comprehensive troubleshooting guide for top 20 failure modes

docs/LIFECYCLE.md

@@ -66,6 +66,7 @@ stateDiagram-v2
     BLOCKED --> CANCELLED : manual cancel
 
     WAITING_FOR_SUBTASKS --> DONE : all subtasks completed
+    WAITING_FOR_SUBTASKS --> BLOCKED : subtask timeout escalation
     WAITING_FOR_SUBTASKS --> CANCELLED : manual cancel
 
     FAILED --> OPEN : retry (within max_retries)
@@ -110,6 +111,7 @@ is `_always` (unconditional). Any transition not in this table raises
 | BLOCKED | OPEN | Blocking dependency resolved |
 | BLOCKED | CANCELLED | Manual cancellation |
 | WAITING_FOR_SUBTASKS | DONE | All child subtasks completed |
+| WAITING_FOR_SUBTASKS | BLOCKED | Subtask timeout escalation (parent blocked waiting on unresponsive subtask) |
 | WAITING_FOR_SUBTASKS | CANCELLED | Manual cancellation |
 | FAILED | OPEN | Retry (respects `max_retries`, default 3) |
 | DONE | CLOSED | Janitor verification passed + branch merged |

docs/deployment-guide.md

@@ -147,6 +147,7 @@ jobs:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           BERNSTEIN_LOG_JSON: "true"
+          BERNSTEIN_NO_TUI: "true"    # disable interactive TUI in CI
 
       - name: Upload state artifacts
         if: always()
@@ -221,6 +222,7 @@ bernstein:
   variables:
     ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY   # set in GitLab CI/CD settings
     BERNSTEIN_LOG_JSON: "true"
+    BERNSTEIN_NO_TUI: "true"    # disable interactive TUI in CI
 
   artifacts:
     paths:
@@ -251,6 +253,7 @@ bernstein:
 
   variables:
     ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
+    BERNSTEIN_NO_TUI: "true"
     PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
 ```
 
@@ -323,6 +326,7 @@ VOLUME ["/workspace/.sdd"]
 
 ENV BERNSTEIN_BIND_HOST=0.0.0.0
 ENV BERNSTEIN_PORT=8052
+ENV BERNSTEIN_NO_TUI=true
 
 EXPOSE 8052
 

docs/openapi-reference.md

@@ -4,18 +4,24 @@ Bernstein exposes a task-server HTTP API on `http://127.0.0.1:8052` by default.
 
 ## Generating the spec
 
+Use the included script to regenerate `docs/openapi.json` from the FastAPI app
+definition without starting the server:
+
+```bash
+uv run python scripts/generate_openapi.py
+# Written docs/openapi.json  (216 paths, 87 schemas)
+```
+
+Run this after adding or modifying any API route, Pydantic model, or response
+schema, then commit the updated `docs/openapi.json`. The hosted
+`docs/api-reference.html` page (Redoc) reads the spec at load time, so the
+reference updates automatically once the JSON is committed.
+
+**Alternative — fetch from a running server:**
+
 ```bash
-# Start the server and fetch the spec
 bernstein run &
-curl -s http://127.0.0.1:8052/openapi.json > openapi.json
-
-# Or generate from code without starting the server
-uv run python -c "
-from bernstein.core.server import create_app
-import json, sys
-app = create_app()
-json.dump(app.openapi(), sys.stdout, indent=2)
-" > openapi.json
+curl -s http://127.0.0.1:8052/openapi.json > docs/openapi.json
 ```
 
 ## Core endpoints

docs/workflows/REGISTRY.md

@@ -26,6 +26,8 @@ Last updated: 2026-04-08
 | Event-sourced task transitions (CQRS) | `WORKFLOW-event-sourced-task-transitions.md` | Draft | Append-only event log per task; state derived by replaying events, not mutable status field |
 | Multi-tenant task isolation (ENT-001) | `WORKFLOW-multi-tenant-task-isolation.md` | Approved | v1.2 — tenant-scoped CRUD, backlog, metrics. Implementation guidance for WAL scoping, tenant audit, quota wiring. Open Qs resolved. |
 | Cluster node auth hardening (ENT-002) | `WORKFLOW-cluster-node-auth.md` | Approved | v1.2 — JWT auth for node reg/heartbeats. Implementation guidance for persistent revocation, user_id bypass fix, dead code cleanup, auth failure rate limiting. Open Qs resolved. |
+| Audit integrity on startup (ENT-003) | `WORKFLOW-audit-integrity-on-startup.md` | Draft | `verify_on_startup()` exists but is dead code — never called from orchestrator. Spec defines wiring pattern + insertion point. |
+| SOC 2 evidence export (ENT-004) | `WORKFLOW-soc2-evidence-export.md` | Draft | Raw JSONL export exists; spec adds control mappings (CC6.1, CC7.2), evidence summaries, Merkle attestation, structured formatting. |
 | Cluster task stealing (ENT-007) | `WORKFLOW-cluster-task-stealing.md` | Draft | Pull-based task stealing with CAS locking — missing assigned_node/pinned_node fields, cooldown not persisted |
 | Per-tenant rate limiting & quotas (ENT-008) | `WORKFLOW-tenant-rate-limiting-quota.md` | Draft | API rate limits, task/hour, agent concurrency, cost budget — TenantRateLimiter exists but not wired to middleware |
 
@@ -125,6 +127,18 @@ Config path: `cluster.steal` in `bernstein.yaml` (not yet parsed — hardcoded t
 
 Config path: `tenants:` and `rate_limit:` sections in `bernstein.yaml`
 
+### Audit integrity and compliance workflows
+
+- `src/bernstein/core/audit.py` — HMAC-chained append-only audit log
+- `src/bernstein/core/audit_integrity.py` — startup integrity verification (ENT-003)
+- `src/bernstein/core/audit_export.py` — SIEM export adapters (ENT-012)
+- `src/bernstein/core/compliance.py` — compliance presets, SOC 2 export (ENT-004)
+- `src/bernstein/core/merkle.py` — Merkle tree integrity seals
+- `src/bernstein/cli/audit_cmd.py` — CLI entry points for audit/seal/verify/export
+
+Config path: `.sdd/config/audit-key` (HMAC key), `.sdd/config/compliance.json` (preset)
+Data path: `.sdd/audit/*.jsonl` (daily logs), `.sdd/audit/merkle/` (seals)
+
 ### Review and quality workflows
 
 - `src/bernstein/core/cross_model_verifier.py`