CLI Reference

The canonical entrypoint is:

recursive-closure

rclosure is an alias.

Global options come before the subcommand:

recursive-closure --workspace /repo status
recursive-closure --state-dir /repo/.recursive-closure status
recursive-closure --workspace /repo --process PRC20260615-120000-PLN000-child001 next

JSON Boundary

Commands that create semantic content or judgments require --json.

Use inline JSON:

recursive-closure init --json '{"title":"Root","task":"Task statement.","success_criteria":["criterion"]}'

Use stdin for any long, multiline, or shell-fragile payload:

recursive-closure init --json - <<'JSON'
{"title":"Root","task":"Task statement.","success_criteria":["criterion"]}
JSON

recursive-closure submit --json - <<'JSON'
{"action":"check-success","task_id":"TSK000","payload":{"status":"not_success","title":"Gap","summary":"A blocking gap remains.","result_ids":["RES000"],"blocking_gaps":["gap"],"followup":{"title":"Follow-up","task":"Close the gap.","success_criteria":["criterion"]}}}
JSON

Generated Markdown is output only. Do not edit Markdown and expect the CLI to parse it back into state.

Commands

init

Creates a schema-v11 process with root task TSK000.

recursive-closure init --json '{"title":"Root","task":"Task statement.","success_criteria":["criterion"]}'

Payload:

{
  "title": "Root",
  "task": "Task statement.",
  "success_criteria": ["criterion"]
}

Options:

--process-id PRC...
--language zh

Returns the next legal action, context ids, command hints, and worker file pointer.

recursive-closure next
recursive-closure next --json
recursive-closure next --compact

Use next --compact for low-token agent loops. It returns the frontier action, ids, worker file, and submit_action without long instructions.

Normal loop:

next --compact -> read worker -> submit JSON -> next

submit returns the next compact frontier after a successful mutation.

submit

Submits the current frontier action and lets the kernel perform legal mechanical status transitions.

recursive-closure submit --json '{"action":"create-plan","task_id":"TSK000","payload":{"title":"Plan","task_definition":"...","proposed_solution":"...","acceptance_criteria":["criterion"],"verification_plan":["check"],"risks":[],"assumptions":[]}}'

Guards:

action must match the current next_action.
Provided task_id and plan_id must match the current frontier.
Semantic content still comes from the agent.
The kernel owns normal status transitions, event writes, rendered bodies, validation, and next-action scheduling.

Supported shapes:

{"action":"create-plan","task_id":"TSK000","payload":{}}
{"action":"classify-plan","plan_id":"PLN000","payload":{}}
{"action":"execute-plan","plan_id":"PLN000","payload":{}}
{"action":"execute-plan","plan_id":"PLN000","spawn":{}}
{"action":"split-plan","plan_id":"PLN000","children":[{}]}
{"action":"parallel-split-plan","plan_id":"PLN000","children":[{}]}
{"action":"parallel-split-plan","plan_id":"PLN000","dispatches":[{"child_process_id":"PRC...","evidence":{}}]}
{"action":"parallel-split-plan","plan_id":"PLN000","join":true}
{"action":"record-result","plan_id":"PLN000","payload":{}}
{"action":"check-success","task_id":"TSK000","payload":{}}
{"action":"unblock-or-report","task_id":"TSK000","resolved":true}

The response is JSON with outputs, valid, errors, and compact next.

Status is an action-derived projection. Normal agents do not author status directly; they submit action outputs and the kernel derives legal status transitions.

The command sections below document the low-level primitives used by submit and by tests, recovery, or manual debugging. Normal agent loops should prefer submit.

create-plan

Creates and defines one plan for a task.

recursive-closure create-plan --task TSK000 --json '{"title":"Plan","task_definition":"...","proposed_solution":"...","acceptance_criteria":["criterion"],"verification_plan":["check"],"risks":[],"assumptions":[]}'

Preconditions:

task exists
task has no existing plan

Payload:

{
  "title": "Plan",
  "task_definition": "What this plan solves.",
  "proposed_solution": "Concrete path.",
  "acceptance_criteria": ["criterion"],
  "verification_plan": ["check"],
  "risks": [],
  "assumptions": []
}

classify-plan

