opencode-overclock 0.3.0 → 0.5.0

package/src/workflow/templates/define.ts

@@ -0,0 +1,45 @@
+export const DEFINE_TEMPLATE = `---
+description: Interrogate requirements or synthesize formal SPEC.md using the grilling and domain-modeling protocols.
+---
+# Lifecycle Phase 1: Define
+
+You are conducting the Define phase for: $ARGUMENTS
+
+Assess current context before acting:
+- **Mode A: Interview (Grilling & Domain Modeling):** If requirements are broad, ambiguous, or unstated, conduct structured inquiry.
+- **Mode B: Synthesis (To-Spec):** If requirements, architecture, or features were ALREADY discussed and settled in conversation, do NOT restart interview rounds. Jump straight to synthesizing \`SPEC.md\`.
+
+---
+
+## Mode A: The Grilling & Domain Modeling Protocol
+Do NOT write production code. Act as a senior software architect interrogating requirements:
+
+1. **Discover Facts First:** Use tools (\`read\`, \`glob\`, \`grep\`) to inspect existing models, dependencies, and code conventions yourself. Never ask the user for information discoverable from the repository.
+2. **Challenge Overloaded Terms:** Align on ubiquitous language. If terms like "user" or "account" are ambiguous, sharpen them into canonical terms and record them in \`CONTEXT.md\`.
+3. **Dependency-Ordered Rounds:** Group questions on the unblocked decision frontier (max 3-4 numbered questions per turn). Resolve fundamental architecture (storage, security) before downstream details.
+4. **The Recommended Defaults Rule (➡️):** For EVERY question you ask, you MUST provide an opinionated default recommendation:
+   \`\`\`markdown
+   1. Where should idempotency keys be stored and for what TTL?
+      ➡️ **Recommended:** Redis cache with 24-hour TTL, matching session storage conventions.
+   \`\`\`
+   This allows the user to approve with "LGTM", "accept recommendations", or override individual points.
+5. **Establish 3-Tier Boundaries:**
+   - **Always Do:** Non-negotiables (invariants, validations, mandatory audit logs).
+   - **Ask First:** Irreversible actions (schema drops, payment operations, external contracts).
+   - **Never Do:** Prohibited anti-patterns (floating-point currency, skipping auth).
+
+---
+
+## Mode B: Specification Synthesis (Output: SPEC.md)
+Once requirements are clear, write or update \`SPEC.md\` (or the project's designated spec location):
+
+- **1. Problem Statement & Solution:** High-level problem and user-perspective solution.
+- **2. Ubiquitous Language:** Canonical domain terms from \`CONTEXT.md\`.
+- **3. User Stories & Acceptance Criteria:** Numbered list with verifiable Given/When/Then outcomes.
+- **4. Public Seams & Interfaces:** Explicit signatures, route types, and invariant contracts.
+- **5. 3-Tier Boundaries:** Always Do / Ask First / Never Do.
+- **6. Out of Scope (Non-Goals):** Concrete exclusions preventing scope creep.
+- **7. Verification Strategy:** Automated commands (tests, smoke runs) proving completion.
+
+Prompt the user to review and confirm \`SPEC.md\`. Once approved, direct them to run \`/plan\`.
+`

package/src/workflow/templates/diagnose.ts

