@zhixuan92/multi-model-agent-core 5.1.0 → 5.2.1

package/dist/unified/worktree-manager.js

@@ -0,0 +1,76 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+const execFileAsync = promisify(execFileCb);
+const defaultExec = async (cmd, args, opts) => {
+    const { stdout, stderr } = await execFileAsync(cmd, args, { cwd: opts.cwd, windowsHide: true });
+    return { stdout: stdout ?? '', stderr: stderr ?? '' };
+};
+const defaultFs = {
+    mkdir: async (path, opts) => { await mkdir(path, opts); },
+    access: async (path) => { await access(path); },
+};
+export class WorktreeManager {
+    exec;
+    fs;
+    constructor(exec, fs) {
+        this.exec = exec ?? defaultExec;
+        this.fs = fs ?? defaultFs;
+    }
+    /**
+     * Create a git worktree for a task.
+     * Runs `git worktree add` off current HEAD with a task-specific branch.
+     * If the worktree has a package.json, runs `pnpm install --frozen-lockfile`.
+     */
+    async create(cwd, taskId, type) {
+        const shortId = taskId.slice(0, 8);
+        const branch = `mma/${type}-${shortId}`;
+        const worktreeDir = join(cwd, '.mma', 'worktrees', shortId);
+        // Ensure parent dir exists
+        await this.fs.mkdir(join(cwd, '.mma', 'worktrees'), { recursive: true });
+        // Create worktree with a new branch off HEAD
+        await this.exec('git', ['worktree', 'add', worktreeDir, '-b', branch], { cwd, windowsHide: true });
+        // Install dependencies if package.json exists
+        try {
+            await this.fs.access(join(worktreeDir, 'package.json'));
+            await this.exec('pnpm', ['install', '--frozen-lockfile'], { cwd: worktreeDir });
+        }
+        catch {
+            // No package.json — skip install
+        }
+        return { branch, path: worktreeDir, hasChanges: false };
+    }
+    /**
+     * Check whether a worktree has uncommitted changes.
+     */
+    async hasChanges(worktreePath) {
+        const { stdout } = await this.exec('git', ['status', '--porcelain'], { cwd: worktreePath, windowsHide: true });
+        return stdout.trim().length > 0;
+    }
+    /**
+     * Remove a worktree and its branch if there are no uncommitted changes.
+     * Returns true if the worktree was preserved (dirty), false if removed.
+     */
+    async cleanup(worktreePath, branch) {
+        const dirty = await this.hasChanges(worktreePath);
+        if (dirty) {
+            return true;
+        }
+        await this.exec('git', ['worktree', 'remove', worktreePath, '--force'], { cwd: worktreePath, windowsHide: true });
+        // Branch delete uses the parent repo; worktreePath's parent is fine since
+        // the worktree itself was just removed.  Use dirname twice to reach the
+        // repo root (.mma/worktrees/<id> → .mma/worktrees → .mma → repo).
+        const repoRoot = join(worktreePath, '..', '..', '..');
+        await this.exec('git', ['branch', '-D', branch], { cwd: repoRoot, windowsHide: true });
+        return false;
+    }
+    /**
+     * Get current info for an existing worktree.
+     */
+    async getInfo(worktreePath, branch) {
+        const dirty = await this.hasChanges(worktreePath);
+        return { branch, path: worktreePath, hasChanges: dirty };
+    }
+}
+//# sourceMappingURL=worktree-manager.js.map

package/dist/unified/worktree-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-manager.js","sourceRoot":"","sources":["../../src/unified/worktree-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent-core",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "type": "module",
   "license": "MIT",
   "description": "Core library for multi-model-agent: provider runners (Claude, Codex, OpenAI-compatible), routing logic, config schema, and tool/sandbox primitives.",
@@ -23,7 +23,8 @@
   "homepage": "https://github.com/zhixuan312/multi-model-agent#readme",
   "bugs": "https://github.com/zhixuan312/multi-model-agent/issues",
   "files": [
-    "dist"
+    "dist",
+    "src/skills"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,18 +49,6 @@
       "types": "./dist/providers/provider-factory.d.ts",
       "import": "./dist/providers/provider-factory.js"
     },
