skip to content

The map pattern

Write a roster of independent tasks from a source document, check it, then build, gate and repair every task in turn. One failed task does not end the run; a streak of them does.

map — a roster of independent tasks, each built and gated on its own

A roster is a directory of task files, enumerated in filename order: each carries +++-delimited front matter with its gate command and a prose body that is the worker's whole prompt.

map declares no run-scoped gate. Each task's own gate judges that task, and nothing judges the run as a whole.

map 
[header]
pattern_language_compatibility = "3"
entry = "map"
include = ["troubleshoot.toml", "merge.toml"]
merge = "merge"
on_stop = "map_write_handover"
description = """
Write a roster of independent tasks from a source document, check it, then build, gate and repair
every task in turn. One failed task does not end the run; a streak of them does.
"""

[[header.cli_flags]]
flag = "map"
value_parameter = "source"

[patterns.map]

[[patterns.map.parameters]]
name = "source"
kind = "path"
declared_plan_source = true
description = "The document the roster is written from; it is also the run's identity."

[[patterns.map.parameters]]
name = "merge_attempt_ceiling"
kind = "text"
default = "2"
description = "The finish-time merge repair ceiling passed to the bundled merge pattern."

[[patterns.map.parameters]]
name = "troubleshoot_prompt"
kind = "prompt-id"
default = "troubleshoot"
description = "The troubleshoot pass's prompt, used by map task repair and finish-time merge repair."

[[patterns.map.steps]]
name = "write_roster"
title = "Write Map Task Roster"
type = "agent"
stage = "plan"
prompt = "write-map-roster"
inputs = ["{{source}}"]
on_plan_change = "nothing"
outputs = [
  { name = "roster", path = "state/roster/" },
]

An empty roster directory is itself a complaint, and the complaint file is what a rewrite reads.

map 
[[patterns.map.steps]]
name = "check_roster"
title = "Check Map Task Roster"
type = "command"
run = '''
mkdir -p "$orchestration/run" "$orchestration/state"
complaint="$orchestration/run/roster-complaint.md"
: > "$complaint"
if ! test -d "$roster" || ! find "$roster" -type f | grep -q .
then
  echo "The roster directory is empty." >> "$complaint"
fi
for task in "$roster"/*
do
  test -f "$task" || continue
  grep -q '^gate = ' "$task" || echo "$task carries no gate command." >> "$complaint"
  grep -q '^+++$' "$task" || echo "$task has no front matter." >> "$complaint"
done
if test -s "$complaint"
then printf no > "$orchestration/state/roster-check.txt"
else printf yes > "$orchestration/state/roster-check.txt"
fi
'''
outputs = [
  { name = "roster_check", path = "state/roster-check.txt", values = ["yes", "no"] },
  { name = "roster_complaint", path = "run/roster-complaint.md", scope = "run" },
]

[[patterns.map.steps]]
if = "roster_check"
then = { yes = "run_roster", no = "rewrite_roster" }
else = "stop_roster_check_absent"

[[patterns.rewrite_roster.steps]]
name = "route_to_rewrite_roster"
type = "call"
pattern = "map_with_complaint"

[patterns.rewrite_roster.steps.parameters]
source = "{{source}}"
complaint = "{{roster_complaint}}"

A roster that failed the check is rewritten against the complaint and checked again; a failed rewrite calls this pattern again, and nothing bounds that recursion.

map 
[patterns.map_with_complaint]

[[patterns.map_with_complaint.parameters]]
name = "source"
kind = "path"
description = "The document the roster is written from."

[[patterns.map_with_complaint.parameters]]
name = "complaint"
kind = "path"
description = "The roster-check complaint the rewrite must address."

[[patterns.map_with_complaint.steps]]
name = "rewrite_roster_from_complaint"
title = "Rewrite Map Task Roster"
type = "agent"
stage = "plan"
prompt = "write-map-roster"
inputs = ["{{source}}", "{{complaint}}"]
on_plan_change = "nothing"
outputs = [
  { name = "rewritten_roster", path = "state/rewritten-roster/" },
]

[[patterns.map_with_complaint.steps]]
name = "check_rewritten_roster"
title = "Check Rewritten Map Task Roster"
type = "command"
run = '''
mkdir -p "$orchestration/run" "$orchestration/state"
complaint="$orchestration/run/rewritten-roster-complaint.md"
: > "$complaint"
if ! test -d "$rewritten_roster" || ! find "$rewritten_roster" -type f | grep -q .
then
  echo "The roster directory is empty." >> "$complaint"
fi
for task in "$rewritten_roster"/*
do
  test -f "$task" || continue
  grep -q '^gate = ' "$task" || echo "$task carries no gate command." >> "$complaint"
  grep -q '^+++$' "$task" || echo "$task has no front matter." >> "$complaint"
done
if test -s "$complaint"
then printf no > "$orchestration/state/rewritten-roster-check.txt"
else printf yes > "$orchestration/state/rewritten-roster-check.txt"
fi
'''
outputs = [
  { name = "rewritten_roster_check", path = "state/rewritten-roster-check.txt", values = ["yes", "no"] },
  { name = "rewritten_roster_complaint", path = "run/rewritten-roster-complaint.md", scope = "run" },
]

[[patterns.map_with_complaint.steps]]
if = "rewritten_roster_check"
then = { yes = "run_rewritten_roster", no = "rewrite_rewritten_roster" }
else = "stop_rewritten_roster_check_absent"