@@ -0,0 +1,58 @@
+export const DIAGNOSE_TEMPLATE = `---
+description: Disciplined root-cause diagnosis loop with red-capable feedback loops, tagged logs, and regression guards.
+---
+# Lifecycle Phase 4: Diagnose
+
+Investigate and fix the reported bug or defect: $ARGUMENTS
+
+## Scope Check: Explanation vs Deep Investigation
+- **Explanation:** If the user is asking for a conceptual explanation of an error, provide a direct answer.
+- **Deep Investigation:** If diagnosing a defect, crash, flake, or regression, execute the 6-phase loop below.
+
+---
+
+## 0. Secret Redaction First
+Before displaying commands, outputs, or traces:
+- Replace credentials, authorization headers, tokens, and private keys with \`<REDACTED>\`.
+- Keep secrets in environment variables rather than command strings.
+
+---
+
+## The 6-Phase Diagnostic Loop
+
+### Phase 1: Construct the Tight Feedback Loop
+DO NOT speculate, theorize, or edit production code yet.
+Construct an automated command (unit test, curl, CLI invocation, or trace replay) that reliably triggers the failure.
+- **Deterministic:** Runs unattended and produces a clear pass/fail signal.
+- **Fast:** Executes in seconds.
+- **Flaky / Intermittent Defects:** Loop the trigger 50-100 times under load to raise the reproduction rate. A 40%-flake bug is debuggable; a 0.5% flake is not.
+- **Inaccessible Environments:** If missing credentials or remote environments prevent local repro, do NOT guess. State what is missing and ask the user for a sanitized HAR trace, log dump, or temporary staging instrumentation.
+
+### Phase 2: Reproduce & Minimise
+1. Run the loop and confirm Red: verify the failure matches the **user's actual symptom**.
+2. **Minimise:** Cut parameters, configurations, and data one at a time until every remaining line is load-bearing.
+
+### Phase 3: Ranked Falsifiable Hypotheses
+Formulate 3 to 5 distinct, ranked hypotheses. For each hypothesis, state its prediction:
+> _"If [Cause X] is the root cause, then [Changing Y] will resolve the failure, and [Changing Z] will worsen it."_
+
+### Phase 4: Instrument with Tagged Probes
+1. Test predictions changing ONE variable at a time.
+2. Tag all diagnostic logging with unique searchable tags:
+   \`\`\`ts
+   console.log("[DEBUG-d8a1] Received payload:", payload)
+   \`\`\`
+3. **Performance Regressions:** Do not use console logs (they distort timing). Measure with stable baselines first, bisect, and compare.
+
+### Phase 5: Fix & Permanent Regression Guard
+1. Write a permanent regression test at the public seam **before** the fix.
+   *(If the codebase architecture lacks a clean seam to test this bug, document it as an architectural finding).*
+2. Apply the minimal root-cause fix. Never paper over symptoms or swallow errors.
+3. Assert Green on the regression test.
+4. Re-run the Phase 1 loop against the full original scenario.
+
+### Phase 6: Clean Up & Verify
+1. Remove all \`[DEBUG-xxxx]\` logging statements (\`grep\` for the tag).
+2. Clean up temporary reproduction scripts.
+3. Run project linters and test suites to verify zero regressions.
+`

package/src/workflow/templates/plan.ts

@@ -0,0 +1,52 @@
+export const PLAN_TEMPLATE = `---
+description: Decompose SPEC.md into vertical tracer-bullet tasks in tasks/plan.md with dependency DAG.
+---
+# Lifecycle Phase 2: Plan
+
+You are decomposing \`SPEC.md\` (or agreed design) into an executable dependency plan for: $ARGUMENTS
+
+## Core Decomposition Principles
+
+1. **Prefactoring First:** Look for opportunities to refactor existing code before implementing new logic:
+   > _"Make the change easy, then make the easy change."_ (Kent Beck)
+   If prefactoring is needed, schedule it as Task 1 on the frontier.
+2. **Vertical Tracer Bullets:** Every task must cut a narrow but complete path through data, logic, interface, and tests. Avoid horizontal layer-by-layer batches (e.g. "all schemas first"). Each completed task delivers verifiable, working software.
+3. **Context-Sized Increments:** Size each task to fit cleanly in a fresh context window (~50-150 lines of focused diff). Small slices keep regressions visible and rollbacks painless.
+4. **Explicit Dependency DAG:** Every task must declare its blocking prerequisites (\`Blocked By: [task-ids]\`). Tasks with zero blockers form the "Ready Frontier".
+5. **Declared Public Seams:** Every task must specify the automated test file or assertion that will prove its completion.
+
+---
+
+## The Wide-Refactor Exception (Expand-and-Contract)
+
+If the change involves a **wide cross-cutting refactor** (e.g. renaming a ubiquitous symbol or schema column) where a single edit affects many files and cannot stay green as a single vertical slice:
+- **Phase A (Expand):** Add the new interface or column alongside the existing one. Both coexist; existing tests remain green.
+- **Phase B (Migrate):** Migrate callers in bounded batches (by package or directory). Each batch is a task blocked by Expand, keeping CI green.
+- **Phase C (Contract):** Once all callers use the new form, remove the old interface/column in a task blocked by all migration batches.
+
+---
+
+## Output Artifact: tasks/plan.md
+
+Create directory \`tasks/\` if needed, and write \`tasks/plan.md\`:
+
+\`\`\`markdown
+# Implementation Plan: [Feature Name]
+
+## Frontier (Ready to Execute)
+- [ ] **Task 1: [Short Title]**
+  - **Seam:** \`test/seam.test.ts\`
+  - **Scope:** [Vertical slice description]
+  - **Acceptance Criteria:** [Verifiable criteria]
+  - **Blocked By:** None
+
+## Sequence (Blocked)
+- [ ] **Task 2: [Short Title]**
+  - **Seam:** \`test/api.test.ts\`
+  - **Scope:** [Vertical slice description]
+  - **Blocked By:** Task 1
+\`\`\`
+
+Populate the session task tracking using \`todowrite\` matching the plan tasks.
+Prompt the user for confirmation. Once approved, the user can run \`/build\` (or \`/build auto\`).
+`

