singularity-forge/docs/plans/todo-triage-2026-05-11-plan.md

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.