-    "./lifecycle/task-runner": {
-      "types": "./dist/lifecycle/task-runner.d.ts",
-      "import": "./dist/lifecycle/task-runner.js"
-    },
-    "./lifecycle/stage-progression": {
-      "types": "./dist/lifecycle/stage-progression.d.ts",
-      "import": "./dist/lifecycle/stage-progression.js"
-    },
-    "./lifecycle/stage-labels": {
-      "types": "./dist/lifecycle/stage-labels.d.ts",
-      "import": "./dist/lifecycle/stage-labels.js"
-    },
     "./bounded-execution/activity-tracker": {
       "types": "./dist/bounded-execution/activity-tracker.d.ts",
       "import": "./dist/bounded-execution/activity-tracker.js"
@@ -100,114 +89,10 @@
       "types": "./dist/events/stderr-log-subscriber.d.ts",
       "import": "./dist/events/stderr-log-subscriber.js"
     },
-    "./lifecycle/auto-commit": {
-      "types": "./dist/lifecycle/auto-commit.d.ts",
-      "import": "./dist/lifecycle/auto-commit.js"
-    },
     "./bounded-execution/file-artifact-check": {
       "types": "./dist/bounded-execution/file-artifact-check.d.ts",
       "import": "./dist/bounded-execution/file-artifact-check.js"
     },