package/src/workflow/templates/ship.ts

@@ -0,0 +1,64 @@
+export const SHIP_TEMPLATE = `---
+description: Parallel 4-way pre-launch review (Standards, Spec, Security, QA) with GO/NO-GO verdict.
+---
+# Lifecycle Phase 5: Ship
+
+Pre-launch gatekeeper and multi-axis review for proposed changes: $ARGUMENTS
+
+## 1. Diff Evidence Resolution (Include Uncommitted Work)
+
+Do NOT assume changes are committed, and do NOT stage or commit user work just to make review convenient.
+Inspect the complete evidence set:
+1. **Working Tree Status:** Run \`git status --short\` to identify modified, staged, and untracked files.
+2. **Uncommitted Changes:** Run \`git diff HEAD\` (captures both staged and unstaged modifications).
+3. **Branch Commits:** If on a feature branch, run \`git diff origin/main...HEAD\` (or appropriate base branch).
+4. **Untracked Files:** Inspect new relevant files using \`git ls-files --others --exclude-standard\`.
+
+Assemble this complete diff into a coherent review packet so all subagents review the exact same snapshot.
+
+---
+
+## 2. Parallel 4-Way Subagent Audit
+
+Delegate review to the 4 specialized review subagents concurrently using the \`task\` tool. Running reviews in isolated context windows prevents cognitive bias and context dilution.
+
+Spawn the four subagents in parallel with the review packet:
+1. **Standards Reviewer (\`standards-reviewer\`):**
+   Evaluates the diff against repository conventions, Martin Fowler's code smells (Feature Envy, Primitive Obsession, Shotgun Surgery), and deep module principles. Read-only terminal worker.
+2. **Spec Reviewer (\`spec-reviewer\`):**
+   Evaluates the diff strictly against requirements in \`SPEC.md\` (or task brief). Flags missing acceptance criteria, incomplete edge cases, and unrequested scope creep. Read-only terminal worker.
+3. **Security Auditor (\`security-auditor\`):**
+   Adversarial audit of diffs for OWASP Top 10 vulnerabilities, credential/secret leaks, improper input sanitization, and authorization bypasses. Read-only terminal worker.
+4. **Test Engineer (\`test-engineer\`):**
+   Audits test coverage gaps, assertion quality (Beyoncé Rule, independent oracles), mocking boundaries, and Prove-It verification. Read-only terminal worker.
+
+---
+
+## 3. Synthesis & Decision Gate
+
+Synthesize findings from all subagents into a structured pre-launch report:
+
+\`\`\`markdown
+# Pre-Launch Review Summary
+
+## 1. Standards & Code Smells: [PASS | WARN | FAIL]
+(Analysis of architectural leverage, idioms, and code smells)
+
+## 2. Spec Compliance: [PASS | WARN | FAIL]
+(Verification against acceptance criteria; verification of zero scope creep)
+
+## 3. Security & Boundaries: [PASS | WARN | FAIL]
+(OWASP analysis, secret hygiene, input sanitization)
+
+## 4. Test Strategy & Coverage: [PASS | WARN | FAIL]
+(Verification rigor, edge cases, mocking boundaries)
+
+---
+## Final Verdict: [GO / NO-GO]
+- **Blocking Issues:** (Must be resolved before shipping)
+- **Non-Blocking Suggestions:** (Technical debt to track for later)
+- **Rollback Plan:** (Explicit instructions for reverting if production fails)
+\`\`\`
+
+**Authorization Boundary:** A GO verdict is an advisory quality gate. It is NOT authorization to commit, push, or deploy without explicit human approval.
+`

