jade-core-rule-dispatcher

Routes rule tasks to registry recipes via recipe-registry.json. Handles LOAD/MATCH/RECORD workflow but delegates all transform logic to recipe subprocesses. Contains ZERO version-specific or rule-spec

SKILL.md

GitHub

JADE Core Rule Dispatcher

Objective

Route a single rule task to the correct registry recipe. The dispatcher contains zero transform logic — its only job is to load the task, find the matching recipe in recipe-registry.json, invoke the recipe script as a subprocess, and record the result.

Core constraints

  1. Never modify source files directly — only registry recipe scripts touch source.
  2. Never contain regex or AST transform logic — all transforms live in recipes.
  3. One execution = one file + one rule_id.
  4. All artifact writes use tmp-file + atomic rename.

Required input

  • artifacts/05-rule-batch-{rule_id}.json — task entry list
  • artifacts/01-breaking-changes-manifest.json — rule definitions
  • recipe-registry.json (in dispatcher directory)

Produced output

  • artifacts/06-fix-results-{rule_id}.json — aggregate array of fix records (per-flag)

Recipe invocation contract

The dispatcher invokes recipe scripts as:

python <recipe-script> --file <path> --line <num>

Registry recipe scripts MUST:

  • Exit 0 on success, non-zero on failure
  • Print a single JSON line to stdout: {"status": "FIXED|FAILED|SKIPPED|DEFERRED", "changes": N, "warnings": [...], "errors": [...], "diff_summary": "..."}
  • Handle file I/O internally (read, transform, atomic write)

The dispatcher records each result with task_id, rule_id, file, status, match_count, match_region, match_context, diff_summary, verification_hint, errors, warnings, and applied_at.

Fix strategy format

In 01-breaking-changes-manifest.json, rules specify:

"fix_strategy": "recipe:jade-recipe-java1.5-generics"

The dispatcher looks up rule_id in recipe-registry.json to resolve the actual script path.

Script

Use scripts/dispatcher.py:

python scripts/dispatcher.py \
  --artifacts-dir migration-runs/sample/artifacts \
  --rule-id RAW_TYPES \
  --task-id RAW_TYPES-0001

Agent mode

A recipe-registry.json entry may carry "mode": "agent" instead of a "script" field (see skill_md in place of script). An entry with no mode key behaves exactly as before -- this section only applies once a rule's registry entry explicitly opts in.

For an agent-mode rule, the dispatcher never spawns a recipe subprocess. Instead it turns a 05-rule-shards-<rule_id>.json plan (produced by jade-core-knowledge-graph's plan_shards.py) into a self-contained task list, and later validates + records the envelope a subagent hands back for one shard at a time:

# Turn the shard plan into a task list (05-agent-tasks-<rule_id>.json).
python scripts/dispatcher.py \
  --artifacts-dir migration-runs/sample/artifacts \
  --rule-id THREAD_STOP_DISABLED \
  --emit-agent-tasks \
  --workspace-root migration-runs/sample/workspace

# After a subagent has worked one shard and written its result envelope
# (06-agent-result-<rule_id>-<shard_id>.json, schema below), record it.
python scripts/dispatcher.py \
  --artifacts-dir migration-runs/sample/artifacts \
  --rule-id THREAD_STOP_DISABLED \
  --record-agent-result \
  --shard-id THREAD_STOP_DISABLED-body-local-001 \
  --result-file migration-runs/sample/artifacts/06-agent-result-THREAD_STOP_DISABLED-THREAD_STOP_DISABLED-body-local-001.json

--emit-agent-tasks and --record-agent-result are mutually exclusive and both refuse (exit 3, no artifact written) a registry entry that is not mode="agent". Neither ever opens a source file directly -- both work only from the shard plan and the envelope, both of which carry paths and metadata, never file content.

Result-envelope schema (one per shard, written by the subagent session, never by this script):

{
  "schema_version": 1,
  "rule_id": "THREAD_STOP_DISABLED",
  "shard_id": "THREAD_STOP_DISABLED-body-local-001",
  "status": "FIXED",
  "match_quality": "exact",
  "diff_summary": "...",
  "files": [
    {"file": "...", "match_count": 1, "changes": 1,
     "touched_line_start": 10, "touched_line_end": 12,
     "migration_skip_marker": false, "diff_summary": "..."}
  ],
  "errors": [],
  "warnings": []
}

Every file entry's file must be one of the shard's editable_files -- otherwise --record-agent-result refuses the whole envelope (exit 3, no 06-fix-results-* write) rather than record a partial, contract-violating result. A declared FIXED result is promoted to NEEDS_REVIEW when the final confidence is low, matches are ambiguous, the fix strategy calls for manual review, the diff falls outside the flagged region, the rule is a BEHAVIOR_CHANGE, or a file carries a MIGRATION-SKIP marker -- FAILED is never promoted or demoted.

Exit codes: --emit-agent-tasks returns 0 (clean), 1 (task list written with warnings) or 3 (structural error, e.g. a bad shard plan or overlapping shards -- nothing is written). --record-agent-result returns 0 (FIXED/SKIPPED/DEFERRED), 2 (FAILED), 3 (contract violation -- nothing is written) or 4 (NEEDS_REVIEW).