iterate-plugin 2.3.6

package/src/skill-prompt.ts

@@ -0,0 +1,227 @@
+/**
+ * The iterate skill prompt injected into the system prompt.
+ *
+ * This teaches the model how to write a correct `workflow` script that
+ * performs the iterate autonomous closed-loop (or dry-run pure review),
+ * using the 5 registered tools via subagents.
+ */
+
+export const ITERATE_SKILL_PROMPT = `
+## Iterate Workflow (autonomous code iteration)
+
+You have the iterate plugin installed, which registers these tools:
+- \`iterate_config\` — read iterate.config.yaml (dimensions, validation commands, personalization)
+- \`iterate_validate\` — run a whitelisted validation command
+- \`iterate_decision_log\` — append to the decision log
+- \`iterate_context\` — read SKILL.md / ITERATE.md project context
+- \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan; \`aggregate\` dedupes/merges findings and computes convergence. Purely computational.
+
+### When to use
+When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.
+- If the user says "review only" / "dry run" / "不要改文件" / "反复审查" → use \`mode: "dry-run"\`.
+- Otherwise → use \`mode: "normal"\`.
+
+### Workflow script contract
+Write a plain-JS script (top-level await, ends with \`return <json>\`). Available globals:
+- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`.
+- \`parallel(thunks): Promise<value[]>\` — run zero-arg async functions concurrently, await all.
+- \`phase(title)\`, \`log(message)\` — progress narration.
+- \`args\` — the args object passed to the workflow tool.
+
+The script CANNOT call tools directly. Subagents are the ones who call tools.
+
+### Dry-run mode workflow (pure review — the ONLY mode that never touches files)
+This is iterate's read-only health-check: repeated review rounds until findings converge,
+then produce an auditable report, then audit the report itself (meta-review) and give a
+final review report. NO file writes, NO git, NO branches, NO worktree.
+
+Canonical script — reproduce this structure exactly (adjust dims via the plan):
+
+\`\`\`js
+phase('plan')
+const planRes = await agent(
+  'Call iterate_review({operation:"plan", mode:"dry-run"}) and return the plan JSON.',
+  { label: 'review:plan' }
+)
+const plan = (planRes && planRes.plan) ? planRes.plan : null
+if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
+const dims = plan.dimensions.map(d => d.id)
+const maxRounds = plan.maxReviewRounds
+const known = []            // cumulative deduped findings across rounds
+const rounds = []           // raw per-round findings
+
+phase('review')
+for (let r = 1; r <= maxRounds; r++) {
+  log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
+  const raw = await parallel(dims.map(dim => () => agent(
+    'Review dimension "' + dim + '". Already-known findings (do NOT re-report): ' +
+    JSON.stringify(known) + '\\nReturn the findings JSON object.',
+    { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+  )))
+  const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+  rounds.push(thisRound)
+  known.push(...thisRound.findings)   // rough accumulation; final dedupe is deterministic in aggregate
+  // Check convergence deterministically
+  const agg = await agent(
+    'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + '}) and return the report JSON.',
+    { label: 'review:aggregate:r' + r }
+  )
+  if (agg && agg.report && agg.report.convergence.findingsByRound[r-1] === 0) {
+    log('round ' + r + ' found 0 new findings — converged')
+    break
+  }
+}
+
+phase('report')
+const finalAgg = await agent(
+  'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + '}) and return the report JSON.',
+  { label: 'review:aggregate:final' }
+)
+const report = (finalAgg && finalAgg.report) ? finalAgg.report : null
+if (!report || !report.convergence) throw new Error('aggregate failed: no valid report was produced')
+await agent(
+  'Call iterate_decision_log({operation:"append", type:"report", round:' + report.convergence.totalRounds + ', data:{mode:"dry-run", totalFindings:' + report.summary.totalFindings + '}})',
+  { label: 'review:log' }
+)
+
+phase('meta-review')
+// Audit the report itself for internal consistency, then produce the final report.
+const metaRes = await agent(
+  'Call iterate_review({operation:"meta-review", report:' + JSON.stringify(report) + '}) and return the finalReport JSON.',
+  { label: 'review:meta' }
+)
+const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
+const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
+
+return {
+  mode: 'dry-run',
+  goal: report.goal,
+  rounds: rounds.length,
+  converged: report.convergence.converged,
+  stoppedReason: report.convergence.stoppedReason,
+  findingsByRound: report.convergence.findingsByRound,
+  totalFindings: report.summary.totalFindings,
+  bySeverity: { critical: report.summary.critical, high: report.summary.high, medium: report.summary.medium, low: report.summary.low },
+  byDimension: report.summary.byDimension,
+  report,
+  metaReview: metaAudit ? { verdict: finalReport.verdict, issues: metaAudit.issues || [], checksRun: metaAudit.checksRun || 0 } : null,
+  finalReport
+}
+\`\`\`
+
+Key rules for dry-run:
+- **NEVER call a fixer / never edit files / never create branches or worktree.** Reviewers read only.
+- Each round feeds the already-known findings to reviewers so they hunt NEW issues only → that is what drives convergence.
+- Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
+- The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
+- **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The \`finalReport.verdict\` is \`approved\` only when the report passes every check; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
+- Only a single \`report\` entry may be appended to the decision log; nothing else is written.
+
+### Normal-mode workflow (autonomous closed loop)
+Set \`args.mode = "normal"\`. Loop: plan → parallel review ×N → fix atomic issues → validate → loop → auto-stop when zero findings remain.
+Canonical script — reproduce this structure exactly (adjust dims via the plan):
+
+\`\`\`js
+// args = { mode: "normal", maxRounds? }
+phase('plan')
+await agent(
+  'Call iterate_config({ validate: true }) and return the config JSON.',
+  { label: 'config:read' }
+)
+const planRes = await agent(
+  'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
+  { label: 'review:plan' }
+)
+const plan = (planRes && planRes.plan) ? planRes.plan : null
+if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
+const dims = plan.dimensions.map(d => d.id)
+const maxRounds = plan.maxReviewRounds
+const rounds = []          // findings per review round (each on the then-current code state)
+const architectural = []   // findings deliberately left unfixed (reported at the end)
+let fixedCount = 0
+let converged = false
+
+phase('loop')
+for (let r = 1; r <= maxRounds; r++) {
+  log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics, validate')
+  const raw = await parallel(dims.map(dim => () => agent(
+    'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
+    'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + '\\nReturn the findings JSON object.',
+    { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+  )))
+  const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+  rounds.push(thisRound)
+
+  // Deterministic dedupe / known_intentional filter / severity sort for this round.
+  const agg = await agent(
+    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + '}) and return the report JSON.',
+    { label: 'review:aggregate:r' + r }
+  )
+  const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
+  const atomic = findings.filter(f => f.is_atomic === true)
+  const remaining = findings.filter(f => f.is_atomic !== true)
+
+  if (atomic.length > 0) {
+    await parallel(atomic.map(f => () => agent(
+      'Fix this finding with the smallest possible change (single file, single function, <=20 lines). ' +
+      JSON.stringify(f) + '. Verify the edit locally before finishing.',
+      { label: 'fix:' + f.file + ':' + (f.line || 0), phase: 'fix' }
+    )))
+    fixedCount += atomic.length
+  }
+  architectural.push(...remaining)
+
+  await agent(
+    'Call iterate_validate for each command in iterate.config.yaml validation.commands and return all {command, exitCode} results.',
+    { label: 'validate:r' + r, phase: 'validate' }
+  )
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"review_result", round:' + r +
+    ', data:{atomic:' + atomic.length + ', architectural:' + remaining.length + ', fixedSoFar:' + fixedCount + '}})',
+    { label: 'log:r' + r }
+  )
+
+  if (atomic.length === 0 && remaining.length === 0) {
+    log('round ' + r + ' found nothing to fix — converged')
+    converged = true
+    break
+  }
+}
+
+phase('report')
+await agent(
+  'Call iterate_decision_log({operation:"append", type:"report", round:' + rounds.length +
+  ', data:{mode:"normal", fixed:' + fixedCount + ', architectural:' + architectural.length + '}})',
+  { label: 'report:log' }
+)
+return {
+  mode: 'normal',
+  goal: plan.goal,
+  roundsExecuted: rounds.length,
+  maxRounds: maxRounds,
+  converged: converged,
+  findingsFixed: fixedCount,
+  remainingArchitecturalCount: architectural.length,
+  remainingArchitectural: architectural
+}
+\`\`\`
+
+Key rules for normal mode:
+- Fixers are the ONLY agents allowed to write files; reviewers read only. Architectural findings are reported, never auto-fixed.
+- Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
+- Validate after every round of fixes; validation results are logged, not silently dropped.
+- Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
+- Every round and the final report go to the append-only decision log.
+
+### Finding schema (for reviewer agents)
+{ "dimension": string, "file": string (relative path), "line": number (optional),
+  "severity": "critical" | "high" | "medium" | "low", "summary": string (one line),
+  "failure_scenario": string (how/when it fails), "suggested_fix": string (the concrete fix),
+  "is_atomic": boolean (true if fix ≤ max_lines within a single file/function) }
+Atomic = is_atomic true (single file, single function, ≤20 lines change). Architectural = everything else.
+
+### Workflow meta
+Always pass \`meta: { name: "iterate", description: "Autonomous iterate loop" }\`.
+
+Always end with a clear summary: total findings, count by severity, fixes applied (normal) or convergence stats (dry-run), and remaining architectural findings.
+`