package/src/buddy/reactions.ts

@@ -1,41 +0,0 @@
-import type { SpriteState } from "./sprites.ts"
-
-export type ReactionKind = "done" | "error" | "permission" | "question" | "pet"
-
-/** Speech-bubble line + which face the sprite pulls while it shows. */
-export interface Reaction {
-  text: string
-  state: SpriteState
-}
-
-// Lines render into the sprite's 12-col effect row -- keep every line <= 12 chars.
-const POOLS: Record<ReactionKind, { lines: string[]; state: SpriteState }> = {
-  done: { lines: ["done!", "all set.", "ship it.", "*stretch*"], state: "idle" },
-  error: { lines: ["uh oh.", "*winces*", "yikes."], state: "alarmed" },
-  permission: { lines: ["can we?", "*peeks*", "please?"], state: "curious" },
-  question: { lines: ["your call.", "hmm?", "*head tilt*"], state: "curious" },
-  pet: { lines: ["<3", "*purrs*", "hi!!", "missed you."], state: "pet" },
-}
-
-/** Pure: pick a random line for a reaction kind. */
-export function pickReaction(kind: ReactionKind, rng: () => number = Math.random): Reaction {
-  const pool = POOLS[kind]
-  return { text: pool.lines[Math.floor(rng() * pool.lines.length)]!, state: pool.state }
-}
-
-export interface ReactionGate {
-  /** True + arms the cooldown if enough time has passed since the last fire. */
-  tryFire(now?: number): boolean
-}
-
-/** Debounce for event-driven reactions -- keeps a busy session from spamming the bubble. */
-export function createReactionGate(cooldownMs = 8000): ReactionGate {
-  let last = -Infinity
-  return {
-    tryFire(now: number = Date.now()): boolean {
-      if (now - last < cooldownMs) return false
-      last = now
-      return true
-    },
-  }
-}

package/src/buddy/types.ts

@@ -1,30 +0,0 @@
-export const SPECIES = [
-  "cat",
-  "dog",
-  "bunny",
-  "owl",
-  "bat",
-  "penguin",
-  "duck",
-  "ghost",
-  "slime",
-] as const
-export type Species = (typeof SPECIES)[number]
-
-export type Rarity = "common" | "uncommon" | "rare" | "legendary"
-
-export interface CompanionStats {
-  patience: number
-  chaos: number
-  wisdom: number
-  snark: number
-}
-
-/** Persisted in TUI kv. Rolled once at hatch, then stable for the life of the install. */
-export interface Companion {
-  species: Species
-  rarity: Rarity
-  name: string
-  stats: CompanionStats
-  hatchedAt: number
-}

package/src/config.ts

@@ -1,19 +0,0 @@
-import type { OverclockConfig } from "./types.ts"
-
-const CONFIG_PATHS = [".opencode/overclock.json", "overclock.json"]
-
-/** Load plugin config from project dir. Missing file -> {} (all defaults). */
-export async function loadConfig(directory: string): Promise<OverclockConfig> {
-  for (const rel of CONFIG_PATHS) {
-    const file = Bun.file(`${directory}/${rel}`)
-    if (await file.exists()) {
-      try {
-        return (await file.json()) as OverclockConfig
-      } catch (e) {
-        console.warn(`[overclock] bad config ${rel}: ${e}`)
-        return {}
-      }
-    }
-  }
-  return {}
-}