Classifies a defined plan as one_go, split, or parallel_split.

recursive-closure classify-plan PLN000 --json '{"classification":"split","reason":"Multiple independently verifiable outcomes."}'

one_go payload:

{
  "classification": "one_go",
  "reason": "Single bounded outcome.",
  "one_go_justification": {
    "single_outcome": true,
    "low_risk": true,
    "immediate_verification": true,
    "no_hidden_dependency": true,
    "rollback_simple": true,
    "why_not_split": "Splitting would be artificial."
  }
}

parallel_split payload:

{
  "classification": "parallel_split",
  "reason": "Independent child tasks can run in parallel with callable subagents.",
  "parallel_split_justification": {
    "independent_children": true,
    "no_shared_write_conflict": true,
    "clear_merge_contract": true,
    "subagent_available": true,
    "why_parallel": "Children can be solved independently.",
    "merge_plan": "Sync child processes, then record a parent summary result."
  }
}

repair-status

Admin recovery command for manual status repair after state corruption or interrupted low-level work.

recursive-closure repair-status task TSK000 doing --reason "recover interrupted low-level command" --force
recursive-closure repair-status plan PLN000 executing --reason "recover interrupted low-level command" --force
recursive-closure repair-status plan PLN000 splitting --reason "recover interrupted low-level command" --force

Normal agents should use submit; it performs legal status transitions automatically. repair-status requires --reason and --force, and appends a status_repaired event. Task repairs are limited to doing. Plan repairs are limited to executing and splitting. Completion is produced by result and check actions.

create-task

Creates a child task from a source plan.

recursive-closure create-task --parent TSK000 --from-plan PLN000 --mode split --json '{"title":"Child","task":"Child statement.","success_criteria":["criterion"]}'
recursive-closure create-task --parent TSK000 --from-plan PLN000 --mode spawn --json '{"title":"Runtime blocker","task":"Blocking subtask.","success_criteria":["criterion"]}'

Modes:

split: from a split plan in splitting
spawn: from a one_go plan in executing

spawn-process

Creates an independent child process from a parallel_split plan.

recursive-closure spawn-process --parent TSK000 --from-plan PLN000 --json '{"title":"Parallel child","task":"Child statement.","success_criteria":["criterion"]}'

Preconditions:

source plan is classified as parallel_split
source plan is in splitting

The command prints the child process id.

record-dispatch

Records real harness/subagent dispatch evidence for a parallel child process.

recursive-closure record-dispatch --plan PLN000 --child-process PRC... --json '{"launcher":"Codex subagent launcher","assignee":"subagent/thread id","dispatch_ref":"harness dispatch id or transcript pointer","command_prefix":"recursive-closure --workspace /repo --process PRC...","notes":[]}'

Payload:

{
  "launcher": "Codex subagent launcher",
  "assignee": "subagent/thread id",
  "dispatch_ref": "harness dispatch id or transcript pointer",
  "command_prefix": "recursive-closure --workspace /repo --process PRC...",
  "notes": []
}

Guards:

dispatch_ref cannot be only the child process id.
command_prefix must include the child --process selector.
placeholders such as todo, unknown, inline, and self are rejected.

join

Syncs parallel child process status into the parent plan.

recursive-closure join --plan PLN000
recursive-closure join --plan PLN000 --json

For done children, join copies the child final result/check summary into the parent plan entry. Parent result creation is blocked until every parallel child has dispatch evidence, done status, and joined final result/check summaries.

result

Records execution result for a plan and marks the plan done.

recursive-closure result --plan PLN000 --json '{"title":"Result","summary":"What was produced.","done":["item"],"verification":["evidence"],"known_gaps":[],"artifacts":[]}'

Payload:

{
  "title": "Result",
  "summary": "What was produced.",
  "done": ["item"],
  "verification": ["evidence"],
  "known_gaps": [],
  "artifacts": []
}

Known gaps are allowed. Task-level check decides whether they are blocking.

Parent result guards:

split plans cannot record a parent result until at least one split child task exists and every child is done.
parallel_split plans cannot record a parent result until every child process has dispatch evidence, is synced as done, and has fresh joined final result/check summaries.
one_go plans with spawned runtime child tasks cannot record the parent result until those child tasks are done.

check

