opencode-overclock 0.4.0 → 0.5.0

package/src/workflow/catalog.ts

@@ -0,0 +1,210 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, basename, resolve } from "node:path"
+import YAML from "yaml"
+
+export interface SkillMetadata {
+  name: string
+  description: string
+  pack?: string
+  license?: string
+  attribution?: string
+  references?: string[]
+  [key: string]: unknown
+}
+
+export interface ParsedSkill {
+  filePath: string
+  directory: string
+  metadata: SkillMetadata
+  body: string
+  rawFrontmatter: string
+}
+
+export interface SkillValidationError {
+  filePath: string
+  message: string
+}
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/
+
+/**
+ * Extracts and parses YAML frontmatter with strict duplicate key checking.
+ */
+export function parseFrontmatter(
+  content: string,
+  filePath = "<string>",
+): { metadata: SkillMetadata; body: string; rawFrontmatter: string } {
+  const match = content.match(FRONTMATTER_REGEX)
+  if (!match) {
+    throw new Error(`Missing frontmatter delimiter (---) in ${filePath}`)
+  }
+
+  const rawFrontmatter = match[1]!
+  const body = match[2]!
+
+  let parsed: unknown
+  try {
+    parsed = YAML.parse(rawFrontmatter, { uniqueKeys: true })
+  } catch (err: any) {
+    throw new Error(`Invalid YAML frontmatter in ${filePath}: ${err?.message ?? String(err)}`)
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Frontmatter must be a key-value mapping in ${filePath}`)
+  }
+
+  const data = parsed as Record<string, unknown>
+
+  if (typeof data.name !== "string" || !data.name.trim()) {
+    throw new Error(`Skill frontmatter missing required string "name" in ${filePath}`)
+  }
+
+  const name = data.name.trim()
+  if (!/^[a-z0-9_-]+$/.test(name)) {
+    throw new Error(
+      `Invalid skill name "${name}" in ${filePath}: must be lowercase alphanumeric with dashes or underscores`,
+    )
+  }
+
+  if (typeof data.description !== "string" || data.description.trim().length < 10) {
+    throw new Error(
+      `Skill frontmatter "description" in ${filePath} must be a descriptive string (at least 10 characters)`,
+    )
+  }
+
+  const metadata: SkillMetadata = {
+    ...data,
+    name,
+    description: data.description.trim(),
+  }
+
+  return { metadata, body, rawFrontmatter }
+}
+
+/**
+ * Validates a single SKILL.md file for schema compliance, directory matching,
+ * and relative reference closure.
+ */
+export function validateSkillFile(filePath: string): {
+  valid: boolean
+  errors: string[]
+  skill?: ParsedSkill
+} {
+  const errors: string[] = []
+
+  if (!existsSync(filePath)) {
+    return { valid: false, errors: [`File does not exist: ${filePath}`] }
+  }
+
+  let content = ""
+  try {
+    content = readFileSync(filePath, "utf-8")
+  } catch (err: any) {
+    return { valid: false, errors: [`Failed to read file ${filePath}: ${err?.message}`] }
+  }
+
+  let parsed: { metadata: SkillMetadata; body: string; rawFrontmatter: string }
+  try {
+    parsed = parseFrontmatter(content, filePath)
+  } catch (err: any) {
+    return { valid: false, errors: [err?.message ?? String(err)] }
+  }
+
+  const skillDir = dirname(filePath)
+  const dirName = basename(skillDir)
+
+  if (parsed.metadata.name !== dirName) {
+    errors.push(
+      `Skill name mismatch in ${filePath}: declared "${parsed.metadata.name}" but parent directory is "${dirName}"`,
+    )
+  }
+
+  // Validate declared references
+  if (parsed.metadata.references) {
+    if (!Array.isArray(parsed.metadata.references)) {
+      errors.push(`"references" in ${filePath} must be an array of relative paths`)
+    } else {
+      for (const ref of parsed.metadata.references) {
+        if (typeof ref !== "string") {
+          errors.push(`Invalid reference in ${filePath}: expected string, got ${typeof ref}`)
+          continue
+        }
+        const resolvedRef = resolve(skillDir, ref)
+        if (!existsSync(resolvedRef)) {
+          errors.push(`Declared reference not found in ${filePath}: "${ref}" -> ${resolvedRef}`)
+        }
+      }
+    }
+  }
+
+  // Check markdown links to local files (dependency closure)
+  const linkRegex = /\[[^\]]+\]\((?!https?:\/\/|#|mailto:)([^)#?]+)\)/g
+  let match: RegExpExecArray | null
+  while ((match = linkRegex.exec(parsed.body)) !== null) {
+    const target = match[1]?.trim()
+    if (!target) continue
+    const resolvedLink = resolve(skillDir, target)
+    if (!existsSync(resolvedLink)) {
+      errors.push(`Broken local markdown link in ${filePath}: "${target}" -> ${resolvedLink}`)
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors }
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    skill: {
+      filePath,
+      directory: skillDir,
+      metadata: parsed.metadata,
+      body: parsed.body,
+      rawFrontmatter: parsed.rawFrontmatter,
+    },
+  }
+}
+
+/**
+ * Validates all skills within the bundled skills directory.
+ */
+export function validateAllSkills(skillsDir: string): {
+  valid: boolean
+  errors: SkillValidationError[]
+  skills: ParsedSkill[]
+} {
+  const errors: SkillValidationError[] = []
+  const skills: ParsedSkill[] = []
+
+  if (!existsSync(skillsDir)) {
+    return {
+      valid: false,
+      errors: [{ filePath: skillsDir, message: `Skills directory does not exist: ${skillsDir}` }],
+      skills: [],
+    }
+  }
+
+  const entries = readdirSync(skillsDir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const skillFile = resolve(skillsDir, entry.name, "SKILL.md")
+      if (existsSync(skillFile)) {
+        const result = validateSkillFile(skillFile)
+        if (result.valid && result.skill) {
+          skills.push(result.skill)
+        } else {
+          for (const err of result.errors) {
+            errors.push({ filePath: skillFile, message: err })
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    skills,
+  }
+}

package/src/workflow/templates/build.ts

@@ -0,0 +1,47 @@
+export const BUILD_TEMPLATE = `---
+description: Test-driven implementation loop with stop-the-line tripwires and incremental verification.
+---
+# Lifecycle Phase 3: Build
+
+Execute tasks from \`tasks/plan.md\` (or the specific task requested: $ARGUMENTS).
+
+## Autonomous Mode ($ARGUMENTS contains "auto") vs Single-Slice Mode
+- **With \`auto\`:** Iteratively execute all unblocked tasks from \`tasks/plan.md\` sequentially until all are complete or a tripwire triggers.
+- **Without \`auto\` (Default):** Execute only the next unblocked task on the frontier, verify, and pause for human review.
+
+---
+
+## The Increment Cycle (Per Task)
+
+For each task on the frontier:
+
+1. **RED (Prove Capability Missing):**
+   - Write a focused test at the declared public seam before touching implementation code.
+   - Use an **independent test oracle**: never compute expected results with the same logic used in production code.
+   - Run the test suite: confirm the test fails for the expected reason (missing capability, not a syntax error).
+   - *Prove-It Pattern:* If fixing a bug, the test MUST reproduce the reported defect before touching the fix.
+
+2. **GREEN (Minimal Implementation):**
+   - Write the minimal code required to make the test pass clean.
+   - Do NOT add speculative abstractions or unrequested features.
+   - Never use error suppressions (\`@ts-ignore\`, \`eslint-disable\`, \`# noqa\`) or test skips (\`.skip\`). Overclock's floor-guard will flag them.
+
+3. **REFACTOR (Clean While Green):**
+   - Refactor only while all tests are green.
+   - Remove duplication, simplify names, and polish structure. Re-verify tests pass after every refactoring edit.
+
+4. **VERIFY:**
+   - Run project linters and typecheckers to confirm zero regressions.
+
+5. **UPDATE PLAN:**
+   - Mark the completed task in \`tasks/plan.md\` and update \`todowrite\`.
+   - If git commits are used, stage ONLY the files modified for this slice with a descriptive commit message.
+
+---
+
+## Stop-The-Line Tripwires (Immediate Halt)
+Halt execution and alert the user immediately if:
+- **Test Failure Loop:** A test fails to pass after 3 consecutive fix attempts.
+- **Irreversible Boundary:** The task requires altering production database schemas, payment processing, or secret keys.
+- **Specification Ambiguity:** An unhandled edge case is discovered that contradicts \`SPEC.md\` or requires human judgment.
+`

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.
+`