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.claude/skills/jade-core-rule-dispatcher/SKILL.md
GitHubJADE 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
- Never modify source files directly — only registry recipe scripts touch source.
- Never contain regex or AST transform logic — all transforms live in recipes.
- One execution = one file + one rule_id.
- All artifact writes use tmp-file + atomic rename.
Required input
artifacts/05-rule-batch-{rule_id}.json— task entry listartifacts/01-breaking-changes-manifest.json— rule definitionsrecipe-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).