Dukeabaddon · Dukeabaddon · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026
diff --git a/README.md b/README.md
@@ -361,6 +361,7 @@ See [Contributing](CONTRIBUTING.md) for the artifact-first workflow.
 - [API reference](docs/API.md)
 - [Adapter setup](docs/ADAPTERS.md)
 - [Current status](docs/STATUS.md)
+- [Production gate](docs/PRODUCTION_GATE.md)
 - [Security](SECURITY.md)
 - [Privacy](PRIVACY.md)
 

diff --git a/apps/web/components/copy-button.tsx b/apps/web/components/copy-button.tsx
@@ -33,4 +33,3 @@ export function CopyButton({
     </button>
   );
 }
-
diff --git a/apps/web/package.json b/apps/web/package.json
@@ -30,4 +30,3 @@
     "node": ">=24"
   }
 }
-
diff --git a/docs/PRODUCTION_GATE.md b/docs/PRODUCTION_GATE.md
@@ -0,0 +1,55 @@
+# Telic production gate
+
+Checklist for declaring **v0.2.0** production-ready preview. Every row must pass before tagging.
+
+**Last updated:** 2026-08-12
+
+## Trust boundary
+
+| #   | Criterion                                                                        | Verify                                                                               |
+| --- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| T1  | Broker hooks fail-closed when `TELIC_BROKER_STRICT=1` (default in adapter hooks) | `npm test -- packages/cli/src/broker-gate.test.ts test/cagt-broker-hook-e2e.test.ts` |
+| T2  | Hook denies when `telic` CLI is missing (strict)                                 | E2E or hook unit test                                                                |
+| T3  | README and STATUS state Telic does not cage the host without hooks               | Manual read                                                                          |
+
+## Maintainability
+
+| #   | Criterion                                                      | Verify                                                                     |
+| --- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| M1  | `intersectStructuredPermissions` has one implementation        | `rg intersectStructuredPermissions packages/core/src` shows one definition |
+| M2  | `controller.ts` facade under 1,500 lines; validators extracted | `wc -l packages/core/src/controller.ts`                                    |
+| M3  | Extracted validators have unit tests                           | `ls packages/core/src/controller/*.test.ts` or `validators/`               |
+
+## Quality
+
+| #   | Criterion                                | Verify                                                |
+| --- | ---------------------------------------- | ----------------------------------------------------- |
+| Q1  | Full test suite passes                   | `npm test`                                            |
+| Q2  | Adapter handshakes pass                  | `npm run adapters:validate`                           |
+| Q3  | Site builds (if web touched)             | `npm run site:check`                                  |
+| Q4  | Coverage run stable (ledger concurrency) | `npm test -- --coverage` three consecutive green runs |
+
+## Review
+
+| #   | Criterion                                         | Verify                   |
+| --- | ------------------------------------------------- | ------------------------ |
+| R1  | `/review` or equivalent on full diff vs `main`    | PR review notes          |
+| R2  | Bugbot triaged (fix or dismiss with reason)       | PR comments              |
+| R3  | Security review on broker + permissions (Phase 1) | security-review artifact |
+
+## Release
+
+| #   | Criterion                               | Verify                    |
+| --- | --------------------------------------- | ------------------------- |
+| S1  | `CHANGELOG.md` updated for v0.2.0       | File diff                 |
+| S2  | Workspace + `telic-mcp` version `0.2.0` | `package.json`            |
+| S3  | Git tag `v0.2.0` on `main`              | `git tag -l v0.2.0`       |
+| S4  | `main` CI green after merge             | `gh pr checks` or Actions |
+
+## Explicitly out of scope for v0.2.0
+
+- CAGT / protocol rewrite
+- Forensic-only FSM expansion beyond current ADRs
+- Adapter marketplace lifecycle certification
+- Parallel WorkPlan execution
+- Hosted service or telemetry
diff --git a/docs/PRODUCTION_PLAN/overview.md b/docs/PRODUCTION_PLAN/overview.md
@@ -0,0 +1,42 @@
+# Telic production readiness plan
+
+**Target:** v0.2.0 production-ready preview  
+**Repo:** Developer Tools (Telic)  
+**Base branch:** `main`
+
+## Context
+
+System review graded protocol and tests highly (S), but security posture (B) and controller complexity (C+) need work before a credible production tag. This plan sequences fixes without rewriting CAGT or the protocol.
+
+## Scope
+
+**In:** fail-closed broker, permission dedup, controller split, ledger hardening, optional storage GC, release gate.
+
+**Out:** CAGT redesign, forensic FSM expansion, new adapters, parallel workers.
+
+## Phases
+
+| Phase | Doc                                                | Branch                                | Playbook         |
+| ----- | -------------------------------------------------- | ------------------------------------- | ---------------- |
+| 0     | [phase-0-docs.md](./phase-0-docs.md)               | `feat/production-phase-0`             | multi-phase-plan |
+| 1     | [phase-1-broker.md](./phase-1-broker.md)           | `feat/production-phase-1-broker`      | feature          |
+| 2     | [phase-2-permissions.md](./phase-2-permissions.md) | `feat/production-phase-2-permissions` | refactoring      |
+| 3     | [phase-3-controller.md](./phase-3-controller.md)   | `feat/production-phase-3a` … `3c`     | refactoring      |
+| 4     | [phase-4-ledger.md](./phase-4-ledger.md)           | `feat/production-phase-4-ledger`      | bug-fix          |
+| 5     | [phase-5-storage.md](./phase-5-storage.md)         | `feat/production-phase-5-storage`     | feature          |
+| 6     | [phase-6-release.md](./phase-6-release.md)         | `release/v0.2.0`                      | shipping         |
+
+## Per-phase gate
+
+```text
+/freeze <scope>
+→ implement
+→ npm test && npm run adapters:validate
+→ /review + Bugbot (+ security-review on Phase 1)
+→ /ship PR
+→ merge when CI green
+```
+
+## Done predicate
+
+All rows in [PRODUCTION_GATE.md](../PRODUCTION_GATE.md) pass. Tag `v0.2.0` on `main`.
diff --git a/docs/PRODUCTION_PLAN/phase-0-docs.md b/docs/PRODUCTION_PLAN/phase-0-docs.md
@@ -0,0 +1,18 @@
+# Phase 0 — Production docs
+
+## Deliverables
+
+- `docs/PRODUCTION_GATE.md`
+- `docs/PRODUCTION_PLAN/overview.md` + phase files
+- README link to production gate
+
+## Exit criteria
+
+- [ ] All files exist
+- [ ] `npm test` still passes (docs only)
+
+## Verify
+
+```bash
+test -f docs/PRODUCTION_GATE.md && test -f docs/PRODUCTION_PLAN/overview.md
+```
diff --git a/docs/PRODUCTION_PLAN/phase-1-broker.md b/docs/PRODUCTION_PLAN/phase-1-broker.md
@@ -0,0 +1,40 @@
+# Phase 1 — Fail-closed broker
+
+## Goal
+
+When adapter hooks run with strict mode, deny risky tools if Telic cannot evaluate permissions.
+
+## Files
+
+- `packages/cli/src/broker-gate.ts`
+- `packages/cli/src/broker-gate.test.ts`
+- `adapters/cursor/project/.cursor/hooks/broker-gate.mjs`
+- `adapters/cline/project/.cline/hooks/broker-gate.mjs`
+- `adapters/roo-code/project/.roo/hooks/broker-gate.mjs`
+- `plugins/telic/hooks/broker-gate.mjs`
+- `test/cagt-broker-hook-e2e.test.ts`
+- `docs/STATUS.md`, `README.md`, `docs/ADAPTERS.md`
+
+## Data shape
+
+`HookPermissionResponse`: `{ permission: "allow" | "deny"; user_message?; agent_message? }`
+
+Strict mode via `TELIC_BROKER_STRICT=1` (set in hook scripts). Opt-out: `TELIC_BROKER_PERMISSIVE=1`.
+
+## Behavior changes
+
+1. Hook fallback when CLI missing → `deny` (strict).
+2. `evaluateBrokerGate`: when strict and mapped capability with no valid active session → `deny`.
+3. When strict and run version mismatch / not running → `deny` (not allow).
+
+## Exit criteria
+
+- PRODUCTION_GATE T1–T3
+- All tests pass
+
+## Verify
+
+```bash
+npm test -- packages/cli/src/broker-gate.test.ts test/cagt-broker-hook-e2e.test.ts
+npm run adapters:validate
+```
diff --git a/docs/PRODUCTION_PLAN/phase-2-permissions.md b/docs/PRODUCTION_PLAN/phase-2-permissions.md
@@ -0,0 +1,24 @@
+# Phase 2 — Permission dedup
+
+## Goal
+
+Single `intersectStructuredPermissions` in `packages/core/src/permissions.ts` (or dedicated module).
+
+## Files
+
+- New or extended `packages/core/src/permissions.ts`
+- `packages/core/src/controller.ts` (remove duplicate)
+- `packages/core/src/tool-broker.ts` (import shared)
+- Unit tests for intersection edge cases
+
+## Exit criteria
+
+- PRODUCTION_GATE M1
+- No behavior change (refactor only)
+
+## Verify
+
+```bash
+rg "function intersectStructuredPermissions" packages/core/src
+npm test -- packages/core
+```
diff --git a/docs/PRODUCTION_PLAN/phase-3-controller.md b/docs/PRODUCTION_PLAN/phase-3-controller.md
@@ -0,0 +1,27 @@
+# Phase 3 — Controller split
+
+## Goal
+
+Extract validators from `packages/core/src/controller.ts` without changing public API.
+
+## PR stack
+
+| PR  | Extract                              | Target file                                                           |
+| --- | ------------------------------------ | --------------------------------------------------------------------- |
+| 3a  | Evidence validation                  | `controller/evidence-validator.ts`                                    |
+| 3b  | Cross-artifact validation            | `controller/cross-artifact-validator.ts`                              |
+| 3c  | Work-plan + permission trace helpers | `controller/work-plan-validator.ts`, `controller/permission-trace.ts` |
+
+Facade remains `RunController` in `controller/index.ts` or slimmed `controller.ts`.
+
+## Exit criteria
+
+- PRODUCTION_GATE M2, M3
+- `full-flow-conformance.test.ts` passes
+
+## Verify
+
+```bash
+wc -l packages/core/src/controller.ts
+npm test -- packages/core test/full-flow-conformance.test.ts
+```
diff --git a/docs/PRODUCTION_PLAN/phase-4-ledger.md b/docs/PRODUCTION_PLAN/phase-4-ledger.md
@@ -0,0 +1,21 @@
+# Phase 4 — Ledger concurrency
+
+## Goal
+
+Fix flaky multi-worker ledger tests; make concurrency suite reliable in CI.
+
+## Files
+
+- `packages/core/src/ledger.test.ts`
+- `packages/core/src/sqlite-ledger.ts` (if race fix needed)
+
+## Exit criteria
+
+- PRODUCTION_GATE Q4
+
+## Verify
+
+```bash
+npm test -- packages/core/src/ledger.test.ts
+npm test -- --coverage
+```
diff --git a/docs/PRODUCTION_PLAN/phase-5-storage.md b/docs/PRODUCTION_PLAN/phase-5-storage.md
@@ -0,0 +1,25 @@
+# Phase 5 — Storage lifecycle
+
+## Goal
+
+`telic purge-run RUN_ID` and `telic gc` for orphan blob cleanup.
+
+## Files
+
+- `packages/cli/src/index.ts`
+- New `packages/cli/src/purge-run.ts`, `packages/cli/src/gc.ts`
+- Tests with `TELIC_STATE_DIR`
+- `docs/API.md`
+
+## Exit criteria
+
+- Commands documented and tested
+- Dry-run mode for `gc`
+
+## Verify
+
+```bash
+npm test -- packages/cli
+telic purge-run --help
+telic gc --help
+```
diff --git a/docs/PRODUCTION_PLAN/phase-6-release.md b/docs/PRODUCTION_PLAN/phase-6-release.md
@@ -0,0 +1,20 @@
+# Phase 6 — Release v0.2.0
+
+## Goal
+
+Run [PRODUCTION_GATE.md](../PRODUCTION_GATE.md), tag, ship.
+
+## Steps
+
+1. Walk every gate row; record pass/fail.
+2. Bump version to `0.2.0` in workspace packages and `telic-mcp`.
+3. Update `CHANGELOG.md`.
+4. `/ship` → merge to `main`.
+5. Tag `v0.2.0`.
+6. `/land-and-deploy` + `/monitor` for website if applicable.
+7. `/document-release`.
+
+## Exit criteria
+
+- All PRODUCTION_GATE rows pass
+- `git tag -l v0.2.0`
diff --git a/docs/STATUS.md b/docs/STATUS.md
@@ -10,13 +10,13 @@ Telic is an executable, local source preview. It is suitable for development and
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Protocol        | Strict Zod v4 schemas for controller, intent, serial execution, evidence, release, and trace artifacts; canonical bodies use camelCase and `schemaVersion: "1.0"`        |
 | Controller      | Deterministic phase ordering, stage-aware verification preflight, one user-facing clarification, one contract revision, one shared remediation, and terminal reports     |