package/src/features/checkpoints.ts

@@ -1,128 +0,0 @@
-import { tool, type PluginInput } from "@opencode-ai/plugin"
-import type { FeatureModule } from "../types.ts"
-
-const z = tool.schema
-
-type Client = PluginInput["client"]
-
-interface MessagePart {
-  type: string
-  text?: string
-}
-
-interface MessageEntry {
-  info: {
-    id: string
-    role: string
-    time?: { created?: number }
-  }
-  parts: MessagePart[]
-}
-
-const collapse = (s: string) => s.replace(/\s+/g, " ").trim()
-
-/** Exported for tests: revert/unrevert/list core, decoupled from plugin ctx. */
-export interface Checkpoints {
-  list(sessionID: string): Promise<string>
-  revert(sessionID: string, messageID: string): Promise<string>
-  restore(sessionID: string): Promise<string>
-}
-
-export function createCheckpoints(client: Client): Checkpoints {
-  async function list(sessionID: string): Promise<string> {
-    try {
-      const res = await client.session.messages({ path: { id: sessionID } })
-      const msgs = ((res.data ?? []) as MessageEntry[]).filter((m) => m.info.role === "user")
-      if (!msgs.length) return "no checkpoints"
-      return msgs
-        .map((m) => {
-          const time = m.info.time?.created
-            ? new Date(m.info.time.created).toISOString()
-            : "unknown time"
-          const text = m.parts.find((p) => p.type === "text" && typeof p.text === "string")?.text ?? ""
-          const preview = collapse(text).slice(0, 60)
-          return `${m.info.id} ${time} ${preview}`
-        })
-        .join("\n")
-    } catch (e) {
-      console.warn(`[overclock] checkpoints: list failed (session ${sessionID}): ${e}`)
-      return `error listing checkpoints: ${e}`
-    }
-  }
-
-  async function revert(sessionID: string, messageID: string): Promise<string> {
-    try {
-      await client.session.revert({ path: { id: sessionID }, body: { messageID } })
-      return `reverted session ${sessionID} to before message ${messageID}`
-    } catch (e) {
-      console.warn(
-        `[overclock] checkpoints: revert failed (session ${sessionID}, message ${messageID}): ${e}`,
-      )
-      return `error reverting checkpoint: ${e}`
-    }
-  }
-
-  async function restore(sessionID: string): Promise<string> {
-    try {
-      await client.session.unrevert({ path: { id: sessionID } })
-      return `restored session ${sessionID} to latest (undo revert)`
-    } catch (e) {
-      console.warn(`[overclock] checkpoints: restore failed (session ${sessionID}): ${e}`)
-      return `error restoring checkpoint: ${e}`
-    }
-  }
-
-  return { list, revert, restore }
-}
-
-/**
- * Shadow-git revert tools (map doc: "Checkpoints — none gap"). Wraps native
- * session.revert/unrevert around each user message as a revert point.
- */
-export const checkpoints: FeatureModule = {
-  name: "checkpoints",
-  tools: ["checkpoint_list", "checkpoint_revert", "checkpoint_restore"],
-  defaultEnabled: true,
-  requires: ["session.revert", "session.unrevert", "session.messages"],
-  async init(ctx) {
-    const core = createCheckpoints(ctx.client)
-
-    return {
-      tool: {
-        checkpoint_list: tool({
-          description:
-            "List user messages of a session as revert points: messageID, time, first 60 chars. Most recent last.",
-          args: { sessionID: z.string().optional().describe("default: current session") },
-          async execute(args, tctx) {
-            return core.list(args.sessionID ?? tctx.sessionID)
-          },
-        }),
-        checkpoint_revert: tool({
-          description:
-            "Revert session files + conversation back to before the given message (shadow-git, reversible via checkpoint_restore). Requires user permission.",
-          args: {
-            messageID: z.string(),
-            sessionID: z.string().optional().describe("default: current session"),
-          },
-          async execute(args, tctx) {
-            const sessionID = args.sessionID ?? tctx.sessionID
-            await tctx.ask({
-              permission: "checkpoint_revert",
-              patterns: [args.messageID],
-              always: [],
-              metadata: { sessionID, messageID: args.messageID },
-            })
-            return core.revert(sessionID, args.messageID)
-          },
-        }),
-        checkpoint_restore: tool({
-          description: "Undo the most recent checkpoint_revert for a session.",
-          args: { sessionID: z.string().optional().describe("default: current session") },
-          async execute(args, tctx) {
-            return core.restore(args.sessionID ?? tctx.sessionID)
-          },
-        }),
-      },
-    }
-  },
-}

