Quality-first architecture refactor + strict contracts + docs/CI hardening

.github/CODEOWNERS

@@ -0,0 +1,15 @@
+# Core architecture and contracts
+/src/core/ @clopca
+/src/contracts/ @clopca
+/src/search/ @clopca
+/src/modes/ @clopca
+/src/ai/ @clopca
+
+# Adapter surfaces
+/src/adapters/ @clopca
+
+# Governance and CI
+/.github/workflows/ @clopca
+/scripts/ @clopca
+/docs/architecture/ @clopca
+/docs/engineering/ @clopca

.github/platform-adapter-runbook.md

@@ -1,87 +1,46 @@
 # Platform Adapter Runbook
 
-This runbook covers operational startup, verification, and troubleshooting for Claude Code/Cursor adapter workers and compatibility validation.
+This runbook covers startup, verification, and troubleshooting for Claude Code and Cursor adapter workers.
 
 ## Scope
 
 - Adapter workers: `open-mem-claude-code`, `open-mem-cursor`
-- Bridge transports: stdio + optional HTTP
-- External compatibility evidence workflow and release gate
+- Bridge transports: stdio and optional HTTP
+- Runtime diagnostics and smoke validation
 
-## Startup (Ops-Safe)
+## Startup
 
 1. Build binaries:
    - `bun run build`
 2. Enable adapters:
    - `OPEN_MEM_PLATFORM_CLAUDE_CODE=true`
    - `OPEN_MEM_PLATFORM_CURSOR=true`
-3. Start workers (one process per platform):
+3. Start workers:
    - `bunx open-mem-claude-code --project /path/to/project`
    - `bunx open-mem-cursor --project /path/to/project`
-4. Optional HTTP mode for bridge checks:
+4. Optional HTTP mode:
    - `bunx open-mem-claude-code --project /path/to/project --http-port 37877`
 
-## Verification Workflow
+## Verification
 
-1. Run external verification harness:
-   - `bun run compat:verify --artifacts-dir artifacts/external-compat`
-   - Auto-detect installed client versions and run verification:
-   - `bun run compat:verify:auto --artifacts-dir artifacts/external-compat`
-2. Render matrix from latest report:
-   - `bun run compat:matrix`
-3. Run worker bridge smoke checks:
-   - `bun run compat:smoke --artifacts-dir artifacts/external-compat`
-4. Check release gate:
-   - `bun run compat:gate`
-
-## Evidence Contract
-
-Each verification run must produce:
-
-- `external-compat-report.json`
-- `transcripts/<client>/<scenario>.jsonl`
-- `logs/<client>.log`
-- `summary.md`
-- `checksums.txt`
-
-CI bundles these as `external-compat-<run-id>.zip`.
-
-## Failure Taxonomy
-
-### `CLIENT_PROTOCOL_DRIFT`
-
-- Trigger: MCP lifecycle/JSON-RPC mismatch.
-- Remediation: patch MCP compatibility handling; add/update transcript fixtures; rerun verify.
-
-### `WORKER_BRIDGE_REGRESSION`
-
-- Trigger: `health`/`flush`/`shutdown` semantics or bridge transport failures.
-- Remediation: patch `src/platform-worker.ts`; rerun smoke script; add targeted integration regression.
-
-### `ENVIRONMENT_DEPENDENCY`
-
-- Trigger: missing client binaries/version metadata on runner.
-- Remediation: fix runner provisioning and version export (`OPEN_MEM_CLAUDE_CODE_VERSION`, `OPEN_MEM_CURSOR_VERSION`).
-
-### `NON_DETERMINISTIC_OUTPUT`
-
-- Trigger: unstable output/transcript causing assertion flake.
-- Remediation: normalize volatile fields and tighten deterministic assertions.
+1. Run integration tests:
+   - `bun test tests/integration/platform-worker.test.ts`
+   - `bun test tests/integration/platform-parity.test.ts`
+2. Validate API/queue/runtime checks:
+   - `bun run quality:gate`
+   - `bun run test:servers`
+3. If HTTP bridge is enabled, verify worker status endpoint:
+   - `curl http://localhost:37877/v1/health`
 
 ## Troubleshooting
 
