diff --git a/README.md b/README.md index 6911794..6df7000 100644 --- 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 index d90d4c8..cd96a54 100644 --- a/apps/web/components/copy-button.tsx +++ b/apps/web/components/copy-button.tsx @@ -33,4 +33,3 @@ export function CopyButton({ ); } - diff --git a/apps/web/package.json b/apps/web/package.json index 638fecf..b7e24e1 100644 --- 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 new file mode 100644 index 0000000..bfe5e52 --- /dev/null +++ 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 new file mode 100644 index 0000000..d51f59a --- /dev/null +++ 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 +→ 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 new file mode 100644 index 0000000..3cbc241 --- /dev/null +++ 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 new file mode 100644 index 0000000..7b09338 --- /dev/null +++ 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 new file mode 100644 index 0000000..e64483c --- /dev/null +++ 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 new file mode 100644 index 0000000..d16fac6 --- /dev/null +++ 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 new file mode 100644 index 0000000..671d9ce --- /dev/null +++ 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 new file mode 100644 index 0000000..0d2edf8 --- /dev/null +++ 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 new file mode 100644 index 0000000..568ea0e --- /dev/null +++ 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 index c044f33..9449b81 100644 --- 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 |