package/src/features/sandbox.ts

@@ -1,104 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import type { FeatureModule } from "../types.ts"
-import { shellQuote } from "../lib/state.ts"
-
-const z = tool.schema
-
-export interface SandboxPolicy {
-  project: string
-  net: boolean
-}
-
-/** Pure: wrap shell cmd in bwrap. / ro, project + /tmp rw, net per policy. */
-export function wrapCommand(cmd: string, policy: SandboxPolicy): string {
-  const args = [
-    "bwrap",
-    "--ro-bind / /",
-    "--dev /dev",
-    "--proc /proc",
-    `--bind ${shellQuote(policy.project)} ${shellQuote(policy.project)}`,
-    "--bind /tmp /tmp",
-    "--die-with-parent",
-  ]
-  if (!policy.net) args.push("--unshare-net")
-  args.push("bash -c", shellQuote(cmd))
-  return args.join(" ")
-}
-
-/** Functional probe: bwrap present AND userns allowed (WSL2/distros vary). */
-export function probeBwrap(): boolean {
-  try {
-    const res = Bun.spawnSync([
-      "bwrap",
-      "--ro-bind",
-      "/",
-      "/",
-      "--dev",
-      "/dev",
-      "--proc",
-      "/proc",
-      "true",
-    ])
-    return res.exitCode === 0
-  } catch {
-    return false
-  }
-}
-
-/**
- * Sandboxed bash via bubblewrap. Rewrites every bash tool call.
- * Off by default. No bwrap -> warn once, passthrough.
- */
-export const sandbox: FeatureModule = {
-  name: "sandbox",
-  tools: ["bash_unsandboxed"],
-  options: { net: "boolean" },
-  defaultEnabled: false,
-  async init(ctx, options) {
-    const policy: SandboxPolicy = {
-      project: ctx.directory,
-      net: options.net !== false,
-    }
-    const available = probeBwrap()
-    if (!available) console.warn("[overclock] sandbox: bwrap unavailable/blocked -> passthrough")
-
-    return {
-      "tool.execute.before": async (input, output) => {
-        if (!available || input.tool !== "bash") return
-        const cmd = (output.args as { command?: string }).command
-        if (typeof cmd !== "string") return
-        output.args.command = wrapCommand(cmd, policy)
-      },
-      tool: {
-        bash_unsandboxed: tool({
-          description:
-            "Run a shell command OUTSIDE the sandbox (full FS write access). Requires user permission. Use only when the sandbox blocks a legitimate operation.",
-          args: {
-            command: z.string(),
-            cwd: z.string().optional(),
-          },
-          async execute(args, tctx) {
-            await tctx.ask({
-              permission: "bash_unsandboxed",
-              patterns: [args.command],
-              always: [],
-              metadata: { command: args.command },
-            })
-            const proc = Bun.spawn(["bash", "-c", args.command], {
-              cwd: args.cwd ?? tctx.directory,
-              stdout: "pipe",
-              stderr: "pipe",
-            })
-            const [out, err, code] = await Promise.all([
-              new Response(proc.stdout).text(),
-              new Response(proc.stderr).text(),
-              proc.exited,
-            ])
-            const text = (out + (err ? `\nstderr:\n${err}` : "")).slice(0, 30_000)
-            return `exit ${code}\n${text}`
-          },
-        }),
-      },
-    }
-  },
-}