-- `ENV_MISSING_DIST_*`: run `bun run build` before verification scripts.
-- `STALE_REPORT`: regenerate report with `compat:verify`; commit updated `docs/compatibility/external-compat-latest.json`.
-- `MATRIX_MISMATCH`: run `compat:matrix` and commit updated `docs/mcp-compatibility-matrix.md`.
-- `CLIENT_VERSION_UNKNOWN`: run `bun run compat:detect-versions` to inspect what is detected, then ensure relevant CLI/app is installed on the runner.
-- Worker HTTP failures: verify port availability and local firewall constraints on runner host.
-
-## Soak Procedure (7-Day)
-
-- Run `external-compat` workflow nightly for 7 consecutive days.
-- Publish weekly soak summary file:
-  - `docs/compatibility/soak-YYYY-MM-DD.md`
-- GA requires:
-  - 7 successful runs,
-  - p95 targets met (`MCP < 250ms`, `worker ingest < 100ms`),
-  - failure rate < 1%.
+- Worker not ingesting events:
+  - Ensure adapter env flag is enabled.
+  - Ensure input is newline-delimited JSON.
+  - Check for `UNSUPPORTED_EVENT` or `INVALID_JSON` responses.
+- HTTP bridge not responding:
+  - Confirm port availability.
+  - Confirm process is running.
+- Queue not draining:
+  - Check `/v1/health` and `/v1/metrics`.
+  - Run diagnostics endpoint: `GET /v1/diagnostics`.

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+-
+
+## Quality Gates
+
+- [ ] `bun run typecheck`
+- [ ] `bun run lint`
+- [ ] `bun run check:boundaries`
+- [ ] `bun run quality:gate`
+
+## Change Checklist
+
+### API
+- [ ] Shared schema updated (if needed)
+- [ ] Contract tests updated
+- [ ] Docs updated
+
+### Storage
+- [ ] Migration compatibility validated
+- [ ] Data integrity checks added/updated
+
+### Adapters
+- [ ] No duplicated business logic introduced in adapters
+- [ ] Contract conformance preserved across MCP/HTTP/OpenCode
+
+### Governance
+- [ ] ADR linked for structural changes

.github/workflows/architecture-health.yml

@@ -0,0 +1,25 @@
+name: architecture-health
+
+on:
+  schedule:
+    - cron: "0 7 1 * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Install
+        run: bun install
+      - name: Generate report
+        run: bun run report:architecture > architecture-health.json
+      - name: Upload report
+        uses: actions/upload-artifact@v4
+        with:
+          name: architecture-health
+          path: architecture-health.json

.github/workflows/ci.yml

@@ -13,8 +13,18 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - name: Install
         run: bun install
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Lint
+        run: bun run lint
       - name: Boundaries
         run: bun run check:boundaries
+      - name: Contract Drift
+        run: bun run check:contracts
+      - name: Architecture Fitness
+        run: bun run check:architecture
+      - name: Migration Compatibility
+        run: bun run check:migration
       - name: Quality Gate
         run: bun run quality:gate
       - name: Tests

.github/workflows/nightly-matrix.yml

@@ -0,0 +1,22 @@
+name: nightly-matrix
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+jobs:
+  structural-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Install
+        run: bun install
+      - name: Run nightly checks
+        run: |
+          bun run typecheck
+          bun run check:boundaries
+          bun run check:contracts
+          bun run check:architecture
+          bun run quality:gate

.github/workflows/release-gate.yml

@@ -6,12 +6,26 @@ on:
   workflow_dispatch:
 
 jobs:
-  compat-gate:
+  quality-gate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v2
       - name: Install
         run: bun install
-      - name: External compatibility release gate
-        run: bun run compat:gate
+      - name: Typecheck
+        run: bun run typecheck
+      - name: Lint
+        run: bun run lint
+      - name: Boundaries
+        run: bun run check:boundaries
+      - name: Contract Drift
+        run: bun run check:contracts
+      - name: Architecture Fitness
+        run: bun run check:architecture
+      - name: Migration Compatibility
+        run: bun run check:migration
+      - name: Quality Gate
+        run: bun run quality:gate
+      - name: Test Suite
+        run: bun run test:repo

docs/.vitepress/config.ts

@@ -59,14 +59,16 @@ export default defineConfig({
 					{ text: "HTTP API", link: "/api" },
 					{ text: "Dashboard", link: "/dashboard" },
 					{ text: "Platform Adapters", link: "/platforms" },
-					{ text: "MCP Compatibility", link: "/mcp-compatibility-matrix" },
 				],
 			},
 			{
 				text: "More",
 				items: [
 					{ text: "Privacy & Security", link: "/privacy" },
 					{ text: "Troubleshooting", link: "/troubleshooting" },
+					{ text: "Quality Gates", link: "/engineering/quality-gates" },
+					{ text: "Deprecation Policy", link: "/engineering/deprecation-policy" },
+					{ text: "Technical Debt Policy", link: "/engineering/technical-debt-policy" },
 					{ text: "Changelog", link: "/changelog" },
 					{
 						text: "Contributing",

docs/api.md

@@ -277,6 +277,56 @@ Response:
 }
 ```
 
+### Readiness
+
+```
+GET /v1/readiness
+```
+
+Returns whether the system is ready to serve memory operations, plus reasons when not ready.
+
+### Diagnostics
+
+```
+GET /v1/diagnostics
+```
+
+Runs setup diagnostics (provider config, adapter enablement, db path, dashboard config).
+
+### Tools Guide
+
+```
+GET /v1/tools/guide
+```
+
+Returns canonical tool workflow guidance and contract metadata.
+
+### Queue Status
+
+```
+GET /v1/queue
+```
+
+Operator endpoint for queue state. Localhost access only.
+
+### Trigger Queue Processing
+
+```
+POST /v1/queue/process
+```
+
+Triggers one queue processing batch. Localhost access only.
+
+Response:
+
+```json
+{
+  "data": { "processed": 4 },
+  "error": null,
+  "meta": {}
+}
+```
+
 ### Metrics
 
 ```