agent-threader 2.0.5

package/skill/build/compile.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+// compile.mjs -- Assemble compiled/ output from skill fragments and platform wrappers.
+// Usage:
+//   node skill/build/compile.mjs              # build compiled/ directory
+//   node skill/build/compile.mjs --validate   # validate fragment references only
+//   node skill/build/compile.mjs --watch      # rebuild on changes (basic poll)
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, watchFile } from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "..");
+const SKILL_DIR = path.join(ROOT, "skill");
+const FRAGMENTS_DIR = path.join(SKILL_DIR, "fragments");
+const SKILLS_DIR = path.join(SKILL_DIR, "skills");
+const MANIFEST_PATH = path.join(SKILL_DIR, "build", "manifest.json");
+const COMPILED_DIR = path.join(ROOT, "compiled");
+const MANAGED_MARKER = "managed_by: agent-threader";
+
+function loadManifest() {
+  if (!existsSync(MANIFEST_PATH)) {
+    console.error(`  ERROR: manifest not found: ${MANIFEST_PATH}`);
+    process.exit(1);
+  }
+
+  const raw = readFileSync(MANIFEST_PATH, "utf8");
+  const manifest = JSON.parse(raw);
+  const skills = manifest?.skills;
+
+  if (!skills || typeof skills !== "object" || Array.isArray(skills)) {
+    console.error("  ERROR: manifest.json must contain an object at skills");
+    process.exit(1);
+  }
+
+  return manifest;
+}
+
+function getSkillEntries(manifest) {
+  return Object.entries(manifest.skills);
+}
+
+function extractIncludes(raw) {
+  return [...new Set([...raw.matchAll(/\{\{include:([\w/.-]+)\}\}/g)].map(([, ref]) => ref))];
+}
+
+// ─── Fragment inclusion ──────────────────────────────────────────────────────
+
+function resolveIncludes(content, baseDir) {
+  return content.replace(/\{\{include:([\w/.-]+)\}\}/g, (_match, ref) => {
+    const fragPath = path.join(FRAGMENTS_DIR, ref);
+    if (!existsSync(fragPath)) {
+      console.warn(`  WARNING: fragment not found: ${ref}`);
+      return `<!-- MISSING FRAGMENT: ${ref} -->`;
+    }
+    const fragContent = readFileSync(fragPath, "utf8").trim();
+    // Recursively resolve nested includes
+    return resolveIncludes(fragContent, path.dirname(fragPath));
+  });
+}
+
+function compileSkill(skillName, sourceRelPath) {
+  const skillSrc = path.join(SKILL_DIR, sourceRelPath);
+  if (!existsSync(skillSrc)) {
+    console.error(`  ERROR: skill source not found: ${skillSrc}`);
+    process.exit(1);
+  }
+  const raw = readFileSync(skillSrc, "utf8");
+  const compiled = resolveIncludes(raw, path.dirname(skillSrc));
+  return `<!-- ${MANAGED_MARKER} -->\n${compiled}`;
+}
+
+// ─── Validation mode ─────────────────────────────────────────────────────────
+
+function validateFragmentRefs() {
+  let errors = 0;
+  const manifest = loadManifest();
+  const skillEntries = getSkillEntries(manifest);
+
+  for (const [skillName, skillConfig] of skillEntries) {
+    if (!skillConfig || typeof skillConfig !== "object") {
+      console.error(`  INVALID: ${skillName} manifest entry must be an object`);
+      errors++;
+      continue;
+    }
+
+    const source = skillConfig.source;
+    const declaredFragments = Array.isArray(skillConfig.fragments) ? skillConfig.fragments : [];
+
+    if (typeof source !== "string" || source.length === 0) {
+      console.error(`  INVALID: ${skillName} must declare a non-empty source path`);
+      errors++;
+      continue;
+    }
+
+    const skillSrc = path.join(SKILL_DIR, source);
+    if (!existsSync(skillSrc)) {
+      console.error(`  MISSING: ${skillName} source -> ${source}`);
+      errors++;
+      continue;
+    }
+
+    const raw = readFileSync(skillSrc, "utf8");
+    const referenced = extractIncludes(raw);
+
+    for (const ref of referenced) {
+      const fragPath = path.join(FRAGMENTS_DIR, ref);
+      if (!existsSync(fragPath)) {
+        console.error(`  MISSING: ${skillName} include -> ${ref}`);
+        errors++;
+      }
+      if (!declaredFragments.includes(ref)) {
+        console.error(`  UNDECLARED: ${skillName} includes ${ref} but manifest does not declare it`);
+        errors++;
+      }
+    }
+
+    for (const ref of declaredFragments) {
+      const fragPath = path.join(FRAGMENTS_DIR, ref);
+      if (!existsSync(fragPath)) {
+        console.error(`  MISSING: ${skillName} declared fragment -> ${ref}`);
+        errors++;
+      }
+      if (!referenced.includes(ref)) {
+        console.error(`  UNUSED: ${skillName} declares ${ref} but source does not include it`);
+        errors++;
+      }
+    }
+  }
+
+  if (errors > 0) {
+    console.error(`\nValidation failed: ${errors} issue(s).`);
+    process.exit(1);
+  }
+  console.log("Manifest and fragment references are valid.");
+}
+
+// ─── Emit helpers ────────────────────────────────────────────────────────────
+
+function emit(filePath, content) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, "utf8");
+  console.log(`  wrote: ${path.relative(ROOT, filePath)}`);
+}
+
+// ─── Platform emitters ───────────────────────────────────────────────────────
+
+function emitClaude(skillName, compiledContent) {
+  emit(path.join(COMPILED_DIR, "claude", skillName, "SKILL.md"), compiledContent);
+}
+
+function emitCursor(skillName, compiledContent) {
+  // Cursor rule (.mdc)
+  const ruleContent = [
+    `---`,
+    `description: "${skillName} skill"`,
+    `globs: []`,
+    `alwaysApply: false`,
+    `---`,
+    ``,
+    compiledContent,
+  ].join("\n");
+  emit(path.join(COMPILED_DIR, "cursor", "rules", `${skillName}.mdc`), ruleContent);
+  // Cursor skill
+  emit(path.join(COMPILED_DIR, "cursor", "skills", skillName, "SKILL.md"), compiledContent);
+}
+
+function emitWindsurf(skillName, compiledContent) {
+  // Windsurf rule
+  emit(path.join(COMPILED_DIR, "windsurf", "rules", `${skillName}.md`), compiledContent);
+  // Windsurf skill
+  emit(path.join(COMPILED_DIR, "windsurf", "skills", skillName, "SKILL.md"), compiledContent);
+}
+
+function emitOpencode(skillName, compiledContent) {
+  emit(path.join(COMPILED_DIR, "opencode", `${skillName}.md`), compiledContent);
+}
+
+function emitCodex(skillName, compiledContent) {
+  emit(path.join(COMPILED_DIR, "codex", skillName, "SKILL.md"), compiledContent);
+}
+
+// ─── Main build ──────────────────────────────────────────────────────────────
+
+function build() {
+  console.log("==> Compiling skills...");
+  const manifest = loadManifest();
+  const skillEntries = getSkillEntries(manifest);
+
+  for (const [skillName, skillConfig] of skillEntries) {
+    const source = skillConfig?.source;
+    if (typeof source !== "string" || source.length === 0) {
+      console.error(`  ERROR: ${skillName} must declare a non-empty source path in manifest`);
+      process.exit(1);
+    }
+    console.log(`  ${skillName}:`);
+    const compiled = compileSkill(skillName, source);
+
+    emitClaude(skillName, compiled);
+    emitCursor(skillName, compiled);
+    emitWindsurf(skillName, compiled);
+    emitOpencode(skillName, compiled);
+    emitCodex(skillName, compiled);
+  }
+
+  console.log("==> Done.");
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+if (args.includes("--validate")) {
+  validateFragmentRefs();
+} else if (args.includes("--watch")) {
+  build();
+  console.log("\nWatching for changes...");
+  const watchDirs = [FRAGMENTS_DIR, SKILLS_DIR];
+  for (const dir of watchDirs) {
+    if (!existsSync(dir)) continue;
+    const files = readdirSync(dir, { recursive: true });
+    for (const file of files) {
+      const fullPath = path.join(dir, file);
+      if (statSync(fullPath).isFile()) {
+        watchFile(fullPath, { interval: 1000 }, () => {
+          console.log(`\nChange detected: ${path.relative(ROOT, fullPath)}`);
+          build();
+        });
+      }
+    }
+  }
+  watchFile(MANIFEST_PATH, { interval: 1000 }, () => {
+    console.log(`\nChange detected: ${path.relative(ROOT, MANIFEST_PATH)}`);
+    build();
+  });
+} else {
+  build();
+}

package/skill/build/manifest.json

@@ -0,0 +1,21 @@
+{
+  "version": "1",
+  "skills": {
+    "agent-threader": {
+      "source": "skills/agent-threader/agent-threader.md",
+      "fragments": [
+        "domain/architecture-overview.md",
+        "domain/contracts.md",
+        "domain/pbh-healing.md",
+        "domain/verification-safety.md",
+        "domain/adapter-model.md",
+        "domain/state-resume.md",
+        "meta/schemas-reference.md",
+        "meta/templates-reference.md",
+        "common/model-selection.md",
+        "common/portability-rules.md",
+        "common/workflow.md"
+      ]
+    }
+  }
+}

package/skill/fragments/common/model-selection.md

@@ -0,0 +1,11 @@
+### Self-Healing: Model Selection Rule
+
+When the user requests a self-healing runner, ask which models to use before generating code:
+
+- **Worker CLI and model** -- runs the inner loop (can be fast/cheap)
+- **Healer CLI and model** -- runs the outer diagnosis loop (should be more capable)
+
+If the user does not specify, state the defaults explicitly before proceeding:
+
+- Worker: the CLI the user is already using, default model
+- Healer: same CLI family, stronger model tier

package/skill/fragments/common/portability-rules.md

@@ -0,0 +1,16 @@
+### Portability Rules
+
+Platform wrappers may adapt:
+
+- invocation command and flags
+- prompt transport (`stdin`, argument, or PTY)
+- approval handling and setup notes
+
+Platform wrappers MUST preserve:
+
+- contract field names and sentinel strings
+- parser behavior
+- PBH defaults and convergence rules
+- state transitions and resume semantics
+
+Platform wrappers MUST NOT redefine architecture, contracts, or healing policy.

package/skill/fragments/common/workflow.md

@@ -0,0 +1,12 @@
+### Workflow
+
+1. Define the unit of work (component, story, work package, ticket, file).
+2. Create the manifest (`manifest.v2` JSON).
+3. Write shared context and per-task prompts.
+4. Define the completion contract in the prompt (instruct the worker to emit `<<<TASK_RESULT_V2>>>`).
+5. Choose the CLI adapter (`agent`, `opencode`, `claude`).
+6. Build the orchestrator (use `templates/` as starting point).
+7. Run sequential first, add concurrency after contracts and parsing are stable.
+8. Add verification gates (build, test, lint, smoke).
+9. Add healing only after the base loop works (`--heal auto`).
+10. Resume with `--resume` after interruptions.

package/skill/fragments/domain/adapter-model.md

@@ -0,0 +1,42 @@
+### Adapter Model
+
+Adapters are the only place where CLI-specific behavior lives. The orchestrator core never calls CLIs directly -- it goes through `CliAdapter.execute`.
+
+### Adapter Responsibilities
+
+- Construct the concrete CLI invocation (command, flags, working directory).
+- Decide whether prompt delivery uses stdin, argv, or PTY interaction.
+- Manage PTY or expect requirements for interactive CLIs.
+- Capture combined stdout and stderr to the execution log.
+- Return execution artifacts to the orchestrator.
+- Delegate contract parsing and schema validation to the shared parser utilities.
+
+### Orchestrator Boundary
+
+The orchestrator must:
+
+- Never call CLIs directly except through `CliAdapter.execute`.
+- Never parse raw logs without going through parser and validator modules.
+- Never assume exit code alone means success.
+- Remain CLI-agnostic outside the adapter boundary.
+
+### Reference Adapters
+
+Initial adapters: `agent`, `opencode`, `claude`. All share one orchestrator contract model.
+
+### Interactive CLI Handling
+
+For interactive CLIs, prompt rescue logic and TTY heuristics are adapter-local. Interactive adapters should implement ANSI stripping, bounded idle detection, finite rescue attempts, and explicit completion detection.
+
+### CliAdapter Interface
+
+```typescript
+interface CliAdapter {
+  id: string;
+  capabilities: { stdinPrompt: boolean; argPrompt: boolean; pty: boolean; interactive: boolean };
+  prepare(task, ctx): PreparedInvocation;
+  execute(invocation, ctx): Promise<ExecutionArtifact>;
+  extractResult(artifact, ctx): Promise<TaskResultV2 | ParserFailure>;
+  healthcheck(ctx): Promise<AdapterHealth>;
+}
+```

package/skill/fragments/domain/architecture-overview.md

@@ -0,0 +1,36 @@
+### Architecture Overview
+
+The v2 system has five moving parts:
+
+1. **Manifest** -- declares work items, dependencies, timeouts, and verification profiles.
+2. **Orchestrator** -- owns scheduling, parsing, verification, checkpointing, healing, and retry policy. The orchestrator is the single source of truth for task status.
+3. **Adapters** -- CLI-specific execution layers (`agent`, `opencode`, `claude`) that the orchestrator calls through a uniform `CliAdapter` interface.
+4. **Worker** -- the model invocation that performs task work and emits a `task_result.v2` JSON contract fenced by `<<<TASK_RESULT_V2>>>` sentinels.
+5. **Healer** -- the model invocation that diagnoses fixable failures and emits a `heal_decision.v2` JSON contract fenced by `<<<HEAL_DECISION_V2>>>` sentinels.
+
+### Control Flow
+
+```text
+Manifest
+  -> Orchestrator
+    -> Adapter -> Worker
+    -> Parser and Schema Validator
+    -> Verification Gates
+    -> State Checkpoint
+    -> Healer (at batch checkpoints when policy requires)
+      -> Patch Validation and Application
+    -> Resume or Escalate
+```
+
+Worker and healer outputs are candidate data until the orchestrator validates and commits them to state. Exit code alone is never treated as task success.
+
+### Canonical Source Tree
+
+```text
+agent-threader/
+  SKILL.md          -- skill entrypoint
+  SPEC.md           -- normative architecture specification
+  schemas/          -- JSON schemas for all contracts
+  templates/        -- TypeScript scaffolding (types, parser, orchestrator utilities)
+  platforms/        -- thin wrappers for Codex, Cursor, Claude, Windsurf
+```

package/skill/fragments/domain/contracts.md

@@ -0,0 +1,31 @@
+### Contracts
+
+All public contracts are JSON, versioned (`"2.0"`), and schema-validated. Machine-readable schemas live in `schemas/`.
+
+### manifest.v2
+
+Declares tasks with required fields: `id`, `prompt_ref`, `depends_on`, `timeout_sec`, `verify_profile`. Optional: `context_refs`, `priority`, `retry_policy`, `metadata`.
+
+Tasks are topologically sorted by `depends_on`. Lower `priority` values run first. A task cannot start until all dependencies are `DONE`.
+
+### task_result.v2
+
+Emitted by the worker inside `<<<TASK_RESULT_V2>>>` / `<<<END_TASK_RESULT_V2>>>` sentinels.
+
+Required fields: `contract_version`, `task_id`, `status` (DONE | BLOCKED | FAILED | CONTRACT_ERROR), `summary`.
+
+Optional: `changed_files`, `writes[]` (with `path`, `op`, `encoding`, `content` or `content_ref`), `evidence` (commands, log_refs, notes), `failure_class`.
+
+### heal_decision.v2
+
+Emitted by the healer inside `<<<HEAL_DECISION_V2>>>` / `<<<END_HEAL_DECISION_V2>>>` sentinels.
+
+Required fields: `contract_version`, `scope` (task | batch | epoch), `decision` (RETRY | ESCALATE | NOT_FIXABLE), `failure_class`, `root_cause`, `patches[]`.
+
+Patch targets: `shared_context`, `task_prompt`, `runtime_patch`, `contract_hint`. Each patch has `target`, `operation` (replace | append | merge), and `content`.
+
+Optional: `learned_rule`, `escalations[]`, `retry_policy` (`reset_tasks`, `retry_window`).
+
+### state.v2
+
+Persistent run state with: `run_id`, `run_status` (RUNNING | COMPLETED | ABORTED), `policy`, per-task state (status, attempts, failure signatures, history), and `healing_rounds[]`. Written atomically via temp file + rename.

package/skill/fragments/domain/pbh-healing.md

@@ -0,0 +1,47 @@
+### Progressive Batch Healing (PBH)
+
+PBH is the default healing strategy. It starts with a small healing window, grows when stable, shrinks when unstable, and stops when automation is no longer justified.
+
+### Scheduling Modes
+
+| Mode | Meaning |
+| --- | --- |
+| `auto` | PBH with adaptive growth and shrink. **Default.** |
+| `off` | Healing disabled. |
+| `task` | Heal only the single failed task. Window size is always 1. |
+| `batch` | Heal at fixed batch checkpoints. Default fixed size is 5. |
+| `epoch` | Attempt all pending tasks before healing. |
+
+### PBH Defaults
+
+- `heal.schedule = auto`
+- `batch.strategy = fibonacci` (sequence: 1, 2, 3, 5, 8, 13, ...)
+- `failure_threshold = 0.2`
+- `max_worker_attempts_per_task = 2`
+- `max_heal_rounds_per_window = 2`
+- `max_total_heal_rounds = 8`
+- `signature_repeat_limit = 2`
+
+### PBH Behavior
+
+- Zero failures in a window: advance to the next larger batch size.
+- Failure rate > 0 but <= threshold: run healer once, retry the same window.
+- Failure rate > threshold: shrink one batch level, isolate repeated signatures.
+- Same signature repeats after healing: escalate that task.
+- No convergence (failing set unchanged across rounds): abort the run.
+
+### Healable vs Non-Healable
+
+Healable: `prompt_gap`, `missing_paths`, `weak_contract`, `contract_error`, `output_format`, `timeout`, `transient_infra`.
+
+Non-healable: `blocked_external`, `real_bug`.
+
+`build_error`, `test_error`, `smoke_error` may be healable when evidence points to prompt or configuration rather than a genuine product defect.
+
+### Convergence
+
+Healing converges when at least one of: total failing count drops, repeated signature count drops, or a broad failure class narrows to a local issue. Healing is non-convergent when the same set persists, same signatures repeat, or budget is exhausted.
+
+### Healer Authority
+
+The healer may emit bounded runtime patches (`timeout_sec`, `concurrency`, `current_batch_size`) validated by the orchestrator against operator limits. The healer must not modify `heal.schedule`, `batch.strategy`, verification commands, protected-file rules, parser behavior, or model identity.

package/skill/fragments/domain/state-resume.md

@@ -0,0 +1,34 @@
+### State, Resume, and Convergence
+
+### Atomic State Writes
+
+Mandatory. The orchestrator writes state via a temporary file followed by atomic rename on the same filesystem. State is checkpointed after every task attempt and every healing round.
+
+### Resume Semantics
+
+- `DONE` tasks are skipped on resume if `manifest_digest` still matches.
+- If `manifest_digest` changes, the orchestrator warns or forces reconciliation.
+- `ESCALATED` tasks are not retried automatically.
+- `FAILED` and `BLOCKED` tasks are eligible only if retry policy allows.
+
+Reconciliation handles: tasks removed since last run, tasks added, tasks whose `prompt_ref`, `depends_on`, or `verify_profile` changed.
+
+### Failure Signature Generation
+
+Stable failure signatures follow this algorithm:
+
+1. Start with the normalized failure class.
+2. Extract the primary stable signal from parser output, verification logs, or error codes.
+3. Remove timestamps, absolute paths, task IDs, and unstable numbers.
+4. Lowercase and collapse whitespace.
+5. Truncate to a stable maximum length.
+
+Format: `<failure_class>:<normalized_signal>` (e.g., `build_error:missing_cn_import`).
+
+### Escalation Rules
+
+Per-task: escalate when a task repeats the same signature `signature_repeat_limit` times after healing, or when a non-healable failure exhausts retry policy.
+
+Per-run: escalate when `max_total_heal_rounds` is exhausted without convergence, or continuing would only repeat the same failure set.
+
+Escalated tasks remain in state for reporting. Aborted runs record `run_status: ABORTED` with a non-empty `abort_reason`.

package/skill/fragments/domain/verification-safety.md

@@ -0,0 +1,33 @@
+### Verification and Safety Model
+
+### Verification Ownership
+
+Verification always belongs to the orchestrator. It runs after successful parse and before final task success. The worker may report evidence, but does not own pass/fail classification.
+
+### Verification Layers
+
+| Layer | Timing | Purpose |
+| --- | --- | --- |
+| Post-parse validation | After parsing worker output | Contract integrity, candidate writes, path safety |
+| Post-write build/test | After writes are applied | Build, test, lint, or type failures caused by the change |
+| Final smoke/browser | After build and test pass | Runtime behavior, UI behavior, custom project checks |
+
+### Allowed Write Path
+
+1. Worker emits `writes[]` in `task_result.v2`.
+2. Orchestrator validates those writes.
+3. Orchestrator applies those writes.
+4. Orchestrator verifies the result.
+
+### Required Write Safeguards
+
+- Path normalization (writes cannot escape workspace root).
+- Protected-file denylist.
+- Shrinkage detection: reject replacement when original > 100 bytes and replacement < 50% of original size (unless explicitly allowed).
+- Optional `sha256_before` precondition validation.
+- Backup before write.
+- Rollback on verification failure.
+
+### Healer Patch Safety
+
+Healer patches follow the same validation model. The healer is forbidden from editing product source files directly, disabling verification, bypassing protected-file rules, or changing healing schedule mid-run.

package/skill/fragments/meta/schemas-reference.md

@@ -0,0 +1,13 @@
+### Schemas
+
+Machine-readable JSON schemas (JSON Schema 2020-12) live in `schemas/`:
+
+| Schema | Contract |
+| --- | --- |
+| `manifest.v2.json` | Task manifest: tasks with deps, timeouts, verify profiles |
+| `verify_profile.v2.json` | Operator-defined verification profiles with steps and rollback flag |
+| `task_result.v2.json` | Worker output: task_id, status, summary, optional writes and evidence |
+| `heal_decision.v2.json` | Healer output: decision, patches, learned_rule |
+| `state.v2.json` | Persistent run state: run_status, policy, per-task state, healing_rounds |
+
+These schemas are the machine-readable authority. The orchestrator validates all contracts against them before state mutation.

package/skill/fragments/meta/templates-reference.md

@@ -0,0 +1,11 @@
+### Templates
+
+Reference implementation skeletons live in `templates/`:
+
+| File | Contents |
+| --- | --- |
+| `types.ts` | TypeScript type definitions for all v2 contracts: `ManifestV2`, `TaskResultV2`, `HealDecisionV2`, `StateV2`, `CliAdapter` interface, failure classes, PBH fibonacci sequence, default policy |
+| `parser.ts` | Shared parser and validator: sentinel extraction (last block wins), JSON repair (strip markdown fences, trailing commas, JS comments), task result and heal decision validation, failure signature generation |
+| `orchestrator.ts` | Shared runtime utilities: `writeAtomicJson` (temp file + rename) and `stableFailureSignature` (normalizes failure fingerprints) |
+
+These templates are starting points for downstream runner implementations. Copy them into your project and extend as needed.

package/skill/schemas/heal_decision.v2.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "heal_decision.v2.json",
+  "title": "Heal Decision v2",
+  "description": "Healer output contract. Emitted inside <<<HEAL_DECISION_V2>>> fences.",
+  "type": "object",
+  "required": ["contract_version", "scope", "decision", "failure_class", "root_cause", "patches"],
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "2.0"
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["task", "batch", "epoch"],
+      "description": "Advisory healer view of the current healing level."
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["RETRY", "ESCALATE", "NOT_FIXABLE"]
+    },
+    "failure_class": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Normalized failure class the healer is addressing."
+    },
+    "root_cause": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-sentence diagnosis of the repeated issue."
+    },
+    "patches": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/patch" },
+      "description": "Allowed patch operations."
+    },
+    "learned_rule": {
+      "type": "string",
+      "description": "Reusable rule recorded by the orchestrator for future runs."
+    },
+    "escalations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["task_id", "reason"],
+        "properties": {
+          "task_id": { "type": "string" },
+          "reason": { "type": "string" }
+        },
+        "additionalProperties": false
+      },
+      "description": "Explicit per-task escalation records."
+    },
+    "retry_policy": { "$ref": "#/$defs/retry_policy" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "patch": {
+      "type": "object",
+      "required": ["target", "operation"],
+      "properties": {
+        "target": {
+          "type": "string",
+          "enum": ["shared_context", "task_prompt", "runtime_patch", "contract_hint"]
+        },
+        "operation": {
+          "type": "string",
+          "enum": ["replace", "append", "merge"]
+        },
+        "path": {
+          "type": "string",
+          "description": "Required for shared_context and task_prompt file replacements."
+        },
+        "task_id": {
+          "type": "string",
+          "description": "Required when target is task_prompt."
+        },
+        "content": {
+          "description": "Patch payload. String for text replacements, object for runtime merge content."
+        }
+      },
+      "additionalProperties": false
+    },
+    "retry_policy": {
+      "type": "object",
+      "properties": {
+        "reset_tasks": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tasks to reset to pending for retry."
+        },
+        "retry_window": {
+          "type": "string",
+          "enum": ["same_window", "shrink_window", "next_epoch"]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}