package/src/tools/config.ts

@@ -0,0 +1,90 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { loadEffectiveConfig, validateConfig } from '../config-loader.ts'
+
+/**
+ * Register the `iterate_config` tool.
+ * Reads and returns the iterate.config.yaml configuration.
+ * Model-facing: returns JSON with the full config, a specific section, or validation errors.
+ */
+export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_config',
+      description:
+        'Read the iterate.config.yaml configuration from the project root. ' +
+        'Returns the full parsed config, a specific section, or validation errors. ' +
+        'Use this to discover available dimensions, validation commands, git settings, and personalization rules.',
+
+      parameters: {
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+        section: {
+          type: 'string',
+          description:
+            'Optional config section to return: dimensions, validation, git, atomic, review, personalization, onboarding, or goal.',
+        },
+        validate: {
+          type: 'boolean',
+          description: 'If true, validate the config schema and return any missing fields.',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            found: { type: 'boolean', required: true },
+            valid: { type: 'boolean' },
+            errors: { type: 'array', items: { type: 'string' } },
+            section: { type: 'string' },
+            data: { type: 'json' },
+            config: { type: 'json' },
+            availableSections: { type: 'array', items: { type: 'string' } },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+      },
+
+      async execute(args) {
+        const projectRoot = args.path ?? process.cwd()
+        // Effective config = defaults (Master) merged with any project-root
+        // overrides. Never null: a project without a config file runs on the
+        // built-in defaults, so the workflow stays usable out of the box.
+        const { config, source } = loadEffectiveConfig(projectRoot)
+        const hasOverride = source === 'override'
+
+        if (args.validate) {
+          const errors = validateConfig(config)
+          return {
+            found: hasOverride,
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            section: 'validation_report',
+          }
+        }
+
+        if (args.section) {
+          const configRecord = config as unknown as Record<string, unknown>
+          const section = configRecord[args.section]
+          if (section === undefined) {
+            return {
+              found: hasOverride,
+              error: `Section "${args.section}" not found in config.`,
+              availableSections: Object.keys(configRecord),
+            }
+          }
+          return { found: hasOverride, section: args.section, data: section as JsonValue }
+        }
+
+        return { found: hasOverride, config: config as unknown as JsonValue }
+      },
+    }),
+  )
+}

