Proposal: Support human-only tasks in tasks.md (AI skips work it can't do) #1362

The ask

From a community question: a change's tasks.md often mixes work the AI can do with work only a developer can do — creating third-party accounts, pasting secrets, hardware/physical steps, anything requiring spend or credentials. Today there's no way to tell OpenSpec "this line isn't for the AI." Original proposal was to tag lines:

- [ ] [DEV] Create a Twilio account, obtain a live API SID/token
- [ ] [DEV] Add TWILIO_AUTH_TOKEN to the local encrypted .env
- [ ] [AI]  Add twilioToken + is2FAEnabled fields to prisma.schema

…with the tooling recognizing [DEV] and skipping execution.

What happens today

tasks.md is a flat checklist and nothing understands task ownership — the tooling only ever reads the checkbox state:

So the tag works fine as a human convention today (write it, tell your agent to skip [DEV] lines), but nothing enforces or reports on it.

Why plain [DEV]/[AI] gating is the wrong layer

• Completion semantics have no clean answer. A checkbox has two states. A human task needs a third — "done by a person, not the AI." If a [DEV] task counts toward completion and stays unchecked, archive nags forever; if it doesn't count, nothing tracks that the human did it.
• Real cost is threading, not parsing. A blessed vocabulary has to run through progress-counting, the apply/verify/archive workflow templates, and all_done logic — and those templates are pinned by golden-hash parity tests.
• It's the thin end of an assignment system ([QA], [REVIEW], assignees…), which is a much bigger product direction.

Better directions to discuss

1. Prerequisites, not tasks. "Create a Twilio account" is an environmental precondition, not an implementation step. Move that work out of the checklist into a plain-bullet section — the progress counter already ignores non-checkbox bullets, so the agent reads it as context but completion math stays clean. No third state, no template/counter changes.

   ## Manual prerequisites
   - Create a Twilio account, obtain a live API SID/token
   - Add TWILIO_AUTH_TOKEN to .env
   Tasks
   
   [ ] Add twilioToken + is2FAEnabled fields to prisma.schema
   
   

2. Recognition, not annotation. The AI already knows it can't create an account or paste a secret. One paragraph in the apply guardrail — "if a task needs human-only action (accounts, secrets, credentials, spend, hardware), don't attempt it; surface it as a handoff and continue" — solves it with zero labeling discipline from the user.

3. Solve it at authoring time. Teach the propose/plan step to route non-automatable work into a prerequisites section from the start. Then apply/verify/archive need no changes at all — the mixed list never gets created.

Suggested resolution

Lean toward (1) + (3): document a ## Manual prerequisites convention, taught at authoring time, working with the fact that the counter already ignores plain bullets — optionally add (2)'s guardrail paragraph as a safety net. This gives the original ask everything except machine-readable per-actor reporting ("2 human tasks left"), which nobody's currently requesting.

Open questions:

• Do people need per-actor reporting/counting, or just "AI doesn't attempt it + doesn't nag"? (Changes whether a real vocabulary is justified.)
• How common is genuine interleaving (AI → human secret → AI), where a flat prerequisites section loses ordering?