-    "./lifecycle/task-executor": {
-      "types": "./dist/lifecycle/task-executor.d.ts",
-      "import": "./dist/lifecycle/task-executor.js"
-    },
-    "./lifecycle/executor-output-types": {
-      "types": "./dist/lifecycle/executor-output-types.d.ts",
-      "import": "./dist/lifecycle/executor-output-types.js"
-    },
-    "./tools": {
-      "types": "./dist/tools/index.d.ts",
-      "import": "./dist/tools/index.js"
-    },
-    "./tools/index": {
-      "types": "./dist/tools/index.d.ts",
-      "import": "./dist/tools/index.js"
-    },
-    "./tools/audit/tool-config": {
-      "types": "./dist/tools/audit/tool-config.d.ts",
-      "import": "./dist/tools/audit/tool-config.js"
-    },
-    "./tools/debug/tool-config": {
-      "types": "./dist/tools/debug/tool-config.d.ts",
-      "import": "./dist/tools/debug/tool-config.js"
-    },
-    "./tools/delegate/tool-config": {
-      "types": "./dist/tools/delegate/tool-config.d.ts",
-      "import": "./dist/tools/delegate/tool-config.js"
-    },
-    "./tools/execute-plan/tool-config": {
-      "types": "./dist/tools/execute-plan/tool-config.d.ts",
-      "import": "./dist/tools/execute-plan/tool-config.js"
-    },
-    "./tools/investigate/tool-config": {
-      "types": "./dist/tools/investigate/tool-config.d.ts",
-      "import": "./dist/tools/investigate/tool-config.js"
-    },
-    "./tools/journal/record/tool-config": {
-      "types": "./dist/tools/journal/record/tool-config.d.ts",
-      "import": "./dist/tools/journal/record/tool-config.js"
-    },
-    "./tools/journal/recall/tool-config": {
-      "types": "./dist/tools/journal/recall/tool-config.d.ts",
-      "import": "./dist/tools/journal/recall/tool-config.js"
-    },
-    "./tools/register-context-block/tool-config": {
-      "types": "./dist/tools/register-context-block/tool-config.d.ts",
-      "import": "./dist/tools/register-context-block/tool-config.js"
-    },
-    "./tools/retry/tool-config": {
-      "types": "./dist/tools/retry/tool-config.d.ts",
-      "import": "./dist/tools/retry/tool-config.js"
-    },
-    "./tools/review/tool-config": {
-      "types": "./dist/tools/review/tool-config.d.ts",
-      "import": "./dist/tools/review/tool-config.js"
-    },
-    "./tools/delegate/schema": {
-      "types": "./dist/tools/delegate/schema.d.ts",
-      "import": "./dist/tools/delegate/schema.js"
-    },
-    "./tools/audit/schema": {
-      "types": "./dist/tools/audit/schema.d.ts",
-      "import": "./dist/tools/audit/schema.js"
-    },
-    "./tools/investigate/schema": {
-      "types": "./dist/tools/investigate/schema.d.ts",
-      "import": "./dist/tools/investigate/schema.js"
-    },
-    "./tools/journal/record/schema": {
-      "types": "./dist/tools/journal/record/schema.d.ts",
-      "import": "./dist/tools/journal/record/schema.js"
-    },
-    "./tools/journal/recall/schema": {
-      "types": "./dist/tools/journal/recall/schema.d.ts",
-      "import": "./dist/tools/journal/recall/schema.js"
-    },
-    "./tools/research/schema": {
-      "types": "./dist/tools/research/schema.d.ts",
-      "import": "./dist/tools/research/schema.js"
-    },
-    "./tools/research/tool-config": {
-      "types": "./dist/tools/research/tool-config.d.ts",
-      "import": "./dist/tools/research/tool-config.js"
-    },
-    "./tools/review/schema": {
-      "types": "./dist/tools/review/schema.d.ts",
-      "import": "./dist/tools/review/schema.js"
-    },
-    "./tools/debug/schema": {
-      "types": "./dist/tools/debug/schema.d.ts",
-      "import": "./dist/tools/debug/schema.js"
-    },
-    "./tools/retry/schema": {
-      "types": "./dist/tools/retry/schema.d.ts",
-      "import": "./dist/tools/retry/schema.js"
-    },
-    "./tools/register-context-block/schema": {
-      "types": "./dist/tools/register-context-block/schema.d.ts",
-      "import": "./dist/tools/register-context-block/schema.js"
-    },
     "./events/consent-rules": {
       "types": "./dist/events/consent-rules.d.ts",
       "import": "./dist/events/consent-rules.js"
@@ -215,6 +100,10 @@
     "./events/wire-schema": {
       "types": "./dist/events/wire-schema.d.ts",
       "import": "./dist/events/wire-schema.js"
+    },
+    "./research": {
+      "types": "./dist/research/index.d.ts",
+      "import": "./dist/research/index.js"
     }
   },
   "scripts": {

package/src/skills/audit/implement-plan.md

@@ -0,0 +1,182 @@
+# Audit — Implementer (Plan: Codebase Coherence)
+
+You are auditing a CODE-EXECUTION PLAN against a real codebase AND (when provided) against an upstream requirement spec. The plan will subsequently be dispatched to literal-following workers via mma-execute-plan; if the plan names a method, file, type, or signature that does not match the codebase as it exists today, the worker will freeze on the contradiction or produce broken code. If the plan silently skips a spec requirement, the implementation will ship incomplete.
+
+## Purpose Split
+
+Your job is NOT prose-quality on the plan itself (that is the default audit's job). Your job splits into three perspective groups:
+
+- **EXTERNAL CODEBASE COHERENCE (perspectives 1-8)** — for every named symbol, file path, signature, or import in the plan, the codebase must contain it as described UNLESS the plan task is the one creating it. These perspectives REQUIRE source-side evidence (file:line).
+- **INTRA-PLAN STRUCTURE (perspectives 9, 11, 12)** — task granularity, placeholder language, and required plan skeleton. These look ONLY at the plan markdown; no codebase grounding needed.
+- **SPEC ALIGNMENT (perspective 10)** — every load-bearing spec requirement maps to at least one plan task, and no task implements something the spec did not ask for. Requires the reference SPEC to be in your context. If no spec is available, emit "No findings for this criterion." for perspective 10 ONLY.
+
+## CRITICAL: USE vs DEFINE Intent Classification
+
+Before ANY finding on perspectives 2-5, classify each symbol mention. Confusing USE and DEFINE intent is the #1 source of false positives.
+
+**USE intent** — the plan TREATS the symbol as already existing. Examples:
+- method calls: `store.register(...)`, `obj.helper(...)`, `await provider.run(...)`
+- property/field access: `config.someField`, `result.cost`, `this._ttlMs`
+- import statements: `import { X } from "./bar.js"`
+- type references: `function f(arg: X)`, `: Promise<X>`, `: ExistingInterface`
+- test code calling production code: `expect(store.register(...))`
+
+**DEFINE intent** — the plan CREATES the symbol in this task. Examples:
+- function/method declarations: `function foo()`, `private foo()`, `static foo()`
+- class/interface/type declarations: `class Foo {}`, `interface Bar {}`, `type Q = ...`
+- exported constants: `export const baz = ...`
+- new fields added to existing types: `interface ExistingType { newField: X }`
+- new option keys on existing methods: `register(content, opts: { newOpt: X })`
+- new test files via "Test: <path> (new)"
+- new modules via "New: <path>" or "Create: <path>"
+
+**Verification rule:**
+- USE intent -> symbol MUST exist in named source file. If grep returns no match -> flag CRITICAL with nearest match.
+- DEFINE intent -> symbol MAY NOT exist yet. The task is adding it. **DO NOT FLAG.**
+- DEFINE intent + symbol DOES already exist -> flag MEDIUM "task is obsolete; deliverable already shipped."
+
+**Heuristic:** if the code block has a function/method declaration syntax ON THE SAME LINE as the symbol name, it's DEFINE. If the symbol appears as callee, imported name, type annotation, or property access, it's USE.
+
+**Task scope = a unit.** Each `### Task X.Y:` heading + its `Files:` block + its numbered steps + code blocks form ONE UNIT. Read the unit as a whole before flagging.
+
+## Your Execution Strategy
+
+You MUST work through the 12 perspectives **one at a time, sequentially**. For each perspective:
+
+1. Read the plan through the lens of ONLY that perspective
+2. Write any findings to a scratch file at `/tmp/audit-findings.md` (append mode)
+3. If no findings for that perspective, write "Perspective N: No findings." to the scratch file
+4. Move to the next perspective
+
+After all 12 perspectives are complete, read the scratch file and consolidate into the final JSON output.
+
+**Do NOT try to evaluate all perspectives in one pass.** The sequential approach ensures thorough coverage — each perspective gets your full attention before moving on.
+
+## Execution Steps
+
+### Step 1: Create scratch file
+Write to `/tmp/audit-findings.md`:
+```
+# Plan Audit Findings (scratch)
+```
+
+### Step 2: Perspective 1 — PATH EXISTENCE
+Every "Files:" line must resolve. Sub-rules: (a) `Modify: <path>` -> file MUST exist (missing = CRITICAL). (b) `Test: <path>` or `Test: <path> (new)` -> parent dir MUST exist; test file itself may or may not. (c) `New: <path>` or `Create: <path>` -> parent dir MUST exist AND file MUST NOT exist (already exists = MEDIUM, plan needs trimming).
+
+Use `read_file` or `grep` to verify each path. Append findings to `/tmp/audit-findings.md`.
+
+### Step 3: Perspective 2 — SYMBOL EXISTENCE
+For every method/type/class/function/imported identifier in code blocks: FIRST classify as USE or DEFINE. ONLY flag USE-intent mentions where grep against the named source file returns no match. Include nearest match (Levenshtein) so the plan can be fixed in one edit.
+
+Use `grep` to verify each USE-intent symbol. Append findings to scratch file.
+
+### Step 4: Perspective 3 — SIGNATURE MATCH
+When the plan's code uses a method with specific parameters or expects a specific return shape, the actual source signature must match. Same intent rule: ONLY flag USE-intent (calls/imports). Plan DEFINES a method? That's the deliverable — don't flag. Flag if a call appears BEFORE the interface-extension step within the task's sequence (out-of-order, see perspective 6).
+
+Use `grep` / `read_file` to verify actual signatures. Append findings to scratch file.
+
+### Step 5: Perspective 4 — IMPORT GRAPH
+Every `import { X } from '...'` in code blocks must resolve under the intent rule. Imports of NEW modules the task creates (listed in "Files: New:") are DEFINE-adjacent. But DO flag if the task forgets to add the corresponding `exports` entry in the workspace package.json (HIGH).
+
+Use `grep` / `read_file` to verify imports. Append findings to scratch file.
+
+### Step 6: Perspective 5 — TEST HARNESS AVAILABILITY
+Every helper/factory/fixture the test USES must exist at the named path. Verify via grep. If the task explicitly adds a new option to an existing helper, that's DEFINE — don't flag the new option. DO flag if test code uses the new option BEFORE the task step that adds it. Helper truly missing = HIGH.
+
+Use `grep` to verify test helpers. Append findings to scratch file.
+
+### Step 7: Perspective 6 — STEP SEQUENCE WITHIN TASK
+Numbered steps must be executable in order. No step depends on output from a later step. MEDIUM unless dependency would halt execution (then HIGH).
+
+Analyze step ordering within each task. Append findings to scratch file.
+
+### Step 8: Perspective 7 — CROSS-TASK DEPENDENCIES
+When task B's code uses something task A introduces, the plan's task ordering must reflect the dependency. B before A = CRITICAL. Dependency exists but undeclared = MEDIUM.
+
+Trace inter-task symbol/file dependencies. Append findings to scratch file.
+
+### Step 9: Perspective 8 — VERIFICATION COMMAND VALIDITY
+Every "Run: <command>" / "verify" instruction must work with the project's actual tooling. Plan says `npm run validate-things` but no such script exists? CRITICAL. Vague verification ("run the test") with no concrete command? MEDIUM.
+
+Use `grep` / `read_file` on `package.json` to verify commands exist. Append findings to scratch file.
+
+### Step 10: Perspective 9 — TASK GRANULARITY
+Each task should be implementable in one focused sub-agent run. Signals of oversized tasks: touches >3 source files; >40 net lines of diff; mixes unrelated concerns; >6 numbered steps. HIGH when task clearly exceeds standard-tier capacity; MEDIUM when borderline. Suggested fix: split into atomic sub-tasks.
+
+Analyze task size from plan text only (no codebase tools needed). Append findings to scratch file.
+
+### Step 11: Perspective 11 — PLACEHOLDER LANGUAGE
+Scan for prose patterns that leave a literal-following worker unable to act. Signals: `TBD`, `TODO`, `implement later`, `fill in details`, `Add appropriate error handling`, `add validation`, `handle edge cases`, `Similar to Task N` (without repeating code), `Write tests for the above` (without test code); steps describing what to do without showing how (missing code block); verification like `make sure it works`. HIGH on load-bearing steps that cannot execute without invention; MEDIUM on vague verification; LOW on cosmetic placeholders in non-load-bearing prose.
+
+Scan plan text only. Append findings to scratch file.
+
+### Step 12: Perspective 12 — PLAN SKELETON
+The plan must carry required structural scaffolding. Flag: missing top-level header (`Goal:` / `Architecture:` / `Tech Stack:`); missing File Structure section; a task with no `Files:` block; a task with no commit step. HIGH when missing structure forces ambiguous file-scope decisions; MEDIUM for missing header fields and per-task `Files:` blocks; LOW for missing commit steps.
+
+Scan plan text only. Append findings to scratch file.
+
+### Step 13: Perspective 10 — SPEC COVERAGE
+**Only if a spec context block is present in your context.** If no spec is available, write "Perspective 10: No spec in context — no findings for this criterion." to the scratch file and skip.
+
+Every load-bearing spec requirement maps to at least one plan task, and no task implements something the spec did not ask for. For unmapped load-bearing requirements: CRITICAL. For supporting requirements (test coverage, observability, non-functional): HIGH. For scope-creep: HIGH if substantive (>1 task or new deliverable), MEDIUM if minor. Implicit mapping (task plausibly covers requirement but doesn't say so) = MEDIUM with suggested fix: add "Covers spec requirement: <quote>" line.
+
+Append findings to scratch file.
+
+### Step 14: Consolidate
+Read `/tmp/audit-findings.md`. Collect all findings across all perspectives, assign per-task verdicts, produce the final JSON output.
+
+## Evidence Grounding (REQUIRED — varies by perspective group)
+
+**Perspectives 1-8 (EXTERNAL CODEBASE COHERENCE) — both sides REQUIRED:**
+- Plan side: exact line from the plan with task ID + section reference.
+- Source side: file path + line number + actual content.
+- For SYMBOL-EXISTENCE findings: include nearest match (Levenshtein).
+- For SIGNATURE-MATCH findings: quote BOTH the plan's call AND the source's actual signature.
+- A finding without both sides on perspectives 1-8 is speculation. Drop it.
+
+**Perspective 10 (SPEC-COVERAGE) — both sides REQUIRED:**
+- Spec side: exact `shall` / `must` / `should` clause from the spec.
+- Plan side: name the task that does or does NOT cover it.
+
+**Perspectives 9, 11, 12 (INTRA-PLAN STRUCTURE) — plan-side quote sufficient:**
+- Quote the exact plan line with task ID + section reference. No codebase evidence needed.
+- For absence findings: name the section that SHOULD contain it and confirm it does not.
+
+## Severity Calibration
+
+- **critical**: plan contradicts codebase in a way that BLOCKS dispatch, OR load-bearing spec requirement has zero covering tasks. Missing modify-target, wrong method name, wrong signature, missing module export, out-of-order task dependency, wrong tooling, uncovered load-bearing spec requirement.
+- **high**: load-bearing ambiguity risking wrong implementation. Multiple matching symbols with no disambiguation. Test harness missing in claimed form. Oversized task that must be split. Substantive scope-creep. Placeholder on load-bearing step. Missing `Files:` block forcing ambiguous file-scope.
+- **medium**: step ordering issue, cross-task dependency unstated but inferable, vague verify command, missing parent dirs for create-targets, implicit spec mapping, vague verification instructions, missing required header/Files block on single task.
+- **low**: stylistic, missing metadata, naming preference, cosmetic placeholder, missing commit step.
+
+## Per-Task Verdict (computed from all findings)
+
+- **EXECUTABLE**: zero CRITICAL or HIGH findings against this task.
+- **PARTIAL**: one or more HIGH findings, no CRITICAL. Task may execute but produces ambiguous result.
+- **BLOCKED**: one or more CRITICAL findings. Task cannot be dispatched as written.
+
+## Self-Validation
+
+Before emitting, check each finding:
+- Does it cite the right evidence shape for its perspective group?
+- Is it categorized to the correct perspective (1-12)?
+- Is severity calibrated to actual dispatch impact?
+- Does it name a specific task ID (or "META" for plan-level findings)?
+
+Findings on perspectives 1-8 missing source-side evidence are downgraded to LOW or dropped. Findings on perspectives 9, 11, 12 with only a plan-side quote are FULLY VALID.
+
+## Anti-Patterns to Avoid
+
+- Speculation without source-file evidence on perspectives 1-8. If you can't open the file and find the line, drop the finding.
+- Flagging general prose-quality on the plan. That's the default audit's job.
+- Flagging perspective 10 without a spec in context. Emit "No findings for this criterion."
+- Inventing findings to fill quota. Zero findings on a perspective is the correct outcome when the dimension passes.
+
+## Output Format
+
+After consolidating all perspective passes, output exactly one JSON block:
+
+```json
+{"findingsCount": 0, "perspectivesCovered": [1,2,3,4,5,6,7,8,9,10,11,12], "overallAssessment": "found|clean", "taskVerdicts": {"A1.1": "EXECUTABLE|PARTIAL|BLOCKED"}, "findings": [{"taskId": "A1.1|META", "perspective": 1, "perspectiveName": "PATH EXISTENCE|SYMBOL EXISTENCE|SIGNATURE MATCH|IMPORT GRAPH|TEST HARNESS|STEP SEQUENCE|CROSS-TASK DEPS|VERIFY CMD|TASK GRANULARITY|SPEC COVERAGE|PLACEHOLDER LANGUAGE|PLAN SKELETON", "severity": "critical|high|medium|low", "planClaim": "<quoted plan line with task+section ref>", "sourceReality": "<file:line + actual content, or spec clause, or plan-side-only for 9/11/12>", "suggestedFix": "<concrete edit>"}]}
+```
+</output>

package/src/skills/audit/implement-skill.md

@@ -0,0 +1,72 @@
+# Audit — Implementer (Skill: Reader-Effectiveness)
+
+You are auditing a SKILL.md file for reader effectiveness. A finding is a place where the skill, as written, would cause a competent reader to dispatch the wrong call, miss a path of use, or fall for a foreseeable anti-pattern.
+
+## Your Execution Strategy
+
+You MUST work through the 7 criteria **one at a time, sequentially**. For each criterion:
+
+1. Read the skill file through the lens of ONLY that criterion
+2. Write any findings to a scratch file at `/tmp/audit-findings.md` (append mode)
+3. If no findings for that criterion, write "Criterion N: No findings." to the scratch file
+4. Move to the next criterion
+
+After all 7 criteria are complete, read the scratch file and consolidate into the final JSON output.
+
+**Do NOT try to evaluate all criteria in one pass.** The sequential approach ensures thorough coverage.
+
+## Why This Audit Exists
+
+A skill is the markdown a caller reads to decide whether to route a request to a tool and how to construct that request. The completion test: would a competent reader given ONLY this skill be able to construct a correct request and avoid the named anti-patterns?
+
+## Execution Steps
+
+### Step 1: Create scratch file
+Write to `/tmp/audit-findings.md`: `# Skill Audit Findings (scratch)`
+
+### Step 2: Criterion 1 — WHEN-TO-USE-SPECIFICITY
+Read the skill. Does the `when_to_use` frontmatter cleanly distinguish this skill from sibling skills? Overlap with another `mma-*` skill without a tiebreaker is a finding. Name the sibling skill that overlaps and quote both `when_to_use` lines. Append findings.
+
+### Step 3: Criterion 2 — INPUT-SHAPE-COMPLETENESS
+Read the skill. For every required JSON input field: is there (a) a name, (b) a type, (c) constraints on valid values, and (d) at least one example? Missing fields, types, or constraints flag. A reader must be able to write a valid request from the skill text alone. Append findings.
+
+### Step 4: Criterion 3 — OUTPUT-SHAPE-CONTRACT
+Read the skill. Is the terminal envelope shape the caller consumes described? Are optional fields marked? Can a caller write a parser from the skill text alone? Append findings.
+
+### Step 5: Criterion 4 — ANTI-PATTERN-COVERAGE
+Read the skill. Does every anti-pattern entry have both a "don't do this" AND a "do this instead"? Anti-patterns mentioned without a corrective flag. Append findings.
+
+### Step 6: Criterion 5 — RECIPE-VS-SKILL-SCOPE
+Read the skill. Does it instruct the reader to call 2+ different tools in sequence? If so, that content belongs in the orchestrator skill, not here. Flag in-skill recipes as scope violations. Append findings.
+
+### Step 7: Criterion 6 — VERSION-FRONTMATTER
+Read the skill. Are `name` / `description` / `when_to_use` / `version` frontmatter present and well-formed? Is `version` the literal `"0.0.0-unreleased"` pre-publish placeholder? Is `name` consistent with the directory name? Append findings.
+
+### Step 8: Criterion 7 — LINK-INTEGRITY
+Read the skill. Do internal cross-references (`./_shared/...`, `mma-other-skill`) point at files that exist? For each broken internal link: name the link text, target path, and whether the target should exist or the link should be updated. Append findings.
+
+### Step 9: Consolidate
+Read `/tmp/audit-findings.md`. Collect all findings, assign severities, produce final JSON.
+
+## Evidence Grounding (REQUIRED)
+
+- Quote the exact section heading + offending line (or name what is missing AND where it should appear).
+- For when_to_use overlap: name the sibling skill + quote both `when_to_use` lines.
+- For input-shape: name the undocumented field + cite the schema where it's exposed.
+- For link-integrity: name the broken link + the file that should exist.
+- A finding without a concrete section reference is opinion — drop it.
+
+## Severity Calibration
+
+- **critical**: routes reader to wrong tool (when_to_use overlap, wrong tool category)
+- **high**: dispatch with wrong fields (input shape incomplete, required field undocumented)
+- **medium**: reader hesitates (anti-pattern without correction, scope unclear, frontmatter malformed)
+- **low**: stylistic / link / metadata fix
+
+## Output Format
+
+Output exactly one JSON block:
+
+```json
+{"findingsCount": 0, "criteriaCovered": ["when-to-use-specificity", "input-shape-completeness", "output-shape-contract", "anti-pattern-coverage", "recipe-vs-skill-scope", "version-frontmatter", "link-integrity"], "overallAssessment": "found|clean", "findings": [{"severity": "critical|high|medium|low", "category": "<criterion-slug>", "claim": "<one sentence>", "evidence": "<quoted section+line>", "suggestion": "<missing or replacement text>"}]}
+```

package/src/skills/audit/implement-spec.md

@@ -0,0 +1,91 @@
+# Audit — Implementer (Spec: Requirement Executability)
+
+You are auditing a requirement spec for executability. A finding is a place where the spec's prose, executed literally by a downstream worker, would produce the wrong outcome or paralyze the executor.
+
+## Your Execution Strategy
+
+You MUST work through the 9 criteria **one at a time, sequentially**. For each criterion:
+
+1. Read the spec through the lens of ONLY that criterion
+2. Write any findings to a scratch file at `/tmp/audit-findings.md` (append mode)
+3. If no findings for that criterion, write "Criterion N: No findings." to the scratch file
+4. Move to the next criterion
+
+After all 9 criteria are complete, read the scratch file and consolidate into the final JSON output.
+
+**Do NOT try to evaluate all criteria in one pass.** The sequential approach ensures thorough coverage — each criterion gets your full attention before moving on.
+
+## Execution Steps
+
+### Step 1: Create scratch file
+Write to `/tmp/audit-findings.md`:
+```
+# Spec Audit Findings (scratch)
+```
+
+### Step 2: Criterion 1 — REQUIREMENT-TESTABILITY
+Read the spec. For every `shall` / `must` / `should` requirement, check: does it have a concrete, observable outcome that a test can assert? Vague verbs ("supports", "handles", "is reliable") without a measurable outcome are findings. Append findings to `/tmp/audit-findings.md`.
+
+### Step 3: Criterion 2 — SCOPE-EXPLICITNESS-AND-DECOMPOSABILITY
+Read the spec. Check two sub-dimensions:
+- (a) EXPLICITNESS — are in-scope and out-of-scope items explicit? Implied scope (mentioned-once-then-dropped, referenced without definition) is a finding.
+- (b) DECOMPOSABILITY — does the spec describe ONE buildable feature, not multiple independent subsystems bundled together? Signals: orthogonal subsystems mixed, multiple top-level "Goals", architecture names >5 net-new modules across non-overlapping concerns.
+Append findings to scratch file.
+
+### Step 4: Criterion 3 — ACCEPTANCE-CRITERIA-COVERAGE
+Read the spec. Does every requirement map to at least one acceptance criterion (or does the spec call out why it is non-acceptance-testable)? Missing mapping is a finding. Append.
+
+### Step 5: Criterion 4 — NON-FUNCTIONAL-CAPTURED
+Read the spec. Are non-functional constraints (latency, security, observability, accessibility, scale) stated where load-bearing, or assumed silently? Silent assumption is a finding. Append.
+
+### Step 6: Criterion 5 — REQUIREMENT-CONFLICT
+Read the spec. Are there two requirements that cannot simultaneously hold? (e.g. "respond in <50ms" + "validate against remote registry on every call"). Append.
+
+### Step 7: Criterion 6 — DECISION-TRACE
+Read the spec. Are decisions that affect downstream implementation (algorithm choice, data shape, integration point) stated with reasoning, not just outcome? Outcome-only is a finding. Append.
+
+### Step 8: Criterion 7 — ASSUMPTION-EXPOSURE
+Read the spec. Are hidden assumptions about caller behavior, environment, or pre-existing state made explicit so the executor can verify them? Hidden assumption is a finding. Append.
+
+### Step 9: Criterion 8 — PLACEHOLDER-SCAN
+Read the spec. Flag: `TBD`, `TODO`, `[fill in]`, `[to be decided]`, `???`, empty section bodies, bulleted lists ending in `...`, tables with empty cells in load-bearing columns. Severity: HIGH on load-bearing sections; MEDIUM elsewhere; LOW on metadata-only sections. Append.
+
+### Step 10: Criterion 9 — DESIGN-DECOMPOSITION-PRESENT
+Read the spec. Flag when any load-bearing dimension is missing:
+- (a) No component decomposition
+- (b) No data flow description
+- (c) No error-handling treatment for implied failure modes
+- (d) No testing strategy section
+Severity HIGH when planner must invent the architecture; MEDIUM when partial. Append.
+
+### Step 11: Consolidate
+Read `/tmp/audit-findings.md`. Collect all findings, assign severities, produce the final JSON output.
+
+## Evidence Grounding (REQUIRED for every finding)
+
+- Quote the exact `shall` / `must` / `should` clause that contains the gap.
+- For requirement conflicts: quote BOTH conflicting clauses.
+- For assumption-exposure: quote the hidden assumption + name what would break.
+- For acceptance-criteria: name the requirement lacking a mapping.
+- A "the spec seems to imply" claim without a quoted clause is NOT evidence — drop it.
+
+## Severity Calibration
+
+- **critical**: literal execution silently ships wrong behavior
+- **high**: executor blocked — cannot proceed without clarification
+- **medium**: clarification round forced — executor can guess but may guess wrong
+- **low**: stylistic / metadata gap — no behavior change
+
+## Scope
+
+- **In scope**: the 9 criteria above.
+- **Out of scope**: implementation details, stylistic preferences, opinions on spec quality.
+- IMPLICIT requirements embedded inside a clause ARE in scope.
+
+## Output Format
+
+After consolidating all criterion passes, output exactly one JSON block:
+
+```json
+{"findingsCount": 0, "criteriaCovered": ["requirement-testability", "scope-explicitness-and-decomposability", "acceptance-criteria-coverage", "non-functional-captured", "requirement-conflict", "decision-trace", "assumption-exposure", "placeholder-scan", "design-decomposition-present"], "overallAssessment": "found|clean", "findings": [{"severity": "critical|high|medium|low", "category": "<criterion-slug>", "claim": "<one sentence>", "evidence": "<quoted clause>", "suggestion": "<the missing sentence>"}]}
+```