package/src/tools/context.ts

@@ -0,0 +1,170 @@
+import { readFileSync, existsSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** How many ancestor directories we walk up looking for a SKILL.md. */
+const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
+
+/**
+ * The directory this source file lives in (…/src/tools). The plugin's own
+ * package root is one level up (…/src), and the skill root is typically a few
+ * levels above that. We use it as the anchor for auto-detecting where the
+ * original SKILL.md lives.
+ */
+const PLUGIN_SRC_DIR = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Walk up from the plugin's own location until a directory containing SKILL.md
+ * is found. This is how the plugin locates the ORIGINAL skill (skill 目录)
+ * without any hardcoded absolute path — it works whether the plugin is mounted
+ * from the source tree or bundled next to the skill.
+ *
+ * Returns the absolute directory containing SKILL.md, or null if none found
+ * within `MAX_SKILL_DIR_LOOKUP_DEPTH` ancestors.
+ */
+function findSkillRoot(startDir: string): string | null {
+  let dir = resolve(startDir)
+  for (let depth = 0; depth < MAX_SKILL_DIR_LOOKUP_DEPTH; depth++) {
+    if (existsSync(join(dir, 'SKILL.md'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break // reached the filesystem root
+    dir = parent
+  }
+  return null
+}
+
+/** Exported for unit tests. See the private `findSkillRoot` above. */
+export { findSkillRoot }
+
+/**
+ * Read a file from a candidate directory, returning its content or null.
+ */
+function readProjectFile(projectRoot: string, filename: string): string | null {
+  const filePath = join(projectRoot, filename)
+  if (!existsSync(filePath)) return null
+  try {
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Locate the first existing SKILL.md across the candidate directories, in
+ * priority order:
+ *   1. explicit skillDir (custom path / 自定义路径)
+ *   2. auto-detected skill root walking up from the plugin (skill 目录)
+ *   3. project root (项目根)
+ * Returns the file content plus the directory it was found in, or null.
+ */
+function findSkillMd(candidates: string[]): { content: string; sourceDir: string } | null {
+  for (const dir of candidates) {
+    if (!dir) continue
+    const content = readProjectFile(dir, 'SKILL.md')
+    if (content !== null) return { content, sourceDir: dir }
+  }
+  return null
+}
+
+/** Exported for unit tests. See the private `findSkillMd` above. */
+export { findSkillMd }
+
+/**
+ * Register the `iterate_context` tool.
+ * Reads SKILL.md (original skill instructions) from the skill directory,
+ * project root, or a custom path, and ITERATE.md from the project root.
+ * Provides the model with the original skill instructions and project knowledge base.
+ */
+export function registerContextTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_context',
+      description:
+        'Read project context files (SKILL.md and/or ITERATE.md). ' +
+        'SKILL.md contains the original iterate skill instructions; it is searched in ' +
+        'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +
+        'ITERATE.md contains the project-specific knowledge base and onboarding information. ' +
+        'Use this to understand the skill workflow and project context.',
+
+      parameters: {
+        files: {
+          type: 'string',
+          required: true,
+          description:
+            'Comma-separated list of files to read: "skill", "project", or "skill,project" for both.',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+        skillDir: {
+          type: 'string',
+          description:
+            'Custom directory to search for SKILL.md (highest priority). ' +
+            'When omitted, SKILL.md is auto-detected from the skill directory, then the project root.',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            found: { type: 'boolean', required: true },
+            skill: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            project: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            skillSource: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            searched: { type: 'array', items: { type: 'string' } },
+          },
+        },
+        render: (_args, value) => {
+          const parts: string[] = []
+          if (value.skill) parts.push(`--- SKILL.md (${value.skillSource ?? '?source?'}) ---\n${value.skill}`)
+          if (value.project) parts.push(`--- ITERATE.md ---\n${value.project}`)
+          if (!value.skill && !value.project) {
+            parts.push('No files found. Searched: ' + (value.searched?.join(', ') ?? 'none'))
+          }
+          return [{ type: 'text', text: parts.join('\n\n') }]
+        },
+      },
+
+      async execute(args) {
+        const projectRoot = args.path ?? process.cwd()
+        const requested = (args.files ?? '')
+          .split(',')
+          .map((s) => s.trim().toLowerCase())
+          .filter(Boolean)
+
+        const result: {
+          found: boolean
+          skill?: string | null
+          project?: string | null
+          skillSource?: string | null
+          searched: string[]
+        } = { found: true, searched: [] }
+
+        if (requested.includes('skill') || requested.includes('skill.md')) {
+          // Candidate dirs in priority order: custom path → auto-detected skill
+          // root → project root. This is how "skill 目录、项目根、自定义路径"
+          // are all supported.
+          const skillRoot = findSkillRoot(PLUGIN_SRC_DIR)
+          const candidates: string[] = []
+          if (args.skillDir) candidates.push(args.skillDir)
+          if (skillRoot) candidates.push(skillRoot)
+          candidates.push(projectRoot)
+          result.searched = candidates
+
+          const found = findSkillMd(candidates)
+          result.skill = found ? found.content : null
+          result.skillSource = found ? found.sourceDir : null
+        }
+        if (requested.includes('project') || requested.includes('iterate.md')) {
+          result.project = readProjectFile(projectRoot, 'ITERATE.md')
+        }
+
+        return result
+      },
+    }),
+  )
+}

package/src/tools/decision-log.ts

@@ -0,0 +1,163 @@
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import type { DecisionLogEntry } from '../types.ts'
+
+const LOG_DIR = '.iterate'
+const LOG_FILE = 'decision-log.jsonl'
+
+/**
+ * Resolve the log file path, creating the directory if needed.
+ */
+function logPath(projectRoot: string): string {
+  const dir = join(projectRoot, LOG_DIR)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+  return join(dir, LOG_FILE)
+}
+
+/**
+ * Append one entry to the decision log (JSONL format).
+ * Returns the entry count after appending.
+ */
+function appendEntry(projectRoot: string, entry: DecisionLogEntry): { count: number; path: string } {
+  const filePath = logPath(projectRoot)
+  const line = JSON.stringify(entry) + '\n'
+  appendFileSync(filePath, line, 'utf-8')
+  // Count entries
+  let count = 0
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    count = content.split('\n').filter((l) => l.trim().length > 0).length
+  } catch {
+    count = 1
+  }
+  return { count, path: filePath }
+}
+
+/**
+ * Read all entries from the decision log.
+ */
+function readEntries(projectRoot: string): DecisionLogEntry[] {
+  const filePath = join(projectRoot, LOG_DIR, LOG_FILE)
+  if (!existsSync(filePath)) return []
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    return content
+      .split('\n')
+      .filter((l) => l.trim().length > 0)
+      .map((l) => JSON.parse(l) as DecisionLogEntry)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Register the `iterate_decision_log` tool.
+ * Append-only decision log stored in .iterate/decision-log.jsonl.
+ * Supports `append` and `read` operations.
+ */
+export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_decision_log',
+      description:
+        'Append-only decision log for the iterate loop. ' +
+        'Use `append` to record a round start, review finding, fix, validation result, or decision. ' +
+        'Use `read` to retrieve all entries for review. ' +
+        'The log is stored in .iterate/decision-log.jsonl and persists across sessions.',
+
+      parameters: {
+        operation: {
+          type: 'string',
+          required: true,
+          description: '"append" to add an entry, "read" to retrieve all entries.',
+          enum: ['append', 'read'],
+        },
+        type: {
+          type: 'string',
+          description:
+            'Entry type (required for append): round_start, review_result, atomic_fix, ' +
+            'architectural_fix, revert, validation, decision, report.',
+        },
+        round: {
+          type: 'integer',
+          description: 'Current iteration round number (required for append).',
+        },
+        data: {
+          type: 'json',
+          description: 'Entry payload as JSON object (required for append).',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            operation: { type: 'string', required: true },
+            entryCount: { type: 'integer' },
+            logPath: { type: 'string' },
+            entries: { type: 'json' },
+            success: { type: 'boolean' },
+            entry: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+      },
+
+      async execute(args) {
+        const projectRoot = args.path ?? process.cwd()
+
+        if (args.operation === 'read') {
+          const entries = readEntries(projectRoot)
+          return {
+            operation: 'read',
+            entryCount: entries.length,
+            logPath: join(projectRoot, LOG_DIR, LOG_FILE),
+            entries: entries as unknown as JsonValue,
+          }
+        }
+
+        if (args.operation === 'append') {
+          if (!args.type || !args.round) {
+            return {
+              operation: 'append',
+              error: 'type and round are required for append operation.',
+            }
+          }
+
+          const entry: DecisionLogEntry = {
+            timestamp: new Date().toISOString(),
+            round: args.round,
+            type: args.type as DecisionLogEntry['type'],
+            data: (args.data as Record<string, unknown>) ?? {},
+          }
+
+          const result = appendEntry(projectRoot, entry)
+          return {
+            operation: 'append',
+            success: true,
+            entryCount: result.count,
+            logPath: result.path,
+            entry: entry as unknown as JsonValue,
+          }
+        }
+
+        return {
+          operation: args.operation,
+          error: `Unknown operation "${args.operation}". Use "append" or "read".`,
+        }
+      },
+    }),
+  )
+}