Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,15 @@ export function createMyHook(ctx: PluginContext) {
8. **Minimal comments** - Only document non-obvious logic.
9. **Atomic commits** - Keep changes focused and small.

## Stage-Gated Verification

Verification is split across two inspect-only roles, gated by lifecycle stage:

- `goop-wave-verifier` — execute phase, scoped to one wave at a time. Inspects the wave and records verification rows via `goop_write_wave` `verifications[]`; it never implements fixes. Gaps go back to the correctly tiered executor for remediation, then the wave is re-verified.
- `goop-verifier` — acceptance only. Runs at the accept gate as the final whole-workflow audit against the spec; it is not dispatched during execute.

A wave does not complete, and execute does not progress to accept, while the wave's effective verification evidence is missing or failing.

## Agent Thinking Levels

GoopSpec supports per-role reasoning-effort configuration through plain-text labels. The system resolves each label against the live OpenCode model catalog — never a hard-coded budget table.
Expand Down Expand Up @@ -281,7 +290,7 @@ Input is case-insensitive and normalized to canonical lowercase. Unknown labels

### Built-in Role Defaults

Defined in `src/core/constants.ts` (lines 140-146):
Defined in `src/core/constants.ts` (lines 140-146). The canonical `AGENT_ROLES` list has 15 roles; the defaults below are derived from it:

| Role(s) | Default Level |
|---------|---------------|
Expand Down
14 changes: 13 additions & 1 deletion packages/opencode-plugin/references/phase-gates.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ Mandatory checkpoints that enforce workflow discipline. No phase proceeds until
|------|----------|-------------|-------------|
| Discovery | Before `/goop-plan` | `interview_complete == true`, `requirements` document exists in DB (`goop_read_db({ doc_type: "requirements" })` returns content) | Orchestrator |
| Spec | Before `/goop-execute` | `spec_locked == true`, `spec` document exists in DB, at least one wave row exists (via `goop_read_wave`), 100% traceability | Orchestrator |
| Execution | Before `/goop-accept` | All waves and tasks complete, verification passing, no blockers | Orchestrator |
| Wave Verification | Each wave during `/goop-execute` | Tasks complete → wave-scoped verifier evidence → remediation on gaps → non-failing effective evidence before completion | Orchestrator |
| Execution | Before `/goop-accept` | All waves and tasks complete, final whole-workflow verification passing, no blockers | Orchestrator |
| Acceptance | Within `/goop-accept` | Verification passed, user explicitly accepts | Orchestrator |

## Gate Semantics
Expand All @@ -30,6 +31,17 @@ Specification must be locked before execution.
→ Run: `/goop-plan`
```

## Wave Verification Gate

Each wave carries its own verification gate before it can be marked complete and before execute can progress to accept:

1. **Tasks complete** — every task in the wave is done per the wave plan.
2. **Wave-scoped verifier evidence** — the orchestrator dispatches `goop-wave-verifier` scoped to that wave (one wave per dispatch; inspect/report-only, never implements fixes). The verifier records evidence rows via `goop_write_wave` `verifications[]`.
3. **Bounded remediation and re-verification** — on gaps, the orchestrator dispatches the correctly tiered executor to remediate, then re-dispatches `goop-wave-verifier` for that wave. The remediation cycle is bounded by the three-strikes convention in `references/test-authoring.md` §Test Execution Discipline: after three failed attempts on the same gap, open a blocker via `goop_blocker` and stop.
4. **Completion and progression** — the wave completes, and execute progresses to accept, when its effective verification evidence is non-failing (at least one recorded check, and every check's latest recorded row is `pass` or an explicit `skip`). The runtime enforces this boundary: `goop_write_wave` rejects a complete-status transition without it, and auto-progression blocks execute→accept until the gate holds.

Acceptance remains a distinct final whole-workflow audit: after every wave has passed its own gate, `goop-verifier` inspects the finished workflow against the spec at the accept gate.

## Bypass Policy

| Gate | Bypass Allowed | Conditions |
Expand Down
5 changes: 3 additions & 2 deletions packages/opencode-plugin/references/wiring-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,8 @@ Before marking a feature complete:
- [ ] **Exports** — public API re-exported from the package entry point.
- [ ] **Config plumbing** — new options read by at least one consumer with observable effect.
- [ ] **Documentation** — new agents, skills, or references listed in `AGENTS.md` or equivalent.
- [ ] **Verification gate** — the wave carries a non-failing verification row (`goop_write_wave` `verifications[]`) before it is marked complete or handed off.
- [ ] **Verification gate** — the wave carries a current non-failing verification row (`goop_write_wave` `verifications[]`; the effective per-check state is the latest row per `check_name`) before it is marked complete or handed off.
- [ ] **Acceptance visibility** — per-wave verification rows are surfaced to the acceptance audit (`goop_acceptance_audit` returns combined `{blockers, verifications, waves}`), so the accept gate can see evidence for every wave.
- [ ] **Build** — `bun run build` succeeds and includes new files in output.
- [ ] **Discovery** — new resource appears in listing tools.

Expand Down Expand Up @@ -125,7 +126,7 @@ Mandatory handoffs at phase completion, wave completion, checkpoint reached, or
### Handoff Rules

- Include tasks completed, key decisions with rationale, exact workflow position, files modified, and explicit next steps.
- At wave completion, the wave verification gate precedes the handoff: `goop-wave-verifier` records a non-failing row for the wave before `HANDOFF.md` marks it complete. A handoff never substitutes for the recorded gate.
- At wave completion, the wave verification gate precedes the handoff: `goop-wave-verifier` records a current non-failing row for the wave before `HANDOFF.md` marks it complete. A handoff never substitutes for the recorded gate.
- Do not include full file contents or detailed implementation code.
- Keep the context summary to 2-4 sentences max.
- Update chronicle via `goop_write_db({ doc_type: "chronicle", content: "..." })` before generating `HANDOFF.md`.
Expand Down
194 changes: 194 additions & 0 deletions packages/opencode-plugin/src/core/tools-v2.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
import { createTools } from "../tools/index.js";
import { convertToolArgsToJsonSchema, registerToolsV2 } from "./tools-v2.js";
import type {
V2JsonSchema,
V2RuntimeContext,
V2ToolCapability,
V2ToolDefinition,
Expand Down Expand Up @@ -126,3 +127,196 @@ describe("registerToolsV2()", () => {
});
});
});

// ---------------------------------------------------------------------------
// Host-visible required-array contract (W4.T4)
//
// HOST-CONVERSION BOUNDARY: this block pins the JSON Schema the PLUGIN hands
// to the host through the V2 conversion path (convertToolArgsToJsonSchema →
// z.toJSONSchema from Zod v4). Host-side V1 conversion — the host running its
// own z.toJSONSchema (or the older zod-to-json-schema@3.x) over our Zod args
// — is OUTSIDE plugin control and has independent, documented defects:
// - opencode #20807: zod-to-json-schema@3.x is broken with Zod v4 and can
// emit a schema with no `properties` and no `required`.
// - opencode #13618: a missing `required` key on a schema that has
// `properties` is rejected by the Claude API.
// We cannot test what the host does with our schema after we hand it over.
// We CAN and DO pin here that the schema the plugin emits at its boundary is
// correct: every tool declares `properties`, and `required` contains exactly
// the intended identifiers and nothing else.
//
// Runtime validation (shared/write-mode.ts and the per-tool mode checks from
// W4.T2/T3) remains the real safety guarantee: even if a host-side conversion
// defect or a confused model sends an optional field as if it were required,
// the tool rejects the ambiguous payload with a one-shot actionable error
// before any mutation occurs. See goop-write-db/index.test.ts
// "one-shot error prevents an identical retry loop" for that regression.
//
// A note on `.default()`: Zod v4 deliberately includes a `.default(...)` field
// in the JSON Schema `required` array because the *parsed output* always
// carries a value (the default). difftastic's `checkOnly` is therefore
// correctly listed below — this is distinct from the patch-field leakage
// defect, where a bare `.optional()` field (no default) must never appear.
// ---------------------------------------------------------------------------

describe("convertToolArgsToJsonSchema() — host-visible required-array contract", () => {
const contractContexts: PluginContext[] = [];

afterEach(() => {
for (const context of contractContexts.splice(0)) {
context.db.close();
}
});

// Expected top-level `required` array for EVERY tool returned by
// createTools(). Update an entry ONLY when intentionally changing a tool's
// argument contract. Two failure modes are deliberate:
// - A new tool added to createTools() without an entry here fails the
// "every tool has a contract entry" test.
// - A schema change that drifts requiredness fails the per-tool
// properties+required test.
// Both force an explicit, reviewed contract update.
const EXPECTED_REQUIRED: Record<string, string[]> = {
ast_grep: ["pattern", "language"],
background_cancel: ["job_id"],
background_command: ["command"],
background_status: [],
// checkOnly is `.optional().default(false)` — see the .default() note above.
difftastic: ["checkOnly"],
generate_image: ["prompt"],
goop_acceptance_audit: [],
goop_adl: ["action"],
goop_append_chronicle: [],
goop_blocker: [],
goop_boot: [],
goop_checkpoint: ["action"],
goop_compact: ["next_step"],
goop_create_pr: ["title", "body", "branch"],
goop_dashboard: [],
goop_get_global_config: [],
goop_infer_intent: ["transcript"],
goop_query_decisions: [],
goop_read_db: [],
goop_read_section: ["doc_type"],
goop_read_wave: [],
goop_reference: [],
// All create + patch fields are optional; runtime enforces per-mode rules.
goop_save_note: [],
goop_search_docs: ["query"],
goop_search_notes: [],
goop_setup: ["action"],
goop_spec: ["action"],
goop_state: ["action"],
goop_status: [],
goop_timeline: [],
goop_write_db: ["doc_type"],
goop_write_section: ["doc_type"],
goop_write_wave: [],
memory_forget: [],
memory_save: ["title", "content"],
memory_search: ["query"],
scip: ["action"],
slashcommand: ["command"],
};

function requiredOf(schema: V2JsonSchema): string[] {
return (schema.required as string[] | undefined) ?? [];
}

function itemElementRequired(schema: V2JsonSchema, arrayProp: string): string[] {
const properties = schema.properties as Record<string, V2JsonSchema | undefined> | undefined;
const arraySchema = properties?.[arrayProp];
const elementSchema = arraySchema?.items as V2JsonSchema | undefined;
return requiredOf(elementSchema ?? {});
}

it("every createTools() entry has an explicit expected-required contract entry", () => {
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const toolNames = Object.keys(createTools(ctx)).sort();
const expectedNames = Object.keys(EXPECTED_REQUIRED).sort();

// Catches a new tool added to createTools() without a contract entry, and
// a stale entry left behind after a tool is removed.
expect(toolNames).toEqual(expectedNames);
});

it("every tool's converted schema declares properties and matches its pinned required array", () => {
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const tools = createTools(ctx);

for (const [name, definition] of Object.entries(tools)) {
const schema = convertToolArgsToJsonSchema(definition.args);

// opencode #20807: a host conversion defect can strip `properties`
// entirely. Pin that the plugin-side conversion always emits the key as
// an object. A zero-argument tool (goop_get_global_config) legitimately
// emits `properties: {}`, so we require the key be an object, not that
// it be non-empty.
const properties = schema.properties as Record<string, unknown> | undefined;
expect(properties, `${name} must declare a properties object`).toBeDefined();
expect(typeof properties, `${name} properties must be an object`).toBe("object");
expect(properties, `${name} properties must not be null`).not.toBeNull();

// Zod v4's z.toJSONSchema OMITS the `required` key entirely when an
// object has no required fields (it does not emit `required: []`).
// That absent-key shape is the same one opencode #13618 documents as
// rejected by some providers — but forcing a present `required: []`
// would require a production change to the converter output, which is
// out of scope for this test-focused task. `requiredOf()` normalizes
// absence to `[]`, so the contract comparison is honest about what the
// plugin emits today; a future task that force-emits the key must
// update `requiredOf` or this assertion intentionally.
const expected = EXPECTED_REQUIRED[name].slice().sort();
const actual = requiredOf(schema).slice().sort();
expect(actual, `${name} required-array contract`).toEqual(expected);
}
});

it("no patch field (old_string/new_string/replace_all) appears in any tool's top-level required", () => {
// The defect this wave exists to prevent: an optional patch field leaking
// into `required` would force every caller to supply old_string/new_string,
// turning every full-document write into a silent patch call. Pin that no
// write tool's top-level schema ever requires a patch modifier.
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const tools = createTools(ctx);
const patchFields = ["old_string", "new_string", "replace_all"];

for (const [name, definition] of Object.entries(tools)) {
const schema = convertToolArgsToJsonSchema(definition.args);
const required = requiredOf(schema);
for (const field of patchFields) {
expect(required, `${name} must not require patch field '${field}'`).not.toContain(field);
}
}
});

it("goop_write_db items[] element requires only doc_type and omits patch fields from required", () => {
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_write_db.args);

expect(itemElementRequired(schema, "items").sort()).toEqual(["doc_type"]);
});

it("goop_write_section items[] element requires doc_type and section_key", () => {
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_write_section.args);

expect(itemElementRequired(schema, "items").sort()).toEqual(["doc_type", "section_key"]);
});

it("goop_save_note items[] element requires nothing (every field is optional)", () => {
const ctx = createMockPluginContext();
contractContexts.push(ctx);
const schema = convertToolArgsToJsonSchema(createTools(ctx).goop_save_note.args);

// No doc_type on note items; create fields and patch fields are all
// optional at the schema level and disambiguated at runtime. Pin that
// nothing leaked into required.
expect(itemElementRequired(schema, "items")).toEqual([]);
});
});
Loading