-| Topology (CAGT) | `micro`, `standard`, and `forensic` classification at `startRun`; EGEL promotes insufficient micro evidence to standard instead of terminal block               |
-| Tool broker       | `telic_check_tool_action` plus preview `telic broker-gate` hooks for Cursor, Cline, and Roo; host-native calls outside MCP remain unintercepted              |
-| Forensic replay   | `telic replay` CLI and `telic_replay_run` MCP inspector with digest verification; micro topology returns a degraded replay flag                               |
+| Topology (CAGT) | `micro`, `standard`, and `forensic` classification at `startRun`; EGEL promotes insufficient micro evidence to standard instead of terminal block                        |
+| Tool broker     | `telic_check_tool_action` plus preview `telic broker-gate` hooks for Cursor, Cline, and Roo; host-native calls outside MCP remain unintercepted                          |
+| Forensic replay | `telic replay` CLI and `telic_replay_run` MCP inspector with digest verification; micro topology returns a degraded replay flag                                          |
 | Persistence     | SQLite metadata/events plus immutable SHA-256-addressed JSON bodies; digest verification occurs on read                                                                  |
 | Context         | Bounded inventory; token-boundary path ranking; eight-file zero-score fallback cap; relevance/file/byte budgets; path, symlink, duplicate, and heuristic secret controls |
-| MCP             | Local STDIO server with eleven tools plus a host-neutral `telic_workflow` prompt                                                                                           |
-| CLI             | npm-packaged and source-built `doctor`, `status`, `trace`, `artifact`, `replay`, `broker-gate`, and `mcp` commands                                                                                |
+| MCP             | Local STDIO server with eleven tools plus a host-neutral `telic_workflow` prompt                                                                                         |
+| CLI             | npm-packaged and source-built `doctor`, `status`, `trace`, `artifact`, `replay`, `broker-gate`, and `mcp` commands                                                       |
 | Host package    | Codex reference plugin plus seven experimental source packs generated from one canonical skill and MCP bundle                                                            |
 | Model access    | None in the runtime; the active host model authors semantic artifacts                                                                                                    |
 | Network service | None required; normal transport is local STDIO                                                                                                                           |
Original file line number	Diff line number	Diff line change
Expand Up		@@ -33,4 +33,3 @@ export function CopyButton({
		</button>
		);
		}