[[patterns.rewrite_rewritten_roster.steps]]
type = "call"
pattern = "map_with_complaint"

[patterns.rewrite_rewritten_roster.steps.parameters]
source = "{{source}}"
complaint = "{{rewritten_roster_complaint}}"

[[patterns.run_rewritten_roster.steps]]
name = "run_rewritten_tasks"
type = "for"
list = { directory = "{{rewritten_roster}}" }
body = "map_task"
fail = "continue"

fail = "continue" covers only what the body did not route — a dead session, a failed step. A red gate routes to repair_task, and the streak stop ends the run whatever fail says.

map 
[[patterns.run_roster.steps]]
name = "run_tasks"
type = "for"
list = { directory = "{{roster}}" }
body = "map_task"
fail = "continue"

{{task.prompt}} is the task file's body and {{task.gate}} its front-matter gate; the loader rejects the pair unless judging_gate matches the task_gate command below it.

map 
[[patterns.map_task.steps]]
name = "build_task"
title = "Implementing"
type = "agent"
prompt = "{{task.prompt}}"
judging_gate = "{{task.gate}}"
confine = true
on_plan_change = "review_plan_change"

[[patterns.map_task.steps]]
name = "task_gate"
title = "Testing"
type = "gate"
command = "{{task.gate}}"

[[patterns.map_task.steps]]
if = { task_gate = "red" }
then = "repair_task"
else = "record_done"

Exactly one repair attempt: a second red is the task's verdict, not another try.

map 
[[patterns.repair_task.steps]]
name = "repair"
title = "Repair Map Task"
type = "agent"
stage = "fix"
prompt = "{{task.prompt}}"
judging_gate = "{{task.gate}}"
confine = true
on_plan_change = "review_plan_change"

[patterns.repair_task.steps.text]
POSITION_CLAUSE = """
A previous agent attempted this task and left the tree red against the task's own gate. Repair its
work rather than starting over, and verify the repair before you finish.
"""

[[patterns.repair_task.steps]]
name = "repaired_gate"
title = "Testing"
type = "gate"
command = "{{task.gate}}"

[[patterns.repair_task.steps]]
if = { repaired_gate = "red" }
then = "record_failed"
else = "record_done"

[[patterns.record_done.steps]]
name = "record_done"
title = "Record Passed Map Task"
type = "command"
run = 'mkdir -p "$orchestration/run/verdicts"; : > "$orchestration/run/verdicts/$task_name.done"'
outputs = [
  { name = "task_done", path = "run/verdicts/{{task.name}}.done", scope = "run" },
]

[[patterns.record_failed.steps]]
name = "record_failed"
title = "Record Failed Map Task"
type = "command"
run = 'mkdir -p "$orchestration/run/verdicts"; : > "$orchestration/run/verdicts/$task_name.failed"'
outputs = [
  { name = "task_failed", path = "run/verdicts/{{task.name}}.failed", scope = "run" },
]

Two .failed among the last two verdict files stop the run; verdict files sort in roster order, so that is two consecutive tasks.

map 
[[patterns.record_failed.steps]]
name = "check_streak"
title = "Check Failed Task Streak"
type = "command"
run = '''
failed=$(ls "$orchestration/run/verdicts" | sort | tail -n 2 | grep -c '\.failed$')
if test "$failed" -ge 2
then printf stop > "$orchestration/state/streak.txt"
else printf continue > "$orchestration/state/streak.txt"
fi
'''
outputs = [
  { name = "streak", path = "state/streak.txt", values = ["continue", "stop"] },
]

[[patterns.record_failed.steps]]
if = "streak"
then = { continue = "nothing", stop = "stop_streak" }
else = "stop_streak_check_absent"

The endings

Falling off the end of whichever roster for ran is the successful ending and declares no step; everything else is a routed stop carrying one note.

map 
[[patterns.stop_roster_check_absent.steps]]
type = "stop"
note = "The roster check did not write state/roster-check.txt, so the map cannot tell whether the roster is usable."

[[patterns.stop_rewritten_roster_check_absent.steps]]
type = "stop"
note = "The rewritten roster check did not write state/rewritten-roster-check.txt, so the map cannot tell whether the roster is usable."

[[patterns.stop_streak.steps]]
type = "stop"
note = "The map stopped after a streak of failed tasks; task verdict files are under run/verdicts."

[[patterns.stop_streak_check_absent.steps]]
type = "stop"
note = "The failed-task streak check did not write state/streak.txt, so the map cannot tell whether to continue."

Named by the header as on_stop: one last troubleshooter whose whole deliverable is the handover document, then the stop.

map 
[[patterns.map_write_handover.steps]]
name = "final_map_handover"
title = "Write Map Handover"
type = "agent"
stage = "troubleshoot"
prompt = "troubleshoot"
protected = [".gantry/no-protected-check"]
outputs = [
  { name = "map_handover_document", path = "state/map-handover.md" },
]

[patterns.map_write_handover.steps.text]
POSITION_CLAUSE = """
This map run is ending when this session finishes and no further repair will be attempted. The whole
deliverable is the handover document. Gantry stopped for this reason: {{STOP_REASON}}
"""

[[patterns.map_write_handover.steps]]
type = "stop"
note = "The map ended on an engine-forced stop; the handover document is at state/map-handover.md."