# TODO Inbox Triage Plan — 2026-05-11

## Summary

Root `TODO.md` contained seven untriaged implementation notes related to headless
machine-surface reliability and planning ergonomics. All have been promoted into
durable roadmap items and cross-referenced with `BUILD_PLAN.md`. Future agents
should use this plan and the referenced docs instead of treating the old raw dump
as instruction.

## Existing Durable Homes

These raw notes did **not** have a suitable existing durable home. None were
represented in `BUILD_PLAN.md`, `docs/specs/`, or milestone planning state.

## Newly Promoted Roadmap Items

| Item | Why | Suggested tier | Implementation note |
|---|---|---|---|
| **Headless `new-milestone` broken in unattended mode** | `sf headless new-milestone --context-text "…"` stalls when the agent calls `ask_user_questions` because the tool returns "unavailable" in non-interactive contexts. No milestone is created. Blocks batch backlog ingestion. | **Tier 1** | Two viable paths: (a) prompt-level — instruct the agent that `--context`/`--context-text` is the complete spec and to proceed without follow-up; (b) tool-level — in headless mode without `--supervised`, route `ask_user_questions` through the probe-resolution flow. Either works; both ideal. |
| **Question resolution via adversarial-collaborative probes** | Replace blocking `ask_user_questions` in headless/autonomous mode with parallel combatant + partner probes. Combatant challenges the assumption; partner researches the codebase for the likely answer. Converge → proceed; diverge → conservative minimal scope + flag in `OPEN-QUESTIONS.md`. Only ask human if interactive mode is available and stakes are high. Makes `headless new-milestone --context …` finish unattended. | **Tier 1** | Builds on the fix above but generalises to any headless/autonomous question. Needs a short budget (30 s / 2 tool calls per probe). Requires `OPEN-QUESTIONS.md` append path. |
| **Auto-triage TODO.md on each autonomous cycle** | `commands-todo.js` already implements `triageTodoDump`. Today it's manual only (`/todo triage`). Wire it to the autonomous orchestrator so each cycle starts by checking if `TODO.md` has content beyond the empty template, and if so runs `triageTodoDump` before picking the next unit. Skip when `TODO.md` == `_EMPTY_TODO` template. | **Tier 2** | One LLM call per cycle when content exists (Minimax M2.7 etc per `PREFERRED_TRIAGE_MODEL_PATTERNS`). Cheap relative to a cycle. Need a hook in the autonomous loop entrypoint before unit dispatch. |
| **Bulk roadmap import** | `sf headless import-roadmap --file BACKLOG.md` — read flat markdown with H2 sections and bullet items, emit one milestone per H2, slices per `⬜` item, no LLM. Pure text → SF-structure transform. | **Tier 2** | Needs a deterministic parser for the markdown schema (H2 = milestone, paragraph = context, `⬜` bullet = slice, optional H3 = phase boundary). Useful for ingesting human roadmaps without 16 LLM round-trips. |
| **`sf plan list` TTY-free variant** | `sf plan list` fails with "Interactive mode requires a terminal" in non-TTY. The actual operation (list files in `.sf/milestones/`) needs no interaction. Add `--plain` or `sf headless plan list` that emits one `milestone-id title` per line. | **Tier 2** | Very small surface change. The plan list logic should check `isTTY` or accept an explicit `--plain` flag; headless variant is a thin adapter. |
| **Hand-authorable milestone scaffold** | Today a milestone is a directory tree with `CONTEXT.md`, `MILESTONE-SUMMARY.md`, `ROADMAP.md`, `SUMMARY.md`, plus `slices/SNN/` and `tasks/TNN/`. Naming uses an ID + 6-char hash that's not documented. Support a "minimum milestone" — just `CONTEXT.md` with frontmatter `id: MNNN\ntitle: …` — that SF accepts and auto-fills the rest from on first operation. | **Tier 2** | Lets humans (or other tools) hand-author milestones when SF's LLM scaffold is unavailable or overkill. Need to document the minimum schema and add an auto-scaffold path in milestone load. |
| **Discoverable `--answers` schema** | `sf headless` has `--answers <path>` for pre-supplying interactive answers, but the answer schema for each command isn't discoverable. Add `--print-answer-schema` to headless commands that emit the JSON schema of every question the command *might* ask. | **Tier 3** | Complements probe-resolution flow — if probes converge, use that; if they diverge but caller pre-supplied via `--answers`, use that instead of falling back to `OPEN-QUESTIONS.md`. |

## Grouping Note

Items 1–2 (headless unattended question handling) and items 3–7 (headless/planning
surface ergonomics) are related but separable. The unattended-mode fixes should
land first because they unblock the autonomous loop for milestone creation.
Bulk import, plain plan list, hand-authorable scaffolds, and answer-schema
discovery can ship independently in any order.

## Acceptance Criteria

- `TODO.md` contains no untriaged raw notes.
- New work starts from this plan or `BUILD_PLAN.md`, not from deleted raw dump text.
- Items that need implementation are converted into SF milestone/slice/task state
  before code changes begin.
