diff --git a/docs/ai-guardrails/README.md b/docs/ai-guardrails/README.md index db405c171947..125a66ab6d8a 100644 --- a/docs/ai-guardrails/README.md +++ b/docs/ai-guardrails/README.md @@ -127,21 +127,32 @@ Bootstrap the first thin-distribution slice that keeps OpenCode upstream-friendl 1. Freeze architecture decisions in ADRs. 2. Land the thin-distribution bootstrap as the first issue-sized slice. 3. Keep scenario coverage in the same change set as runtime behavior. -4. Stack later issues for plugin policy, safe workflows, provider lanes, and replay coverage on top of this base. +4. Establish the MVP floor explicitly before broadening into later maturity work. +5. Stack later issues for plugin policy, safe workflows, provider lanes, replay coverage, and authoritative release gates on top of this base. + +## MVP readiness split + +The remaining work is intentionally split into two stages: + +- `now required before MVP claim`: `#5`, `#6`, `#7`, and `#13` +- `later, after MVP floor`: `#14` and `#12` + +The detailed rationale lives in `docs/ai-guardrails/mvp-readiness.md`. Future sessions should start there before expanding issue scope. ## Tracking - Epic: [#1](https://github.com/Cor-Incorporated/opencode/issues/1) -- Current issue: [#4](https://github.com/Cor-Incorporated/opencode/issues/4) +- MVP readiness epic: [#16](https://github.com/Cor-Incorporated/opencode/issues/16) +- Current issue: [#15](https://github.com/Cor-Incorporated/opencode/issues/15) - Future slices remain separate issues so implementation can stay one issue per pull request. Issue `#2` is the merged bootstrap base. -Issue `#4` is complete only when: +Issue `#15` is complete only when: -- the plugin brief is committed and linked from the issue pack -- repo docs explain the plugin MVP in terms of the same canon -- scenario coverage proves the plugin loads and exercises the intended hooks +- the repo has a written MVP readiness register +- missing local issue briefs for the open workstreams are committed +- GitHub issue structure matches the same `now` versus `later` split - future implementation work can point back to this source canon instead of relying on memory ## Session rule @@ -159,6 +170,7 @@ When continuing this work in future sessions: - ADRs: `docs/ai-guardrails/adr/` - Issue briefs: `docs/ai-guardrails/issues/` +- MVP readiness: `docs/ai-guardrails/mvp-readiness.md` - Migration inventory: `docs/ai-guardrails/migration/` - Scenario tests: `packages/opencode/test/scenario/` - Thin distribution package: `packages/guardrails/` diff --git a/docs/ai-guardrails/issues/004-safe-agents-and-commands.md b/docs/ai-guardrails/issues/004-safe-agents-and-commands.md new file mode 100644 index 000000000000..11da4ece3c56 --- /dev/null +++ b/docs/ai-guardrails/issues/004-safe-agents-and-commands.md @@ -0,0 +1,36 @@ +# Issue 004: Safe Agents And Workflow Commands + +## Problem + +Raw built-in agents are too permissive for an internal product. The repo needs a safer default operating model for implementation, review, and release workflows. + +This issue is part of the MVP floor. It should not absorb later CI or broader migration scope. + +## Deliverables + +- hardened default primary agent +- review-oriented subagent +- slash commands for `/implement`, `/review`, `/ship`, and `/handoff` +- explicit permission policy for dangerous shell patterns and write operations + +## Acceptance + +- default agent is not an unrestricted build clone +- review workflow can run without edit access +- release workflow cannot bypass explicit gates +- the scope stays limited to local runtime workflow safety, not later CI/release authority + +## Dependencies + +- `003-guardrail-plugin-mvp.md` +- `docs/ai-guardrails/mvp-readiness.md` +- `docs/ai-guardrails/migration/claude-code-skills-inventory.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` +- https://opencode.ai/docs/agents +- https://opencode.ai/docs/commands +- https://opencode.ai/docs/config diff --git a/docs/ai-guardrails/issues/005-provider-admission-policy.md b/docs/ai-guardrails/issues/005-provider-admission-policy.md new file mode 100644 index 000000000000..a047136b1507 --- /dev/null +++ b/docs/ai-guardrails/issues/005-provider-admission-policy.md @@ -0,0 +1,35 @@ +# Issue 005: Provider Admission Policy + +## Problem + +The internal distribution needs a stable provider strategy that does not tie product decisions to one transient model name. + +This issue is part of the MVP floor because the product needs a concrete answer for confidential-code routing before it can honestly be described as an MVP. + +## Deliverables + +- lane policy for `zai`, `openai`, and `openrouter` +- provider allowlist and denylist defaults +- evaluation checklist for OpenRouter-backed candidates +- confidential-repo restrictions for preview, free, or data-collecting models + +## Acceptance + +- provider defaults are expressed in config, not only in prose +- evaluation lane is separate from standard defaults +- policy references official routing and data controls, not assumptions + +## Dependencies + +- `docs/ai-guardrails/adr/002-provider-admission-lanes.md` +- `docs/ai-guardrails/mvp-readiness.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` +- OpenRouter provider routing docs +- OpenAI pricing and model docs +- Z.AI pricing docs +- https://opencode.ai/docs/config diff --git a/docs/ai-guardrails/issues/006-scenario-and-replay-harness.md b/docs/ai-guardrails/issues/006-scenario-and-replay-harness.md new file mode 100644 index 000000000000..11f1f5ac448e --- /dev/null +++ b/docs/ai-guardrails/issues/006-scenario-and-replay-harness.md @@ -0,0 +1,34 @@ +# Issue 006: Scenario And Replay Harness + +## Problem + +Guardrails are only credible if config precedence, plugin behavior, and migration compatibility are exercised automatically. + +This issue is part of the MVP floor because the philosophy from epic `#130` treats runtime proof as a requirement, not a follow-up. + +## Deliverables + +- scenario tests for guarded workflow commands +- scenario tests for provider admission behavior +- scenario tests for plugin state and carry-over that matter to MVP claims +- follow-up replay strategy for release-gate and provider-admission scenarios + +## Acceptance + +- scenario suite runs under `packages/opencode` +- the tests are stable on local development machines and CI +- future guardrail issues can link to specific scenario or replay coverage + +## Dependencies + +- `003-guardrail-plugin-mvp.md` +- `004-safe-agents-and-commands.md` +- `005-provider-admission-policy.md` +- `docs/ai-guardrails/mvp-readiness.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` +- `packages/opencode/test/scenario/guardrails.test.ts` diff --git a/docs/ai-guardrails/issues/007-plugin-hardening-wave-2.md b/docs/ai-guardrails/issues/007-plugin-hardening-wave-2.md new file mode 100644 index 000000000000..f8fd3c489831 --- /dev/null +++ b/docs/ai-guardrails/issues/007-plugin-hardening-wave-2.md @@ -0,0 +1,39 @@ +# Issue 007: Plugin Hardening Wave 2 + +## Problem + +The plugin MVP in `003-guardrail-plugin-mvp.md` proves the extension surface, but it does not yet cover enough of the highest-value hook migration set to support an MVP claim by itself. + +## Deliverables + +- expand plugin policy to cover high-priority fast-feedback hooks from the migration inventory +- add crash-safe state/logging expectations where needed for local runtime continuity +- document which plugin behaviors are part of the MVP floor versus later operational hardening + +## Candidate scope + +- `post-lint-format` +- `block-version-downgrade` +- `context-budget-*` +- `mark-factcheck-done` +- `reset-factcheck` +- targeted review or fact-check runtime state where feasible without broad core patches + +## Acceptance + +- the plugin covers the highest-value remaining fast-feedback policies needed for MVP +- behavior is scenario-tested or otherwise runtime-verified +- scope remains thin-distribution-first and upstream-friendly + +## Dependencies + +- `003-guardrail-plugin-mvp.md` +- `006-scenario-and-replay-harness.md` +- `docs/ai-guardrails/mvp-readiness.md` +- `docs/ai-guardrails/migration/claude-code-skills-inventory.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` diff --git a/docs/ai-guardrails/issues/008-authoritative-ci-and-release-gates.md b/docs/ai-guardrails/issues/008-authoritative-ci-and-release-gates.md new file mode 100644 index 000000000000..4dc326a45261 --- /dev/null +++ b/docs/ai-guardrails/issues/008-authoritative-ci-and-release-gates.md @@ -0,0 +1,31 @@ +# Issue 008: Authoritative CI And Release Gates + +## Problem + +The local client can guide safe behavior, but merge, release, and post-merge authority must not depend on local agent goodwill alone. + +This issue is intentionally outside the MVP floor. It should stay separated from `004-safe-agents-and-commands.md` so the MVP scope does not expand indefinitely. + +## Deliverables + +- CI or provider-enforced review freshness gates +- release and post-merge verification policy +- documented split between local preflight checks and authoritative server-side gates + +## Acceptance + +- the repo documents which gates are local-only versus authoritative +- release-sensitive operations are enforced outside the local client +- the work remains separate from the local-runtime MVP floor + +## Dependencies + +- `004-safe-agents-and-commands.md` +- `006-scenario-and-replay-harness.md` +- `docs/ai-guardrails/mvp-readiness.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` diff --git a/docs/ai-guardrails/issues/009-broader-claude-asset-migration.md b/docs/ai-guardrails/issues/009-broader-claude-asset-migration.md new file mode 100644 index 000000000000..e46bc0c2472c --- /dev/null +++ b/docs/ai-guardrails/issues/009-broader-claude-asset-migration.md @@ -0,0 +1,30 @@ +# Issue 009: Broader Claude Asset Migration + +## Problem + +The MVP floor does not require full migration of every Claude-owned asset, but the longer-term product still needs a principled path for additional skills, commands, and packaging decisions. + +This issue is intentionally after the MVP floor. + +## Deliverables + +- next-wave migration candidates beyond the MVP floor +- ownership rules for moving assets from `.claude` into `.opencode` +- packaging and maintenance rules for org-owned assets after the MVP ships + +## Acceptance + +- the repo distinguishes MVP-critical migration from later migration work +- future asset moves can point to an explicit issue and ownership rule instead of ad hoc decisions + +## Dependencies + +- `002-claude-asset-inventory-and-import.md` +- `docs/ai-guardrails/mvp-readiness.md` +- `docs/ai-guardrails/migration/claude-code-skills-inventory.md` + +## Sources + +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` diff --git a/docs/ai-guardrails/issues/README.md b/docs/ai-guardrails/issues/README.md index 771db01c63e2..dd0e5099d9c0 100644 --- a/docs/ai-guardrails/issues/README.md +++ b/docs/ai-guardrails/issues/README.md @@ -10,6 +10,14 @@ These issue briefs are intentionally written as implementation slices that can b 4. `004-safe-agents-and-commands.md` 5. `005-provider-admission-policy.md` 6. `006-scenario-and-replay-harness.md` +7. `007-plugin-hardening-wave-2.md` +8. `008-authoritative-ci-and-release-gates.md` +9. `009-broader-claude-asset-migration.md` + +## MVP split + +- `004` to `007` define the MVP floor +- `008` and `009` are later maturity work and should not silently expand the MVP scope ## Working rule diff --git a/docs/ai-guardrails/migration/claude-code-skills-inventory.md b/docs/ai-guardrails/migration/claude-code-skills-inventory.md index eea84159a2ca..bc3a3d1a20a5 100644 --- a/docs/ai-guardrails/migration/claude-code-skills-inventory.md +++ b/docs/ai-guardrails/migration/claude-code-skills-inventory.md @@ -208,11 +208,14 @@ Bucket definitions: ## Immediate Implications For This Repo -- `Issue 001` should stay thin: wrapper, managed config, packaged profile. -- `Issue 002` is complete only when this inventory remains current and scenario coverage for `.claude/skills` stays green. -- `Issue 003` should focus on plugin rewrites that preserve fast feedback and system-level verifiability. -- `Issue 004` should turn command-bucket items into explicit safe workflows like `/implement`, `/review`, `/ship`, and `/handoff`. -- `Issue 005` should keep provider policy declarative and independent from one transient model brand. +- `001-bootstrap-thin-distribution` should stay thin: wrapper, managed config, packaged profile. +- `002-claude-asset-inventory-and-import` is complete only when this inventory remains current and scenario coverage for `.claude/skills` stays green. +- `003-guardrail-plugin-mvp` proved the runtime hook surface but not the full MVP floor. +- `004-safe-agents-and-commands` should turn command-bucket items into explicit safe workflows like `/implement`, `/review`, `/ship`, and `/handoff`. +- `005-provider-admission-policy` should keep provider policy declarative and independent from one transient model brand. +- `006-scenario-and-replay-harness` should prove the MVP floor in runtime scenarios, not just code review. +- `007-plugin-hardening-wave-2` should carry the next high-value plugin migrations that still block an MVP claim. +- `008-authoritative-ci-and-release-gates` and `009-broader-claude-asset-migration` are later maturity work and should not silently expand the MVP floor. ## What Success Looks Like diff --git a/docs/ai-guardrails/mvp-readiness.md b/docs/ai-guardrails/mvp-readiness.md new file mode 100644 index 000000000000..d7e5c2fa006e --- /dev/null +++ b/docs/ai-guardrails/mvp-readiness.md @@ -0,0 +1,127 @@ +# MVP Readiness Register + +This document defines the remaining work between the current guardrails slice and an honest MVP claim. + +The current state is not "production-ready." It is a verified thin-distribution base with a first guardrail plugin slice. That is enough to start the next implementation waves, but not enough to describe the system as a complete internal MVP yet. + +The split below is mandatory for future planning: + +- `now required before MVP claim`: work that must land before the product can be described as an MVP +- `later, after MVP floor`: work that materially improves safety or maturity, but should not be used to bloat the MVP floor + +## Current position + +What exists today: + +- thin wrapper distribution and managed profile +- Claude-compatible skill discovery proof +- first guardrail plugin slice for env injection, protected files, lifecycle logging, and compaction carry-over +- scenario coverage for the above + +What is still missing: + +- safe default operating workflows for implementation, review, ship, and handoff +- declarative provider lanes and confidential-code admission rules +- replayable scenario coverage for the next policy layers +- more of the high-value hook inventory moved into deterministic runtime mechanisms + +## Now Required Before MVP Claim + +These items define the MVP floor. If they are not complete, the product should still be described as "in progress" rather than "MVP". + +### `#5` Safe Agents And Workflow Commands + +Why it blocks MVP: + +- the current runtime still lacks the final guarded primary workflow surface +- implementation, review, ship, and handoff need explicit entrypoints so policy is not left to agent goodwill + +Required outcome: + +- guarded default primary agent +- review-safe subagent behavior +- slash commands for `/implement`, `/review`, `/ship`, and `/handoff` +- dangerous shell and write flows routed through explicit workflow gates + +### `#6` Provider Admission Policy + +Why it blocks MVP: + +- without provider lanes, the internal product does not yet have a stable answer for confidential code handling or evaluation traffic +- the README philosophy explicitly rejects product decisions tied to one transient model label + +Required outcome: + +- declarative provider lanes in config/profile +- allow/deny defaults for standard use versus evaluation use +- documented restrictions for preview, free, or data-collecting providers in confidential repos + +### `#7` Scenario And Replay Harness + +Why it blocks MVP: + +- the philosophy from epic `#130` requires runtime proof, not just implementation +- the current scenario suite proves the first slices, but not the later guarded workflows or provider lanes + +Required outcome: + +- stable scenario coverage for guarded commands, provider policy, and plugin behavior +- replay strategy for future release-sensitive checks without requiring deep forks + +### `#13` Plugin Hardening Wave 2 For MVP Floor + +Why it blocks MVP: + +- `#4` proved the plugin surface, but it did not yet migrate enough of the highest-value fast-feedback hooks +- the plugin still needs more of the mechanical guardrail layer before the runtime can be described as a coherent MVP + +Required outcome: + +- next high-value plugin migrations from the inventory +- context budget and version-baseline protections where feasible +- fact-check and review-state primitives where they materially improve the guarded workflows + +## Later, After MVP Floor + +These items should be tracked now, but they should not be allowed to endlessly delay the MVP floor. + +### `#14` Authoritative CI And Release Gates + +Why it is later: + +- local workflows and provider policy can still establish an MVP floor first +- this work is authoritative and necessary, but it belongs to the next maturity tier rather than the first local-runtime MVP + +Target outcome: + +- CI/provider-enforced review freshness +- release and post-merge verification outside the local client +- a clean split between local preflight and authoritative server-side gates + +### `#12` Broader Claude Asset Migration Beyond MVP Floor + +Why it is later: + +- the MVP does not require every Claude-owned asset to be repackaged +- the current strategy already prefers direct reuse and role-based migration over forced copying + +Target outcome: + +- next-wave ownership and packaging rules for org-owned assets +- deliberate moves from `.claude` to `.opencode` only when maintenance ownership is stable + +## Execution Rule + +When scoping future work: + +- if the task advances the guarded runtime needed to make an MVP claim, it belongs in the `now required` set +- if the task improves maturity without changing the MVP claim, keep it in the `later` set +- do not quietly absorb `later` scope into `#5`, `#6`, or `#7` + +## Sources + +- `docs/ai-guardrails/README.md` +- `docs/ai-guardrails/migration/claude-code-skills-inventory.md` +- `claude-code-skills` epic `#130` +- `claude-code-skills` README +- Anthropic `The Complete Guide to Building Skills for Claude` diff --git a/packages/guardrails/README.md b/packages/guardrails/README.md index c790f9201cc7..3f979dee80a4 100644 --- a/packages/guardrails/README.md +++ b/packages/guardrails/README.md @@ -51,10 +51,13 @@ Current contents focus on the first thin-distribution slice: Planned next slices are tracked in the fork: - epic [#1](https://github.com/Cor-Incorporated/opencode/issues/1) -- plugin MVP [#4](https://github.com/Cor-Incorporated/opencode/issues/4) +- MVP readiness epic [#16](https://github.com/Cor-Incorporated/opencode/issues/16) - safe agents and commands [#5](https://github.com/Cor-Incorporated/opencode/issues/5) - provider policy [#6](https://github.com/Cor-Incorporated/opencode/issues/6) - scenario/replay harness [#7](https://github.com/Cor-Incorporated/opencode/issues/7) +- plugin hardening wave 2 [#13](https://github.com/Cor-Incorporated/opencode/issues/13) +- post-MVP CI and release gates [#14](https://github.com/Cor-Incorporated/opencode/issues/14) +- post-MVP broader asset migration [#12](https://github.com/Cor-Incorporated/opencode/issues/12) ## Usage