Writes a task-level success, not-success, or blocked check.

Required success fields:

result_ids: top-level result ids cited by the check.
evidence: evidence strings supporting the success claim.
criteria_map: one entry per original success criterion.
criteria_map[].result_ids: cited result ids for that specific criterion; each must also appear in top-level result_ids.
execution_map, stress_tests, residual_risks, and defect_hunt: explicit review coverage.

Success:

{
  "status": "success",
  "title": "Check",
  "summary": "Solved with evidence.",
  "result_ids": ["RES000"],
  "evidence": ["evidence"],
  "criteria_map": [
    {"criterion": "criterion", "evidence": ["evidence"], "result_ids": ["RES000"]}
  ],
  "execution_map": [
    {"plan_id": "PLN000", "result_id": "RES000", "verification": ["verified"]}
  ],
  "stress_tests": [
    {"failure_mode": "plausible failure", "probe": "probe", "outcome": "passes", "blocking": false}
  ],
  "residual_risks": [
    {"risk": "risk", "why_non_blocking": "bounded"}
  ],
  "defect_hunt": [
    {"concern": "possible defect", "investigation": "checked", "outcome": "not present", "blocking": false}
  ]
}

Every criteria_map[].criterion value must copy one original task success_criteria string exactly. Do not summarize, translate, or paraphrase criteria in this field.

Success payloads reject weak verification language conservatively. Use positive verified evidence instead of phrases such as probably, maybe, unknown, or not verified; if uncertainty is blocking, write not_success.

Minimal success submit:

recursive-closure submit --json - <<'JSON'
{"action":"check-success","task_id":"TSK000","payload":{"status":"success","title":"Check","summary":"Solved with evidence.","result_ids":["RES000"],"evidence":["verified result evidence"],"criteria_map":[{"criterion":"criterion","evidence":["criterion satisfied"],"result_ids":["RES000"]}],"execution_map":[{"plan_id":"PLN000","result_id":"RES000","verification":["result belongs to this plan"]}],"stress_tests":[{"failure_mode":"missing evidence","probe":"checked cited result","outcome":"evidence present","blocking":false}],"residual_risks":[{"risk":"future scope change","why_non_blocking":"outside stated criteria"}],"defect_hunt":[{"concern":"uncited claim","investigation":"checked all success claims","outcome":"all claims cite results","blocking":false}]}}
JSON

Not success:

{
  "status": "not_success",
  "title": "Gap",
  "summary": "A blocking gap remains.",
  "result_ids": ["RES000"],
  "blocking_gaps": ["gap"],
  "followup": {
    "title": "Follow-up",
    "task": "Close the gap.",
    "success_criteria": ["criterion"]
  }
}

validate

Validates process structure, paths, links, status transitions, result/check references, dispatch evidence, and joined child summaries.

recursive-closure validate
recursive-closure validate --json

render

Regenerates human-readable views.

recursive-closure render

status

Prints current process summary.

recursive-closure status
recursive-closure status --json

ps

Lists process sessions under the selected state root.

recursive-closure ps
recursive-closure ps --json

attach

Changes the workspace active process pointer.

recursive-closure attach PRC...

Do not use attach inside parallel child-process subagents.

batch-next

Lists runnable frontier tasks.

recursive-closure batch-next
recursive-closure batch-next --json

archive and delete

recursive-closure archive PRC...
recursive-closure delete PRC... --force

undo and purge-events

These are operational cleanup commands for event history.

recursive-closure undo
recursive-closure purge-events --keep 100

undo only trims the event log. It does not revert process.json, rendered bodies, or derived status. Use it as a recovery tool and expect to inspect or repair state afterward.

dashboard

Runs the local dashboard server.

recursive-closure --workspace . dashboard

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

JSON Boundary

Commands

init

next

submit

create-plan

classify-plan

repair-status

create-task

spawn-process

record-dispatch

join

result

check

validate

render

status

ps

attach

batch-next

archive and delete

undo and purge-events

dashboard

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

JSON Boundary

Commands

init

next

submit

create-plan

classify-plan

repair-status

create-task

spawn-process

record-dispatch

join

result

check

validate

render

status

ps

attach

batch-next

archive and delete

undo and purge-events

dashboard