sweep

<objective>

Non-interactive end-to-end research pipeline: auto-plan → judge gate → run. Single command from goal to result. Accepts goal string, passes all run/colab/team flags.

NOT for: interactive planning (use /research:plan); methodology review only (use /research:judge); running already-approved plan (use /research:run).

</objective>

<workflow>

Agent Resolution

<!-- Agent resolution: see _RESEARCH_SHARED/agent-resolution.md -->

_RESEARCH_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/research}/bin/resolve_shared.py" 2>/dev/null)  # timeout: 5000

Read $_RESEARCH_SHARED/agent-resolution.md. Contains: foundry check + fallback table. If foundry not installed: use table to substitute each foundry:X with general-purpose.

Sweep delegates to plan (S2), judge (S3), run (S5) — see each skill's Agent Resolution for fallback handling.

Steps S1–S5

Triggered by sweep "goal" [--flags]. Non-interactive end-to-end: auto-plan → judge gate → run.

Shared path resolution (always runs before S1):

_RESEARCH_SHARED already resolved above (Agent Resolution block); reuse it here. Additionally resolve _RESEARCH_SKILLS:

_RESEARCH_SKILLS=$(ls -td ~/.claude/plugins/cache/borda-ai-rig/research/*/skills 2>/dev/null | head -1)
[ -z "$_RESEARCH_SKILLS" ] && _RESEARCH_SKILLS="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/research/skills"

Task tracking: create tasks for S1–S5 at start.

Step S1: Parse arguments

Existing program.md guard — sweep creates a new program.md; if one already exists at the output path (default: program.md at project root, or --out <path> if provided), stop immediately:

! sweep: program.md already exists — sweep cannot overwrite existing program.
  Use /research:run <program.md> to execute the existing program, or delete program.md to restart sweep.

Check AFTER extracting --out flag so the correct output path is known before checking.

Extract <goal> — first positional argument (quoted or unquoted string describing optimization target).

Extract flags:

• --colab[=HW] — passed to plan (Config.compute) and run; if =HW present, extract colab_hw
• --compute=local|colab|docker — passed through
• --team — passed through to run
• --codex — passed through to run
• --researcher — passed through to run; combine with --architect for dual-agent SOTA + architectural hypothesis pipeline
• --architect — passed through to run; enables architectural hypothesis pass via foundry:solution-architect
• --journal — passed through to run when present; preserves per-iteration journal entries (requires --researcher or --architect — enforced by run R2)
• --hypothesis <path> — passed through to run when present; preloads hypothesis queue from the given file
• --skip-validation — passed to judge step (S3)
• --out <path> — optional: write program.md here instead of project root. .md output target is determined solely by --out (or the default project-root program.md) — never infer the output path by scanning <goal> text for .md substrings; the goal string is prose describing the optimization target, not a path argument.

--out validation: if --out <path> provided, validate path BEFORE any extraction or file write:

# POSIX-compatible path-traversal check (avoids bash-specific [[ ]])
case "$OUT" in
  *..*)
    if [ -n "$OUT" ]; then
      echo "sweep: invalid --out path (path traversal not allowed): $OUT" >&2
      exit 2
    fi
    ;;
esac

# Verify resolved path stays within project root (defense in depth; macOS-compatible)
if [ -n "$OUT" ]; then
    _PROJ_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
    if ! python "${CLAUDE_PLUGIN_ROOT:-plugins/research}/bin/check_output_within_root.py" "$OUT" "$_PROJ_ROOT" 2>/dev/null; then  # timeout: 5000
        echo "sweep: --out path escapes project root: $OUT" >&2
        exit 2
    fi
fi

Unsupported flag check — after extracting supported flags, scan $ARGUMENTS for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>\. Supported: \--team\, \--compute\, \--colab\, \--codex\, \--researcher\, \--architect\, \--journal\, \--hypothesis\, \--skip-validation\, \--out\. then invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

If <goal> missing or empty, stop:

⚠ sweep requires a goal prompt.
Usage: /research:sweep "goal description" [--flags]

If extracted <goal> starts with --, treat as flag misparse — stop with ! Misparse: goal starts with '--'. Did you forget to quote the goal or omit it? Usage: /research:sweep "goal description" [--flags]

Step S2: Non-interactive plan

First, Read $_RESEARCH_SKILLS/plan/SKILL.md to load the plan mode step definitions, then execute steps P-P1, P-P2, P-P2b and P-P3 from $_RESEARCH_SKILLS/plan/SKILL.md ($_RESEARCH_SKILLS resolved above S1) (P-P0 skipped — <goal> always text string) with overrides:

Include P-P2b analysis in S2 synthesis — P-P2b findings are scoped hypotheses that need consolidation into the program.md written by P-P3; skipping P-P2b drops hypothesis context from the generated program.

Mandatory P-P1 codebase scan — sweep MUST execute P-P1 to derive metric_cmd and guard_cmd from the codebase. Skipping P-P1 produces a program.md with placeholder commands that fail at run-time. If P-P1 cannot complete (no detectable test runner, no benchmark scripts, no metric command candidates): mark the program as INCOMPLETE, do NOT proceed to S3 — print ! sweep: P-P1 codebase scan could not derive metric_cmd/guard_cmd from <project-root>. Program marked INCOMPLETE — manual configuration required. Run /research:plan "<goal>" interactively to configure. and stop.

• P-P2 (config presentation): Accept all auto-detected defaults without prompting. Print proposed config as informational block prefixed sweep: auto-config → — do NOT wait for confirmation.
• If --colab[=HW] or --compute=colab passed, write compute: colab (and colab_hw: <HW> if provided) into Config block.
• scope_files: derive from goal string — extract domain-relevant file patterns (e.g. goal mentioning "neural network" → ["*.py", "models/**", "train*.py"]; goal mentioning "config" or "YAML" → [".yaml", ".yml", "*.json"]). Default ["**/*.py"] only when goal provides no domain signals. Multiple keyword matches: merge (union) all matched patterns. Always include the derived scope_files in the sweep: auto-config → printout so users can verify before run — users cannot correct silently wrong scope without seeing it.
• agent_strategy: set to a value accepted by judge C9 (auto / perf / code / ml / arch). Map flags to a valid strategy: --researcher or --team or --architect → "arch" (multi-agent research/architect work is closest to the arch ideation track); no flags → "auto". Never write "dual-agent: ...", "team", "researcher", or "default" — those values fail C9. Record the flag combination separately in ## Notes (e.g. dispatch: dual-agent (researcher + architect)) so the orchestration intent is preserved without polluting the validated agent_strategy field.
• P-P3 (write program.md): Write to <--out path> if provided; else program.md at project root.
• If output path exists: enforce the P-P3 AskUserQuestion overwrite gate — sweep does NOT bypass it. The gate's pipeline-mode exemption applies to non-interactive CI pipelines, not user-initiated sweeps. Invoke AskUserQuestion: (a) Overwrite — proceed; (b) Abort — stop. On Abort: print follow-up hint and stop.

Print on completion:

sweep: plan → <output path> ✓

Step S3: Judge + refinement loop

$_RESEARCH_SKILLS resolved in S2 — in scope throughout S3–S5.

Initialize REFINE_ITER = 0, MAX_REFINE = 3.

Repe