@clawplays/ospec-cli 1.1.0 → 1.2.0

package/SKILL.md

@@ -176,12 +176,15 @@ Treat these as the source of truth for active delivery work:
 - `changes/active/<change>/artifacts/agents/document-review-dispatches/`
 - `changes/active/<change>/artifacts/agents/workspace-status.md`
 - `changes/active/<change>/artifacts/agents/worktree-plan.md`
+- `changes/active/<change>/artifacts/agents/workflow-route.json`
+- `changes/active/<change>/artifacts/agents/workflow-route.md`
 - `changes/active/<change>/artifacts/agents/finish-plan.md`
 - `changes/active/<change>/artifacts/agents/launch-plan.md`
 - `changes/active/<change>/artifacts/agents/worker-runs/`
 - `changes/active/<change>/artifacts/agents/review-runs/`
 - `changes/active/<change>/artifacts/agents/retries/`
 - `changes/active/<change>/artifacts/agents/blockers/`
+- `changes/active/<change>/artifacts/agents/decisions/`
 - `changes/active/<change>/artifacts/agents/review-feedback-plan.md`
 - `changes/active/<change>/tasks.md`
 - `changes/active/<change>/artifacts/reviews/design-review.md`
@@ -208,27 +211,29 @@ Before advancing an active change:
 - keep `changes/active/<change>/artifacts/agents/task-graph.json` aligned with `implementation-plan.md` and `tasks.md`
 - do not archive while `artifacts/agents/task-graph.json` has unresolved task statuses, invalid dependencies, missing target files, or missing verification commands
 - use `ospec execute bootstrap [changes/active/<change>]` when starting or resuming a single active change to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md`; it summarizes current stage, project session brief snapshot, and next safe action, including `ospec execute launch ... --task ...` when an active dispatch is waiting, without launching workers, syncing worker status, running tests, inspecting git, or editing source files
-- use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules, but does not launch workers, sync worker status, run tests, inspect git, or edit source files
+- use `ospec execute route [changes/active/<change>]` when the next recommended OSpec command needs to be persisted for human or AI handoff; it writes `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` without editing source files
+- use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules, but does not launch workers, sync worker status, run tests, inspect git, or edit source files
 - use `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` before deriving or dispatching implementation tasks to create document reviewer packets with the project session brief snapshot under `artifacts/agents/document-review-dispatches/`; design review must be approved before implementation plan review, and the command does not launch reviewers, run shell commands, sync worker status, or edit source files
+- use `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]` when direction, architecture, API, UI, risk, or scope needs explicit user choice; present the decision report `Chat Prompt` or `artifacts/agents/decisions/index.md` when asking the user, then record the answer with `ospec execute decision [changes/active/<change>] --id <id> --select <option-id>`; required pending decisions block dispatch until selected or skipped
 - use `ospec execute workspace [changes/active/<change>]` before worker handoff to record git workspace safety; if status is `needs_isolation`, defer parallel dispatch until the workspace is clean or moved into an isolated git worktree
 - use `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` to write an isolated worktree preparation plan without running git
 - use `ospec execute worktree [changes/active/<change>] --create [--branch name] [--path path] [--base ref]` only when explicitly asked to run `git worktree add`; it records stdout/stderr/status under `artifacts/agents/worktree-runs/`
 - use `ospec execute worktree [changes/active/<change>] --cleanup [--path path]` only when explicitly asked to run `git worktree remove`; it does not delete branches, push, merge, archive, run tests, or edit project source files
 - use `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` to write an artifact-only closeout readiness plan before finalize, archive, push, PR, merge, or worktree cleanup; review blockers and commands manually
-- use `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` to create a parallel-safe worker packet batch and `artifacts/agents/execution-session.json`; each packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; use `--task` for one explicit task, use `--limit` to cap dispatch batch size, and use `ospec execute complete <task-id> ...` to record worker results; a terminal worker result opens task-level review gates, so run `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work
-- use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` after dispatch to write `artifacts/agents/launch-plan.json` and `artifacts/agents/launch-plan.md`; this is the native agent launch artifact and tells the controlling AI how to use the current harness native agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). It requires an active dispatch and ready workspace status, and does not start workers, run shell commands, or edit source files by itself
-- default to current-harness native subagents for multi-worker execution: create parallel-safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, then dispatch one native agent per safe packet in the current AI session; only use `ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N]` as the final CLI fallback when the current AI harness cannot dispatch native subagents. The fallback reads or creates parallel-safe dispatches, renders the explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, and collects results into the task graph unless `--no-collect` is passed
-- use `--run --command` with `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] --run --command "..." [--timeout-ms N]` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; it captures stdout, stderr, exit code, timeout metadata, and run metadata under `artifacts/agents/worker-runs/`, then `ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]` records the task result
+- use `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` to create a parallel-safe worker packet batch and `artifacts/agents/execution-session.json`; each packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; required pending user decisions block dispatch; use `--task` for one explicit task, use `--limit` to cap dispatch batch size, and use `ospec execute complete <task-id> ...` to record worker results; a terminal worker result opens task-level review gates, so run `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work
+- use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` after dispatch to write `artifacts/agents/launch-plan.json` and `artifacts/agents/launch-plan.md`; this is the native agent launch artifact and tells the controlling AI how to use the current harness native agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, `@mention` for OpenCode, Cursor Agent/task chat, and Copilot CLI/coding-agent task). Use `--json` when an adapter needs the machine-readable launch artifact on stdout. It requires an active dispatch and ready workspace status, and does not start workers, run shell commands, or edit source files by itself
+- default to current-harness native subagents for multi-worker execution: create parallel-safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, then dispatch one native agent per safe packet in the current AI session; only use `ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N]` as the final CLI fallback when the current AI harness cannot dispatch native subagents. The fallback reads or creates parallel-safe dispatches, renders the explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, collects results into the task graph unless `--no-collect` is passed, and reports failed-worker retry commands
+- use `--run --command` with `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] --run --command "..." [--timeout-ms N]` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; it captures stdout, stderr, exit code, timeout metadata, and run metadata under `artifacts/agents/worker-runs/`, then `ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]` records the task result
 - use `ospec execute retry [changes/active/<change>] --task task-id [--run run-id] [--force]` after a blocked, needs-context, or failed run has been corrected; it writes `artifacts/agents/retries/`, reopens the task, and creates a fresh dispatch packet. Completed tasks require explicit `--force`
 - keep `dispatch`, `launch`, `orchestrate`, `collect`, `retry`, and `complete` artifact-controlled: native subagent dispatch is performed by the current AI harness, while shell commands run only for explicit fallback `launch --run --command` or `orchestrate` with a command template; none of these commands edits project source files directly; when `complete` or `collect` records `NEEDS_CONTEXT` or `BLOCKED`, OSpec writes blocker escalation under `artifacts/agents/blockers/`
 - complete `changes/active/<change>/artifacts/reviews/spec-compliance.md` before `changes/active/<change>/artifacts/reviews/code-quality.md`
 - use `ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality]` to create durable task-level or final reviewer handoff packets with the project session brief snapshot; with `--task`, review one completed task and write `artifacts/reviews/tasks/<task-id>/...`; without `--task`, run the final whole-change review after the task graph is completed; do not dispatch quality review before the matching spec review is approved
 - use `ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality] --run --command "..."` only when explicitly asked to run a local reviewer command; it captures review stdout/stderr under `artifacts/agents/review-runs/` and can update the matching task-level or final review artifact when `--decision` is provided
-- use `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` after a review artifact has a non-`PENDING` decision to write `artifacts/agents/review-feedback-plan.json` and `artifacts/agents/review-feedback-plan.md`; this records how to accept, revise, clarify, or unblock review feedback and does not edit source files or launch workers
+- use `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` after a review artifact has a non-`PENDING` decision to write `artifacts/agents/review-feedback-plan.json` and `artifacts/agents/review-feedback-plan.md`; this records how to accept, revise, clarify, or unblock review feedback, creates a required user decision gate when feedback changes scope, direction, API, UI, risk, or accepted tradeoffs, and does not edit source files or launch workers
 - do not archive while any task-level review or final review decision is `PENDING`, `NEEDS_CHANGES`, or `BLOCKED`
 - update `changes/active/<change>/artifacts/agents/worker-status.md` during implementation and review
-- use `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` when debugging was part of the change to record systematic debugging evidence; this command records evidence only and does not run shell commands
-- use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` after focused test runs to record TDD cycle evidence; this command records evidence only and does not run shell commands
+- use `ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` when debugging was part of the change to record systematic debugging evidence; this command records evidence only and does not run shell commands
+- use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` after focused test runs to record TDD cycle evidence; this command records evidence only and does not run shell commands; red must not pass, green requires a prior red FAILED record, refactor requires prior passing green/refactor evidence, and SKIPPED requires a concrete summary
 - use `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` after running fresh project checks to record verification evidence; this command records evidence only and does not run shell commands
 - use `ospec execute sync [changes/active/<change>]` after manual task graph, execution-session, review artifact, or verification checklist edits to rebuild worker status
 - do not claim completion while worker status is `PENDING`, `NEEDS_CONTEXT`, or `BLOCKED`; `controller_status` must be `DONE` before archive
@@ -263,25 +268,28 @@ ospec run resume [path]
 ospec run stop [path]
 ospec execute status [changes/active/<change>]
 ospec execute bootstrap [changes/active/<change>]
-ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]
+ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]
 ospec execute doc-review [changes/active/<change>] [--stage design|plan]
 ospec execute next [changes/active/<change>]
+ospec execute route [changes/active/<change>]
 ospec execute workspace [changes/active/<change>]
 ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]
 ospec execute worktree [changes/active/<change>] --create [--branch name] [--path path] [--base ref]
 ospec execute worktree [changes/active/<change>] --cleanup [--path path]
 ospec execute finish [changes/active/<change>] [--target main] [--remote origin]
 ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]
-ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]
-ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N] # fallback only
-ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] --run --command "..." [--timeout-ms N] # fallback only
+ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]
+ospec execute orchestrate [changes/active/<change>] --command "..." [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--limit N] [--max-rounds N] [--timeout-ms N] # fallback only
+ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] --run --command "..." [--timeout-ms N] # fallback only
 ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id] [--status DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED] [--summary "..."]
 ospec execute retry [changes/active/<change>] --task task-id [--run run-id] [--summary "..."] [--force]
 ospec execute complete <task-id> [changes/active/<change>] --status DONE --summary "..."
 ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality]
 ospec execute review [changes/active/<change>] [--task task-id] [--stage spec|quality] --run --command "..." [--timeout-ms N] [--decision APPROVED|APPROVED_WITH_CONCERNS|NEEDS_CHANGES|BLOCKED|PENDING] [--summary "..."]
 ospec execute feedback [changes/active/<change>] [--stage spec|quality] [--summary "..."]
-ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED --command "npm test -- focused" --summary "..."
+ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required|--optional]
+ospec execute decision [changes/active/<change>] --id <id> --select <option-id> [--summary "..."]
+ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED --command "npm test -- focused" --summary "..."
 ospec execute tdd [changes/active/<change>] --phase red --command "npm test -- focused" --status FAILED --exit-code 1 --summary "..."
 ospec execute tdd [changes/active/<change>] --phase green --command "npm test -- focused" --status PASSED --exit-code 0 --summary "..."
 ospec execute verify [changes/active/<change>] --command "npm test" --status PASSED --exit-code 0 --summary "..."

package/assets/for-ai/ar/ai-guide.md

@@ -30,21 +30,23 @@ tags: [ai, guide, ospec]
 - تعامل مع خطوات built-in quality policy المفعّلة مثل `tdd_cycle` و`root_cause_debug` و`verification_evidence` كـ `optional_steps` خاضعة لـ archive gate؛ غطّها في `tasks.md` و`verification.md` وملفات evidence المطابقة قبل closeout
 - عند تنفيذ change بمساعدة AI، لا تطلب من المستخدم كتابة `design.md` أو `implementation-plan.md` يدوياً؛ أنشئهما أو حدّثهما من المتطلب و`proposal.md` وسياق المشروع قبل اشتقاق `artifacts/agents/task-graph.json` أو تعديل `tasks.md` أو الكود
 - لا تطرح أكثر من سؤال تصميم موجز واحد إلا عندما يغيّر القرار الناقص البنية أو API أو البيانات أو UI أو المخاطر فعلياً؛ وإلا فسجل الافتراضات في `design.md`
+- عندما يجب أن ينتظر change اختيار المستخدم، سجّل durable decision gate عبر `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]`، واعرض `Chat Prompt` من decision report أو `artifacts/agents/decisions/index.md`، ثم سجّل الإجابة عبر `ospec execute decision [changes/active/<change>] --id <id> --select <option-id>`
 - يجب أن يُشتق `implementation-plan.md` من `design.md`، وأن يُشتق `artifacts/agents/task-graph.json` من `implementation-plan.md`، وأن تُشتق `tasks.md` من task graph، وتُوائم المهام الموجودة بعد تحديث الوثائق السابقة
 - عند بدء أو استئناف active change واحد، استخدم `ospec execute bootstrap [changes/active/<change>]` لكتابة `artifacts/agents/bootstrap.json` و`artifacts/agents/bootstrap.md` مع project session brief snapshot، ثم اتبع الإجراء الآمن التالي المسجل فيه؛ عند وجود active dispatch، يوصي bootstrap بأمر `ospec execute launch ... --task ...` المطابق
-- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
+- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
 - قبل اشتقاق implementation tasks أو dispatch لها، استخدم `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` لإنشاء document reviewer packets تتضمن project session brief snapshot تحت `artifacts/agents/document-review-dispatches/` وتجهيز `artifacts/reviews/design-review.md` أو `artifacts/reviews/implementation-plan-review.md`؛ يجب اعتماد design review قبل dispatch لمراجعة implementation plan
 - عندما تحتاج إلى عرض controller للمهام ready وblocked وrunning وcompleted والمرشحات التالية الآمنة، استخدم `ospec execute status [changes/active/<change>]` أو `ospec execute next [changes/active/<change>]`
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
 - قبل handoff إلى worker استخدم `ospec execute workspace [changes/active/<change>]` لتسجيل سلامة git workspace؛ إذا كانت الحالة `needs_isolation`، نظّف workspace أو انقل العمل إلى git worktree معزول قبل parallel dispatch
 - قبل إنشاء git worktree معزول، استخدم `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` لكتابة `artifacts/agents/worktree-plan.json` و`artifacts/agents/worktree-plan.md`؛ هذا الأمر يسجل خطة تحضير فقط ولا يشغّل `git worktree add`
 - قبل الإغلاق النهائي، استخدم `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` لكتابة `artifacts/agents/finish-plan.json` و`artifacts/agents/finish-plan.md`؛ هذا الأمر يسجل الجاهزية ونص الأوامر فقط ولا يشغل finalize أو archive أو push أو merge أو حذف worktree
 - عندما تحتاج إلى handoff artifacts دائمة على مستوى task، استخدم `ospec execute dispatch` لإنشاء batch آمن للتوازي من worker packets و`ospec execute complete` لتسجيل نتائج worker؛ يتضمن كل dispatch packet project session brief snapshot وworker profile يوضح capability tier وrecommended target وtarget tool mapping وrationale وrequired behavior؛ عندما تكون النتيجة `NEEDS_CONTEXT` أو `BLOCKED` يكتب `complete` ملفات `artifacts/agents/blockers/`؛ استخدم `--task` لمهمة واحدة صريحة و`--limit` لتحديد حجم dispatch batch؛ بعد اكتمال كل worker task استخدم `ospec execute review [changes/active/<change>] --task <task-id> --stage spec` ثم `--stage quality` لإجراء task-level review، وتبقى المهام التابعة محجوبة حتى اعتماد المراجعتين؛ وبعد اعتماد كل task-level reviews واكتمال task graph استخدم `ospec execute review` من دون `--task` لإنشاء final spec أو quality reviewer handoff packets؛ وبعد decision غير `PENDING` استخدم `ospec execute feedback` لكتابة `artifacts/agents/review-feedback-plan.md`؛ وبعد تعديل execution أو review artifacts يدويا استخدم `ospec execute sync` لإعادة بناء `worker-status.md`
-- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
+- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`، وCursor يستخدم Agent/task chat، وCopilot يستخدم CLI/coding-agent task. استخدم `--json` عندما يحتاج adapter إلى machine-readable launch artifact على stdout. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
 - default multi-worker execution هو current-harness native subagents: أنشئ safe packets عبر `ospec execute dispatch`، اقرأ `launch-plan.md`، ثم dispatch native worker agent لكل packet آمن، وسجل النتيجة عبر `ospec execute complete`
-- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/`
+- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/` ويعرض failed-worker retry commands
 - استخدم `--run --command` مع `ospec execute launch ... --run --command "..."` فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ ثم استخدم `ospec execute collect ...` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم `ospec execute retry` لإعادة dispatch
 - لا يشغّل OSpec local reviewer command إلا عند استخدام `ospec execute review ... --run --command "..."` صراحة؛ يسجل ذلك `artifacts/agents/review-runs/` ويمكنه كتابة review decision عند تمرير `--decision`
-- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` لتسجيل root-cause وfix evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
+- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` لتسجيل root-cause وfix evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
 - بعد تشغيل focused tests، استخدم `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` لتسجيل TDD cycle evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
 - بعد تشغيل project checks حديثة، استخدم `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` لتسجيل verification evidence؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell
 - `ospec execute doc-review` يسجل artifacts فقط ولا يشغّل reviewers ولا أوامر shell ولا يزامن worker status ولا يعدّل source files

package/assets/for-ai/ar/execution-protocol.md

@@ -14,13 +14,13 @@ tags: [ai, protocol, ospec]
 4. `docs/project/naming-conventions.md`
 5. `docs/project/skill-conventions.md`
 6. `docs/project/workflow-conventions.md`
-7. ملفات change الحالية: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
+7. ملفات change الحالية: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/decisions/ / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
 8. إذا وُجد `stitch_design_review` فاقرأ `artifacts/stitch/approval.json`
 9. إذا كنت تحتاج إلى تعديل إعدادات Stitch أو Checkpoint المتعلقة بـ provider أو MCP أو المصادقة أو التثبيت أو التفعيل، فاقرأ أولاً مواصفة الإضافة المحلية المطابقة للغة الوثائق المعتمدة للمشروع، ولا تنتقل إلى لغة أخرى إلا إذا كان الملف المطابق غير موجود
 
 ## القواعد الإلزامية
 
-- حافظ على `proposal.md` و`design.md` و`implementation-plan.md` و`artifacts/agents/task-graph.json` و`artifacts/agents/bootstrap.md` و`artifacts/agents/handoff.md` و`artifacts/agents/document-review-dispatches/` و`artifacts/agents/workspace-status.md` و`artifacts/agents/worktree-plan.md` و`artifacts/agents/finish-plan.md` و`artifacts/agents/launch-plan.md` و`artifacts/agents/worker-runs/` و`artifacts/agents/review-runs/` و`artifacts/agents/retries/` و`artifacts/agents/blockers/` و`artifacts/agents/review-feedback-plan.md` و`tasks.md` و`artifacts/reviews/design-review.md` و`artifacts/reviews/implementation-plan-review.md` و`artifacts/reviews/spec-compliance.md` و`artifacts/reviews/code-quality.md` و`artifacts/agents/worker-status.md` و`artifacts/agents/debug-evidence.json` و`artifacts/agents/tdd-evidence.json` و`artifacts/agents/verification-evidence.json` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- حافظ على `proposal.md` و`design.md` و`implementation-plan.md` و`artifacts/agents/task-graph.json` و`artifacts/agents/bootstrap.md` و`artifacts/agents/handoff.md` و`artifacts/agents/document-review-dispatches/` و`artifacts/agents/workspace-status.md` و`artifacts/agents/worktree-plan.md` و`artifacts/agents/finish-plan.md` و`artifacts/agents/launch-plan.md` و`artifacts/agents/worker-runs/` و`artifacts/agents/review-runs/` و`artifacts/agents/retries/` و`artifacts/agents/blockers/` و`artifacts/agents/decisions/` و`artifacts/agents/review-feedback-plan.md` و`tasks.md` و`artifacts/reviews/design-review.md` و`artifacts/reviews/implementation-plan-review.md` و`artifacts/reviews/spec-compliance.md` و`artifacts/reviews/code-quality.md` و`artifacts/agents/worker-status.md` و`artifacts/agents/debug-evidence.json` و`artifacts/agents/tdd-evidence.json` و`artifacts/agents/verification-evidence.json` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
 - لا تعِد كتابة وثائق change إلى الإنجليزية فقط لأن واجهة المنتج أو locale الموقع أو نص المتطلب يميل إلى الإنجليزية
 - إذا كانت وثائق change الحالية بالصينية بالفعل، فاستمر بالصينية ما لم تتطلب قواعد المشروع التحويل إلى الإنجليزية صراحةً
 - لا تتجاوز proposal/design/implementation-plan/task-graph/tasks/review-artifacts/worker-status وتدّعي الاكتمال مباشرة
@@ -28,25 +28,28 @@ tags: [ai, protocol, ospec]
 - تعامل مع خطوات built-in quality policy المفعّلة مثل `tdd_cycle` و`root_cause_debug` و`verification_evidence` كـ `optional_steps` خاضعة لـ archive gate؛ غطّها في `tasks.md` و`verification.md` وملفات evidence المطابقة قبل closeout
 - أثناء تنفيذ change بمساعدة AI، أنشئ `design.md` أو حدّثه بعد `proposal.md` وقبل تعديل `implementation-plan.md` أو `tasks.md` أو الكود
 - لا تطرح إلا سؤال تصميم موجزاً واحداً عندما يغيّر القرار الناقص فعلياً البنية أو API أو البيانات أو UI أو المخاطر؛ وإلا فسجل الافتراضات في `design.md`
+- عندما يجب أن ينتظر change اختيار المستخدم، سجّل durable decision gate عبر `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]`، واعرض `Chat Prompt` من decision report أو `artifacts/agents/decisions/index.md`، ثم سجّل الإجابة عبر `ospec execute decision [changes/active/<change>] --id <id> --select <option-id>`
 - أنشئ `implementation-plan.md` أو حدّثه من `design.md`، مع الملفات المستهدفة والنتائج المتوقعة وأوامر التحقق والاعتماديات والعمل القابل للتوازي والتعارضات
 - اشتق `artifacts/agents/task-graph.json` من `implementation-plan.md`؛ ويجب أن تتضمن كل مهمة id والحالة والاعتماديات وسلامة التوازي والتعارضات والملفات المستهدفة وأوامر التحقق والنتيجة المتوقعة ودور worker
 - عند بدء أو استئناف active change واحد، استخدم `ospec execute bootstrap [changes/active/<change>]` لكتابة `artifacts/agents/bootstrap.json` و`artifacts/agents/bootstrap.md` مع project session brief snapshot، ثم اتبع الإجراء الآمن التالي المسجل فيه
-- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
+- عند نقل change بين agents أو tools أو worktrees أو shells أو operators بشريين، استخدم `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` لكتابة `artifacts/agents/handoff.json` و`artifacts/agents/handoff.md`؛ يسجل هذا الأمر project session brief snapshot وtool mapping وقواعد السلامة فقط ولا يشغّل workers أو يعدّل source files
 - قبل اشتقاق implementation tasks أو dispatch لها، استخدم `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` لإنشاء document reviewer packets تتضمن project session brief snapshot تحت `artifacts/agents/document-review-dispatches/` وتجهيز `artifacts/reviews/design-review.md` أو `artifacts/reviews/implementation-plan-review.md`؛ يجب اعتماد design review قبل dispatch لمراجعة implementation plan. هذا الأمر يسجل artifacts فقط ولا يشغّل reviewers ولا أوامر shell ولا يزامن worker status ولا يعدّل source files
 - قبل توزيع عمل المهام، استخدم `ospec execute status [changes/active/<change>]` أو `ospec execute next [changes/active/<change>]` لفحص حالة controller والمهام التالية الآمنة
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
+- عندما تحتاج direction أو architecture أو API أو UI أو risk أو scope إلى اختيار صريح من المستخدم، استخدم `ospec execute decision [changes/active/<change>] ...`؛ تظهر required pending decisions في bootstrap/status/finish وفي `artifacts/agents/decisions/index.md` وتحجب dispatch حتى يتم اختيارها أو تخطيها
 - قبل handoff إلى worker استخدم `ospec execute workspace [changes/active/<change>]` لكتابة `artifacts/agents/workspace-status.json` و`artifacts/agents/workspace-status.md`؛ إذا كانت الحالة `needs_isolation`، نظّف workspace أو انقل العمل إلى git worktree معزول قبل parallel dispatch
 - قبل إنشاء git worktree معزول، استخدم `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` لكتابة `artifacts/agents/worktree-plan.json` و`artifacts/agents/worktree-plan.md`؛ هذا الأمر يسجل خطة تحضير فقط ولا يشغّل `git worktree add`
 - قبل الإغلاق النهائي، استخدم `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` لكتابة `artifacts/agents/finish-plan.json` و`artifacts/agents/finish-plan.md`؛ هذا الأمر يسجل الجاهزية ونص الأوامر فقط ولا يشغل finalize أو archive أو push أو merge أو حذف worktree
 - استخدم `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` لإنشاء batch آمن للتوازي من worker packets و`artifacts/agents/execution-session.json`؛ يتضمن كل packet project session brief snapshot وworker profile يوضح capability tier وrecommended target وtarget tool mapping وrationale وrequired behavior. استخدم `ospec execute complete <task-id> ...` لتسجيل نتائج worker. استخدم `--task` لمهمة واحدة صريحة و`--limit` لتحديد حجم dispatch batch. تزامن هذه الأوامر أيضا `artifacts/agents/worker-status.md`، وتحدّث OSpec artifacts فقط ولا تشغّل workers خارجيين؛ عندما تكون النتيجة `NEEDS_CONTEXT` أو `BLOCKED` يكتب `complete` ملفات blocker escalation تحت `artifacts/agents/blockers/`
-- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
+- بعد dispatch، استخدم `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` لكتابة native agent launch plan؛ يوجه controlling AI إلى آلية agent الأصلية في harness الحالي: Codex/GPT يستخدم `spawn_agent`/`wait_agent`/`close_agent`، وClaude Code يستخدم Task، وGemini يستخدم `@generalist`، وOpenCode يستخدم `@mention`، وCursor يستخدم Agent/task chat، وCopilot يستخدم CLI/coding-agent task. استخدم `--json` عندما يحتاج adapter إلى machine-readable launch artifact على stdout. هذا الأمر لا يشغّل workers ولا أوامر shell بنفسه
 - default multi-worker execution هو current-harness native subagents: أنشئ safe packets عبر `ospec execute dispatch`، اقرأ `launch-plan.md`، ثم dispatch native worker agent لكل packet آمن، وسجل النتيجة عبر `ospec execute complete`
-- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/`
+- استخدم `ospec execute orchestrate [changes/active/<change>] --command "..."` فقط كـ final CLI fallback عندما لا يدعم harness الحالي native subagents؛ fallback mode يرندر explicit command template ويشغّل worker commands بالتوازي ويسجل `artifacts/agents/orchestration-runs/` ويجمع النتائج ويعرض failed-worker retry commands
 - استخدم `--run --command` مع `ospec execute launch ... --run --command "..."` فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ ثم استخدم `ospec execute collect ...` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم `ospec execute retry` لإعادة dispatch
 - بعد اكتمال كل worker task، استخدم `ospec execute review [changes/active/<change>] --task <task-id> --stage spec` ثم `--stage quality` لإنشاء task-level reviewer handoff packets. تحفظ قرارات task-level داخل `artifacts/reviews/tasks/<task-id>/` وتبقى المهام التابعة محجوبة حتى اعتماد المراجعتين
 - بعد اعتماد كل task-level reviews واكتمال task graph، استخدم `ospec execute review [changes/active/<change>] [--stage spec|quality]` من دون `--task` لإنشاء final whole-change reviewer handoff packets داخل `artifacts/agents/review-dispatches/`؛ لا توزّع final quality review قبل اعتماد final spec review
 - لا يشغّل OSpec local reviewer command إلا عند استخدام `ospec execute review ... --run --command "..."` صراحة؛ يسجل ذلك `artifacts/agents/review-runs/` ويمكنه كتابة review decision عند تمرير `--decision`
-- بعد أن يحتوي review artifact على قرار غير `PENDING`، استخدم `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` لكتابة `artifacts/agents/review-feedback-plan.json` و`artifacts/agents/review-feedback-plan.md`؛ حدد accept أو revise أو clarify أو blocked قبل dispatch عمل إضافي
-- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` لتسجيل `artifacts/agents/debug-evidence.json`؛ تعني `CONFIRMED` عزل root cause، وتعني `FIXED` إصلاحا متحققا، وتؤدي `BLOCKED` إلى فشل verify
+- بعد أن يحتوي review artifact على قرار غير `PENDING`، استخدم `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` لكتابة `artifacts/agents/review-feedback-plan.json` و`artifacts/agents/review-feedback-plan.md`؛ حدد accept أو revise أو clarify أو blocked قبل dispatch عمل إضافي، وأنشئ required user decision عندما يغير feedback scope أو direction أو API أو UI أو risk أو accepted tradeoffs، وأنشئ required user decision gate عندما يغير feedback scope أو direction أو API أو UI أو risk أو accepted tradeoffs
+- عندما يكون debugging جزءا من change، استخدم `ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` لتسجيل `artifacts/agents/debug-evidence.json`؛ تعني `CONFIRMED` عزل root cause، وتعني `FIXED` إصلاحا متحققا، وتؤدي `BLOCKED` إلى فشل verify
 - بعد تشغيل focused tests، استخدم `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` لتسجيل `artifacts/agents/tdd-evidence.json`؛ عادة يسجل red الاختبار المتوقع فشله، بينما يجب أن تسجل green/refactor نتيجة ناجحة
 - بعد تشغيل project verification commands حديثة، استخدم `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` لتسجيل `artifacts/agents/verification-evidence.json`؛ لا تدّعِ الاكتمال بمجرد ملخص داخل المحادثة
 - بعد تعديل task graph أو execution session أو review artifacts أو debug evidence أو verification checklist يدويا، استخدم `ospec execute sync [changes/active/<change>]` لإعادة بناء `artifacts/agents/worker-status.md`

package/assets/for-ai/en-US/ai-guide.md

@@ -22,30 +22,33 @@ This document is the project-adopted AI guide copied from the OSpec mother spec.
 
 ## Required Behavior
 
-- Follow the project-adopted document language for `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `artifacts/agents/bootstrap.md`, `artifacts/agents/handoff.md`, `artifacts/agents/document-review-dispatches/`, `artifacts/agents/workspace-status.md`, `artifacts/agents/worktree-plan.md`, `artifacts/agents/finish-plan.md`, `artifacts/agents/launch-plan.md`, `artifacts/agents/worker-runs/`, `artifacts/agents/review-runs/`, `artifacts/agents/retries/`, `artifacts/agents/blockers/`, `artifacts/agents/review-feedback-plan.md`, `tasks.md`, `artifacts/reviews/design-review.md`, `artifacts/reviews/implementation-plan-review.md`, `artifacts/reviews/spec-compliance.md`, `artifacts/reviews/code-quality.md`, `artifacts/agents/worker-status.md`, `artifacts/agents/debug-evidence.json`, `artifacts/agents/tdd-evidence.json`, `artifacts/agents/verification-evidence.json`, `verification.md`, and `review.md`
+- Follow the project-adopted document language for `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `artifacts/agents/bootstrap.md`, `artifacts/agents/handoff.md`, `artifacts/agents/document-review-dispatches/`, `artifacts/agents/workspace-status.md`, `artifacts/agents/worktree-plan.md`, `artifacts/agents/finish-plan.md`, `artifacts/agents/launch-plan.md`, `artifacts/agents/worker-runs/`, `artifacts/agents/review-runs/`, `artifacts/agents/retries/`, `artifacts/agents/blockers/`, `artifacts/agents/decisions/`, `artifacts/agents/review-feedback-plan.md`, `tasks.md`, `artifacts/reviews/design-review.md`, `artifacts/reviews/implementation-plan-review.md`, `artifacts/reviews/spec-compliance.md`, `artifacts/reviews/code-quality.md`, `artifacts/agents/worker-status.md`, `artifacts/agents/debug-evidence.json`, `artifacts/agents/tdd-evidence.json`, `artifacts/agents/verification-evidence.json`, `verification.md`, and `review.md`
 - Do not infer change-document language from product copy, default site locale, or an "English-first" business requirement alone
 - If the project-adopted protocol is Chinese or the current change docs are already Chinese, keep the change docs in Chinese unless the project rules explicitly switch them to English
 - Use the index to locate knowledge before reading target files
-- When entering an existing OSpec project, run `ospec session [path]` to write `.ospec/session-brief.json` and `.ospec/session-brief.md` with active change, queued change, queue-run, cache fingerprint, and safe next command context; this project entry brief does not replace active-change `ospec execute bootstrap`. Use `ospec session hook [path]` only to write optional harness startup hook artifacts
+- When entering an existing OSpec project, run `ospec session [path]` to write `.ospec/session-brief.json` and `.ospec/session-brief.md` with active change, queued change, queue-run, cache fingerprint, and safe next command context; this project entry brief does not replace active-change `ospec execute bootstrap`. Use `ospec session hook [path]` only to write optional harness startup hook artifacts, including `.ospec/hooks/using-ospec.md` for session-start injection, harness target metadata, active-change bootstrap guidance, and decision/plugin gate sources
 - Use `ospec brainstorm [path] --topic "..."` only for optional pre-change exploration artifacts; use `ospec plan [path] --change changes/active/<change>` only for optional plan drafts, and pass `--apply` only when updating `implementation-plan.md` deliberately
 - Treat activated built-in quality policy steps such as `tdd_cycle`, `root_cause_debug`, and `verification_evidence` as archive-gated `optional_steps`; cover them in `tasks.md`, `verification.md`, and matching evidence artifacts before closeout
 - In AI-assisted change execution, do not ask the user to hand-write `design.md` or `implementation-plan.md`; draft or update them from the requirement, `proposal.md`, and project context before deriving `artifacts/agents/task-graph.json`, editing `tasks.md`, or editing code
-- Ask at most one concise design question only when the missing decision materially changes architecture, API, data, UI, or risk; otherwise write assumptions into `design.md`
+- Ask at most one concise design question only when the missing decision materially changes direction, architecture, API, data, UI, risk, or scope; otherwise write assumptions into `design.md`
+- When the change must pause for a user choice, record a durable gate with `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]`, present the decision report `Chat Prompt` or `artifacts/agents/decisions/index.md`, then record the selected option with `ospec execute decision [changes/active/<change>] --id <id> --select <option-id>`
 - Keep `implementation-plan.md` derived from `design.md`, keep `artifacts/agents/task-graph.json` derived from `implementation-plan.md`, keep `tasks.md` derived from the task graph, and reconcile existing tasks after upstream docs are updated
 - When starting or resuming one active change, use `ospec execute bootstrap [changes/active/<change>]` to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md` with the project session brief snapshot, then follow its next safe action; when an active dispatch is waiting, bootstrap recommends the matching `ospec execute launch ... --task ...` command
-- Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files
+- Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files
 - Before deriving or dispatching implementation tasks, use `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` to create document reviewer packets with the project session brief snapshot under `artifacts/agents/document-review-dispatches/` plus `artifacts/reviews/design-review.md` or `artifacts/reviews/implementation-plan-review.md`; design review must be approved before implementation plan review
 - Use `ospec execute status [changes/active/<change>]` or `ospec execute next [changes/active/<change>]` when you need a controller view of ready, blocked, running, completed, and safe next task candidates
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
+- Use `ospec execute decision [changes/active/<change>] ...` when direction, architecture, API, UI, risk, or scope needs explicit user choice; required pending decisions appear in bootstrap/status/finish, are summarized in `artifacts/agents/decisions/index.md`, and block dispatch until selected or skipped
 - Before worker handoff, use `ospec execute workspace [changes/active/<change>]` to record git workspace safety; if status is `needs_isolation`, clean the workspace or move work into an isolated git worktree before parallel dispatch
 - Before creating an isolated worktree, use `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` to write `artifacts/agents/worktree-plan.json` and `artifacts/agents/worktree-plan.md`; plan mode does not run git. Use explicit `--create` to run `git worktree add`, and explicit `--cleanup` to run `git worktree remove`; both record `artifacts/agents/worktree-runs/`
 - Before final closeout, use `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` to write `artifacts/agents/finish-plan.json` and `artifacts/agents/finish-plan.md`; this command records readiness and command text only and does not finalize, archive, push, merge, or remove worktrees
-- Use `ospec execute dispatch` to create a parallel-safe batch of worker packets and `ospec execute complete` to record worker results when task-level execution needs durable handoff artifacts; each dispatch packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; `complete` writes `artifacts/agents/blockers/` when the result is `NEEDS_CONTEXT` or `BLOCKED`; use `--task` for one explicit task and `--limit` to cap dispatch batch size; after each `DONE` or `DONE_WITH_CONCERNS` worker result, run task-level review with `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work; after all task-level reviews complete, use `ospec execute review` without `--task` for final whole-change spec or quality reviewer packets; use `ospec execute feedback` after non-`PENDING` final review decisions to write `artifacts/agents/review-feedback-plan.md`; use `ospec execute sync` to rebuild `worker-status.md` after manual execution or review artifact edits
-- Use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` after dispatch to write the native agent launch plan; it tells the controlling AI how to use the current harness agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). It does not start workers or edit source files by itself
+- Use `ospec execute dispatch` to create a parallel-safe batch of worker packets and `ospec execute complete` to record worker results when task-level execution needs durable handoff artifacts; each dispatch packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior; required pending user decisions block dispatch; `complete` writes `artifacts/agents/blockers/` when the result is `NEEDS_CONTEXT` or `BLOCKED`; use `--task` for one explicit task and `--limit` to cap dispatch batch size; after each `DONE` or `DONE_WITH_CONCERNS` worker result, run task-level review with `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`, then `--stage quality`, before dispatching dependent work; after all task-level reviews complete, use `ospec execute review` without `--task` for final whole-change spec or quality reviewer packets; use `ospec execute feedback` after non-`PENDING` final review decisions to write `artifacts/agents/review-feedback-plan.md`; use `ospec execute sync` to rebuild `worker-status.md` after manual execution or review artifact edits
+- Use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` after dispatch to write the native agent launch plan; it tells the controlling AI how to use the current harness agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). Use `--json` when an adapter needs the machine-readable launch artifact on stdout. It does not start workers or edit source files by itself
 - Default to current-harness native subagents for multi-worker execution: create safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, dispatch one native worker agent per safe packet, and record each result with `ospec execute complete`
-- Use `ospec execute orchestrate [changes/active/<change>] --command "..."` only as the final CLI fallback when native subagents are unavailable; fallback mode renders an explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, and collects results unless `--no-collect` is passed
+- Use `ospec execute orchestrate [changes/active/<change>] --command "..."` only as the final CLI fallback when native subagents are unavailable; fallback mode renders an explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, collects results unless `--no-collect` is passed, and reports failed-worker retry commands
 - Use explicit `--run --command` on `ospec execute launch ... --run --command "..."` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; runs capture `artifacts/agents/worker-runs/`. Then use `ospec execute collect ...` to record the fallback task result. Use `ospec execute retry` to reopen corrected blocked, needs-context, or failed work with `artifacts/agents/retries/`; completed tasks require explicit `--force`
 - Use explicit `ospec execute review ... --run --command "..."` only when OSpec should run a local reviewer command; it captures `artifacts/agents/review-runs/` and can write the task-level or final review decision when `--decision` is provided
-- When debugging is part of the change, use `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` to record root-cause and fix evidence; it records evidence only and does not run shell commands
+- When debugging is part of the change, use `ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` to record root-cause and fix evidence; it records evidence only and does not run shell commands
 - After focused test runs, use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` to record TDD cycle evidence; it records evidence only and does not run shell commands
 - After running fresh project checks, use `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` to record verification evidence; it records evidence only and does not run shell commands
 - `ospec execute doc-review` records artifacts only and does not launch reviewers, run shell commands, sync worker status, or edit source files; native subagent dispatch is done by the current AI harness, while shell commands run only for explicit worktree create/cleanup, fallback `launch --run --command`, `review --run --command`, or fallback `orchestrate` with an explicit command template

package/assets/for-ai/en-US/execution-protocol.md

@@ -14,42 +14,45 @@ tags: [ai, protocol, ospec]
 4. `docs/project/naming-conventions.md`
 5. `docs/project/skill-conventions.md`
 6. `docs/project/workflow-conventions.md`
-7. The current change files: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
+7. The current change files: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/decisions/ / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
 8. If `stitch_design_review` exists, read `artifacts/stitch/approval.json`
 9. If Stitch or Checkpoint provider, MCP, auth, install, or enable config must be changed, read the repo-local localized plugin docs under `.ospec/plugins/<plugin>/docs/` first; if they are missing, install or enable the plugin to sync its docs before changing config
 
 ## Mandatory Rules
 
-- Keep `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `artifacts/agents/bootstrap.md`, `artifacts/agents/handoff.md`, `artifacts/agents/document-review-dispatches/`, `artifacts/agents/workspace-status.md`, `artifacts/agents/worktree-plan.md`, `artifacts/agents/finish-plan.md`, `artifacts/agents/launch-plan.md`, `artifacts/agents/worker-runs/`, `artifacts/agents/review-runs/`, `artifacts/agents/retries/`, `artifacts/agents/blockers/`, `artifacts/agents/review-feedback-plan.md`, `tasks.md`, `artifacts/reviews/design-review.md`, `artifacts/reviews/implementation-plan-review.md`, `artifacts/reviews/spec-compliance.md`, `artifacts/reviews/code-quality.md`, `artifacts/agents/worker-status.md`, `artifacts/agents/debug-evidence.json`, `artifacts/agents/tdd-evidence.json`, `artifacts/agents/verification-evidence.json`, `verification.md`, and `review.md` in the project-adopted document language
+- Keep `proposal.md`, `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, `artifacts/agents/bootstrap.md`, `artifacts/agents/handoff.md`, `artifacts/agents/document-review-dispatches/`, `artifacts/agents/workspace-status.md`, `artifacts/agents/worktree-plan.md`, `artifacts/agents/finish-plan.md`, `artifacts/agents/launch-plan.md`, `artifacts/agents/worker-runs/`, `artifacts/agents/review-runs/`, `artifacts/agents/retries/`, `artifacts/agents/blockers/`, `artifacts/agents/decisions/`, `artifacts/agents/review-feedback-plan.md`, `tasks.md`, `artifacts/reviews/design-review.md`, `artifacts/reviews/implementation-plan-review.md`, `artifacts/reviews/spec-compliance.md`, `artifacts/reviews/code-quality.md`, `artifacts/agents/worker-status.md`, `artifacts/agents/debug-evidence.json`, `artifacts/agents/tdd-evidence.json`, `artifacts/agents/verification-evidence.json`, `verification.md`, and `review.md` in the project-adopted document language
 - Do not rewrite change docs into English just because the product UI, site locale, or requirement text is English-first
 - If the current change docs are already Chinese, continue in Chinese unless the project rules explicitly require an English switch
 - Do not skip proposal/design/implementation-plan/task-graph/tasks/review-artifacts/worker-status and jump straight into completion
-- When entering an existing OSpec project, use `ospec session [path]` to write `.ospec/session-brief.json` and `.ospec/session-brief.md`; it records active changes, queued changes, queue-run state, cache fingerprint, and safe next commands without launching workers, running tests, inspecting git, archiving, or editing source files. Use `ospec session hook [path]` only to write opt-in harness startup hook artifacts under `.ospec/hooks/`
+- When entering an existing OSpec project, use `ospec session [path]` to write `.ospec/session-brief.json` and `.ospec/session-brief.md`; it records active changes, queued changes, queue-run state, cache fingerprint, and safe next commands without launching workers, running tests, inspecting git, archiving, or editing source files. Use `ospec session hook [path]` only to write opt-in harness startup hook artifacts under `.ospec/hooks/`, including `using-ospec.md` with session-start injection steps, harness targets, active-change bootstrap guidance, and decision/plugin gate sources
 - Use `ospec brainstorm [path] --topic "..."` only for optional pre-change exploration artifacts under `.ospec/brainstorms/`; `--visual` adds a local static HTML companion and the command does not create a change
 - Use `ospec plan [path] --change changes/active/<change>` for optional plan drafts under `.ospec/plans/`; pass `--apply` only when deliberately updating that change's `implementation-plan.md`
 - Treat activated built-in quality policy steps such as `tdd_cycle`, `root_cause_debug`, and `verification_evidence` as archive-gated `optional_steps`; cover them in `tasks.md`, `verification.md`, and matching evidence artifacts before closeout
 - During AI-assisted change execution, draft or update `design.md` after `proposal.md` and before editing `implementation-plan.md`, `tasks.md`, or code
-- Ask one concise design question only when a missing decision would materially change architecture, API, data, UI, or risk; otherwise record assumptions in `design.md`
+- Ask one concise design question only when a missing decision would materially change direction, architecture, API, data, UI, risk, or scope; otherwise record assumptions in `design.md`
+- When the change must pause for a user choice, record a durable gate with `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]`, present the decision report `Chat Prompt` or `artifacts/agents/decisions/index.md`, then record the selected option with `ospec execute decision [changes/active/<change>] --id <id> --select <option-id>`
 - Draft or update `implementation-plan.md` from `design.md`, including target files, expected results, verification commands, dependencies, parallelizable work, and conflicts
 - Derive `artifacts/agents/task-graph.json` from `implementation-plan.md`; each task must include id, status, dependencies, parallel safety, conflicts, target files, verification commands, expected result, and worker role
 - When starting or resuming one active change, use `ospec execute bootstrap [changes/active/<change>]` to write `artifacts/agents/bootstrap.json` and `artifacts/agents/bootstrap.md` with the project session brief snapshot, then follow its next safe action
-- Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files
+- Use `ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` when moving a change between agents, tools, worktrees, shells, or human operators; it writes `artifacts/agents/handoff.json` and `artifacts/agents/handoff.md` with the project session brief snapshot, target tool mapping, and safety rules without launching workers or editing source files
 - Before deriving or dispatching implementation tasks, use `ospec execute doc-review [changes/active/<change>] [--stage design|plan]` to create document reviewer packets with the project session brief snapshot under `artifacts/agents/document-review-dispatches/` and review artifacts at `artifacts/reviews/design-review.md` or `artifacts/reviews/implementation-plan-review.md`; design review must be approved before implementation plan review. This command records artifacts only and does not launch reviewers, run shell commands, sync worker status, or edit source files
 - Use `ospec execute status [changes/active/<change>]` or `ospec execute next [changes/active/<change>]` to inspect controller state and safe next task candidates before assigning task work
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
+- Use `ospec execute decision [changes/active/<change>] ...` when direction, architecture, API, UI, risk, or scope needs explicit user choice; required pending decisions appear in bootstrap/status/finish, are summarized in `artifacts/agents/decisions/index.md`, and block dispatch until selected or skipped
 - Before worker handoff, use `ospec execute workspace [changes/active/<change>]` to write `artifacts/agents/workspace-status.json` and `artifacts/agents/workspace-status.md`; if status is `needs_isolation`, clean the workspace or move work into an isolated git worktree before parallel dispatch
 - Before creating an isolated worktree, use `ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` to write `artifacts/agents/worktree-plan.json` and `artifacts/agents/worktree-plan.md`; plan mode records a preparation plan only and does not run git. Use explicit `--create` to run `git worktree add`, and explicit `--cleanup` to run `git worktree remove`; both write `artifacts/agents/worktree-runs/`, and cleanup does not delete branches
 - Before final closeout, use `ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` to write `artifacts/agents/finish-plan.json` and `artifacts/agents/finish-plan.md`; this command records readiness and command text only and does not finalize, archive, push, merge, or remove worktrees
-- Use `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` to create a parallel-safe batch of worker packets and `artifacts/agents/execution-session.json`; each packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior. Use `ospec execute complete <task-id> ...` to record worker results. Use `--task` for one explicit task and `--limit` to cap dispatch batch size. These commands also sync `artifacts/agents/worker-status.md`, update OSpec artifacts only, and do not launch external workers; `complete` writes blocker escalation artifacts under `artifacts/agents/blockers/` when the result is `NEEDS_CONTEXT` or `BLOCKED`
-- Use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` after dispatch to write the native agent launch plan; it tells the controlling AI how to use the current harness agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, and `@mention` for OpenCode). It does not start workers or run shell commands by itself
+- Use `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` to create a parallel-safe batch of worker packets and `artifacts/agents/execution-session.json`; each packet includes the project session brief snapshot and a worker profile with capability tier, recommended target, target tool mapping, rationale, and required behavior. Use `ospec execute complete <task-id> ...` to record worker results. Use `--task` for one explicit task and `--limit` to cap dispatch batch size. These commands also sync `artifacts/agents/worker-status.md`, update OSpec artifacts only, and do not launch external workers; required pending user decisions block dispatch; `complete` writes blocker escalation artifacts under `artifacts/agents/blockers/` when the result is `NEEDS_CONTEXT` or `BLOCKED`
+- Use `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` after dispatch to write the native agent launch plan; it tells the controlling AI how to use the current harness agent mechanism (`spawn_agent`/`wait_agent`/`close_agent` for Codex/GPT, Task for Claude Code, `@generalist` for Gemini, `@mention` for OpenCode, Cursor Agent/task chat, and Copilot CLI/coding-agent task). Use `--json` when an adapter needs the machine-readable launch artifact on stdout. It does not start workers or run shell commands by itself
 - Default to current-harness native subagents for multi-worker execution: create safe packets with `ospec execute dispatch`, inspect `launch-plan.md`, dispatch one native worker agent per safe packet, and record each result with `ospec execute complete`
-- Use `ospec execute orchestrate [changes/active/<change>] --command "..."` only as the final CLI fallback when native subagents are unavailable; fallback mode renders an explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, and collects results unless `--no-collect` is passed
+- Use `ospec execute orchestrate [changes/active/<change>] --command "..."` only as the final CLI fallback when native subagents are unavailable; fallback mode renders an explicit command template, runs worker commands concurrently, records `artifacts/agents/orchestration-runs/`, captures worker runs, collects results unless `--no-collect` is passed, and reports failed-worker retry commands
 - Use explicit `--run --command` on `ospec execute launch ... --run --command "..."` only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; runs capture `artifacts/agents/worker-runs/`. Then use `ospec execute collect ...` to record the fallback task result. Use `ospec execute retry` to reopen corrected blocked, needs-context, or failed work with `artifacts/agents/retries/`; completed tasks require explicit `--force`
 - After a worker records `DONE` or `DONE_WITH_CONCERNS`, use `ospec execute review [changes/active/<change>] --task <task-id> --stage spec` and then `--stage quality` to create task-level reviewer packets; task-level decisions are stored under `artifacts/reviews/tasks/<task-id>/`, and dependent tasks stay blocked until both task reviews are approved
 - After all task-level reviews are approved and the task graph is completed, use `ospec execute review [changes/active/<change>] [--stage spec|quality]` without `--task` to create final whole-change reviewer packets with the project session brief snapshot under `artifacts/agents/review-dispatches/`; final spec review must be approved before final quality review is dispatched
 - Use explicit `ospec execute review ... --run --command "..."` only when OSpec should run a local reviewer command; it captures `artifacts/agents/review-runs/` and can write the task-level or final review decision when `--decision` is provided
-- Use `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` after a review artifact has a non-`PENDING` decision to write `artifacts/agents/review-feedback-plan.json` and `artifacts/agents/review-feedback-plan.md`; handle review feedback through accept, revise, clarify, or blocked actions before dispatching more work
-- When debugging is part of the change, use `ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` to record `artifacts/agents/debug-evidence.json`; `CONFIRMED` isolates root cause, `FIXED` verifies the fix, and `BLOCKED` fails verification
-- After focused test runs, use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` to record `artifacts/agents/tdd-evidence.json`; red normally records the expected failing test, while green/refactor should pass
+- Use `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` after a review artifact has a non-`PENDING` decision to write `artifacts/agents/review-feedback-plan.json` and `artifacts/agents/review-feedback-plan.md`; handle review feedback through accept, revise, clarify, or blocked actions before dispatching more work, and create a required user decision gate when feedback changes scope, direction, API, UI, risk, or accepted tradeoffs
+- When debugging is part of the change, use `ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` to record `artifacts/agents/debug-evidence.json`; `CONFIRMED` isolates root cause, `FIXED` verifies the fix, and `BLOCKED` fails verification
+- After focused test runs, use `ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` to record `artifacts/agents/tdd-evidence.json`; red must record a non-passing focused test before implementation, green requires a prior red `FAILED` record, refactor requires prior passing green/refactor evidence, and `SKIPPED` requires a concrete summary
 - After running fresh project verification commands, use `ospec execute verify [changes/active/<change>] --command "..." --status PASSED` to record `artifacts/agents/verification-evidence.json`; do not claim completion with only an unrecorded chat summary
 - Use `ospec execute sync [changes/active/<change>]` after manual task graph, execution-session, review artifact, debug evidence, or verification checklist edits to rebuild `artifacts/agents/worker-status.md`
 - Derive `tasks.md` from `artifacts/agents/task-graph.json`; if tasks already exist but upstream docs are still templates, update them first and then reconcile tasks

package/assets/for-ai/ja-JP/ai-guide.md

@@ -30,21 +30,23 @@ tags: [ai, guide, ospec]
 - `tdd_cycle`、`root_cause_debug`、`verification_evidence` など有効化された built-in quality policy steps は、archive-gated `optional_steps` として扱う。closeout 前に `tasks.md`、`verification.md`、対応する evidence artifacts で coverage を記録する
 - AI 支援で change を進める場合、ユーザーに `design.md` や `implementation-plan.md` の手書きを求めない。要件、`proposal.md`、プロジェクト文脈からそれらを作成または更新してから `artifacts/agents/task-graph.json` を導出し、`tasks.md` やコードを編集する
 - 不足判断がアーキテクチャ、API、データ、UI、リスクを実質的に変える場合だけ、短い設計質問を 1 つ行う。それ以外は仮定を `design.md` に記録する
+- change がユーザー選択を待つ必要がある場合は `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]` で durable decision gate を記録し、decision report の `Chat Prompt` または `artifacts/agents/decisions/index.md` を提示してから、`ospec execute decision [changes/active/<change>] --id <id> --select <option-id>` で回答を記録する
 - `implementation-plan.md` は `design.md` から導き、`artifacts/agents/task-graph.json` は `implementation-plan.md` から導き、`tasks.md` は task graph から導く。既存 tasks は上流文書の更新後に整合させる
 - one active change を開始または再開するときは、`ospec execute bootstrap [changes/active/<change>]` で project session brief snapshot を含む `artifacts/agents/bootstrap.json` と `artifacts/agents/bootstrap.md` を書き、そこにある次の安全な action に従う。active dispatch がある場合、bootstrap は対応する `ospec execute launch ... --task ...` command を推奨する
-- change を agent、tool、worktree、shell、human operator の間で引き渡すときは、`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` で `artifacts/agents/handoff.json` と `artifacts/agents/handoff.md` を書く。このコマンドは project session brief snapshot、target tool mapping、safety rules のみを記録し、worker 起動や source file 編集は行わない
+- change を agent、tool、worktree、shell、human operator の間で引き渡すときは、`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` で `artifacts/agents/handoff.json` と `artifacts/agents/handoff.md` を書く。このコマンドは project session brief snapshot、target tool mapping、safety rules のみを記録し、worker 起動や source file 編集は行わない
 - implementation tasks を導出または dispatch する前に、`ospec execute doc-review [changes/active/<change>] [--stage design|plan]` で `artifacts/agents/document-review-dispatches/` 配下に project session brief snapshot を含む document reviewer packet を作成し、`artifacts/reviews/design-review.md` または `artifacts/reviews/implementation-plan-review.md` を用意する。design review 承認後に implementation plan review を dispatch する
 - ready、blocked、running、completed と安全な次 task 候補を確認する必要がある場合は、`ospec execute status [changes/active/<change>]` または `ospec execute next [changes/active/<change>]` を使って controller view を確認する
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
 - worker handoff の前に `ospec execute workspace [changes/active/<change>]` で git workspace safety を記録する。status が `needs_isolation` の場合は、workspace を clean にするか isolated git worktree に移してから parallel dispatch する
 - isolated worktree を作成する前に、`ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` で `artifacts/agents/worktree-plan.json` と `artifacts/agents/worktree-plan.md` を記録する。このコマンドは準備計画のみを記録し、`git worktree add` は実行しない
 - final closeout の前に、`ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` で `artifacts/agents/finish-plan.json` と `artifacts/agents/finish-plan.md` を記録する。このコマンドは readiness と command text のみを記録し、finalize、archive、push、merge、worktree 削除は実行しない
 - task-level の永続 handoff artifacts が必要な場合は、`ospec execute dispatch` で parallel-safe な worker packet batch を作成し、`ospec execute complete` で worker 結果を記録する。各 dispatch packet には project session brief snapshot と、capability tier、recommended target、target tool mapping、rationale、required behavior を示す worker profile が含まれる。結果が `NEEDS_CONTEXT` または `BLOCKED` の場合、`complete` は `artifacts/agents/blockers/` を書く。`--task` は明示的な単一 task、`--limit` は dispatch batch size の上限に使う。各 worker task 完了後は `ospec execute review [changes/active/<change>] --task <task-id> --stage spec`、続けて `--stage quality` で task-level review を行い、dependent task は両方の review が承認されるまで dispatch されない。すべての task-level review が承認され task graph が完了した後は、`--task` なしの `ospec execute review` で final spec または quality reviewer handoff packet を作成する。review decision が non-`PENDING` の場合は `ospec execute feedback` で `artifacts/agents/review-feedback-plan.md` を書く。実行または review artifacts を手動編集した後は `ospec execute sync` で `worker-status.md` を再構築する
-- dispatch 後は `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` で native agent launch plan を書く。Codex/GPT は `spawn_agent`/`wait_agent`/`close_agent`、Claude Code は Task、Gemini は `@generalist`、OpenCode は `@mention` を使うよう controlling AI に指示する。この command 自体は worker 起動や shell command 実行を行わない
+- dispatch 後は `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` で native agent launch plan を書く。Codex/GPT は `spawn_agent`/`wait_agent`/`close_agent`、Claude Code は Task、Gemini は `@generalist`、OpenCode は `@mention`、Cursor は Agent/task chat、Copilot は CLI/coding-agent task を使うよう controlling AI に指示する。adapter が stdout の machine-readable launch artifact を必要とする場合は `--json` を使う。この command 自体は worker 起動や shell command 実行を行わない
 - multi-worker execution は current harness native subagents が default。`ospec execute dispatch` で safe packet を作り、`launch-plan.md` を読んで、各 safe packet に native worker agent を dispatch し、結果を `ospec execute complete` で記録する
-- `ospec execute orchestrate [changes/active/<change>] --command "..."` は native subagents が使えない場合だけの final CLI fallback。fallback mode は explicit command template で worker command を並行実行し、`artifacts/agents/orchestration-runs/` と task graph collect を記録する
+- `ospec execute orchestrate [changes/active/<change>] --command "..."` は native subagents が使えない場合だけの final CLI fallback。fallback mode は explicit command template で worker command を並行実行し、`artifacts/agents/orchestration-runs/` と task graph collect を記録し、failed-worker retry commands を報告する
 - explicit `--run --command` on `ospec execute launch ... --run --command "..."` は native subagents が使えない、または明示的に bypass する場合だけの single-worker CLI fallback。その後 `ospec execute collect ...` で fallback task result を記録する。修正済み blocked/needs-context/failed work は `ospec execute retry` で再 dispatch する
 - explicit `ospec execute review ... --run --command "..."` の場合のみ local reviewer command を実行し、`artifacts/agents/review-runs/` を記録する。`--decision` がある場合は review decision も書き戻せる
-- debugging が change の一部だった場合、`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` で root cause と fix evidence を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない
+- debugging が change の一部だった場合、`ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` で root cause と fix evidence を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない
 - focused test 実行後は、`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` で TDD cycle evidence を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない
 - fresh project checks を実行した後、`ospec execute verify [changes/active/<change>] --command "..." --status PASSED` で verification evidence を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない
 - `ospec execute doc-review` は artifacts のみを記録し、reviewer 起動、shell command 実行、worker status 同期、source file 編集は行わない

package/assets/for-ai/ja-JP/execution-protocol.md

@@ -14,13 +14,13 @@ tags: [ai, protocol, ospec]
 4. `docs/project/naming-conventions.md`
 5. `docs/project/skill-conventions.md`
 6. `docs/project/workflow-conventions.md`
-7. 現在の change ファイル: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
+7. 現在の change ファイル: `proposal.md / design.md / implementation-plan.md / artifacts/agents/task-graph.json / artifacts/agents/bootstrap.md / artifacts/agents/handoff.md / artifacts/agents/document-review-dispatches/ / artifacts/agents/launch-plan.md / artifacts/agents/decisions/ / artifacts/agents/review-feedback-plan.md / tasks.md / artifacts/reviews/design-review.md / artifacts/reviews/implementation-plan-review.md / artifacts/reviews/spec-compliance.md / artifacts/reviews/code-quality.md / artifacts/agents/worker-status.md / artifacts/agents/debug-evidence.json / state.json / verification.md`
 8. `stitch_design_review` がある場合は `artifacts/stitch/approval.json`
 9. Stitch / Checkpoint の provider、MCP、認証、インストール、または有効化設定を変更する必要がある場合は、先にプロジェクト文書言語に一致するリポジトリ内のローカライズ済みプラグイン仕様を読む。一致する言語ファイルがない場合のみ他言語版へフォールバックする
 
 ## 必須ルール
 
-- `proposal.md`、`design.md`、`implementation-plan.md`、`artifacts/agents/task-graph.json`、`artifacts/agents/bootstrap.md`、`artifacts/agents/handoff.md`、`artifacts/agents/document-review-dispatches/`、`artifacts/agents/workspace-status.md`、`artifacts/agents/worktree-plan.md`、`artifacts/agents/finish-plan.md`、`artifacts/agents/launch-plan.md`、`artifacts/agents/worker-runs/`、`artifacts/agents/review-runs/`、`artifacts/agents/retries/`、`artifacts/agents/blockers/`、`artifacts/agents/review-feedback-plan.md`、`tasks.md`、`artifacts/reviews/design-review.md`、`artifacts/reviews/implementation-plan-review.md`、`artifacts/reviews/spec-compliance.md`、`artifacts/reviews/code-quality.md`、`artifacts/agents/worker-status.md`、`artifacts/agents/debug-evidence.json`、`artifacts/agents/tdd-evidence.json`、`artifacts/agents/verification-evidence.json`、`verification.md`、`review.md` はプロジェクト採用の文書言語で維持する
+- `proposal.md`、`design.md`、`implementation-plan.md`、`artifacts/agents/task-graph.json`、`artifacts/agents/bootstrap.md`、`artifacts/agents/handoff.md`、`artifacts/agents/document-review-dispatches/`、`artifacts/agents/workspace-status.md`、`artifacts/agents/worktree-plan.md`、`artifacts/agents/finish-plan.md`、`artifacts/agents/launch-plan.md`、`artifacts/agents/worker-runs/`、`artifacts/agents/review-runs/`、`artifacts/agents/retries/`、`artifacts/agents/blockers/`、`artifacts/agents/decisions/`、`artifacts/agents/review-feedback-plan.md`、`tasks.md`、`artifacts/reviews/design-review.md`、`artifacts/reviews/implementation-plan-review.md`、`artifacts/reviews/spec-compliance.md`、`artifacts/reviews/code-quality.md`、`artifacts/agents/worker-status.md`、`artifacts/agents/debug-evidence.json`、`artifacts/agents/tdd-evidence.json`、`artifacts/agents/verification-evidence.json`、`verification.md`、`review.md` はプロジェクト採用の文書言語で維持する
 - 製品 UI やサイト locale が英語中心でも、それだけを理由に change 文書を英語へ書き換えない
 - 現在の change 文書が既に中国語なら、プロジェクトルールが明示的に英語切り替えを要求しない限り中国語のまま続ける
 - proposal/design/implementation-plan/task-graph/tasks/review-artifacts/worker-status を飛ばして完了を主張しない
@@ -28,25 +28,28 @@ tags: [ai, protocol, ospec]
 - `tdd_cycle`、`root_cause_debug`、`verification_evidence` など有効化された built-in quality policy steps は、archive-gated `optional_steps` として扱う。closeout 前に `tasks.md`、`verification.md`、対応する evidence artifacts で coverage を記録する
 - AI 支援で change を進める場合は、`proposal.md` の後、`implementation-plan.md`、`tasks.md`、コードを編集する前に `design.md` を作成または更新する
 - 不足している判断がアーキテクチャ、API、データ、UI、リスクを実質的に変える場合だけ、短い設計質問を 1 つ行う。それ以外は仮定を `design.md` に記録する
+- change がユーザー選択を待つ必要がある場合は `ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact --option id:label:impact [--recommended id] [--required]` で durable decision gate を記録し、decision report の `Chat Prompt` または `artifacts/agents/decisions/index.md` を提示してから、`ospec execute decision [changes/active/<change>] --id <id> --select <option-id>` で回答を記録する
 - `design.md` から `implementation-plan.md` を作成または更新し、対象ファイル、期待結果、検証コマンド、依存関係、並行可能な作業、競合を記録する
 - `implementation-plan.md` から `artifacts/agents/task-graph.json` を導く。各 task には id、状態、依存関係、並行安全性、競合、対象ファイル、検証コマンド、期待結果、worker role を含める
 - one active change を開始または再開するときは、`ospec execute bootstrap [changes/active/<change>]` で project session brief snapshot を含む `artifacts/agents/bootstrap.json` と `artifacts/agents/bootstrap.md` を書き、そこにある次の安全な action に従う
-- change を agent、tool、worktree、shell、human operator の間で引き渡すときは、`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]` で `artifacts/agents/handoff.json` と `artifacts/agents/handoff.md` を書く。このコマンドは project session brief snapshot、target tool mapping、safety rules のみを記録し、worker 起動や source file 編集は行わない
+- change を agent、tool、worktree、shell、human operator の間で引き渡すときは、`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic]` で `artifacts/agents/handoff.json` と `artifacts/agents/handoff.md` を書く。このコマンドは project session brief snapshot、target tool mapping、safety rules のみを記録し、worker 起動や source file 編集は行わない
 - implementation tasks を導出または dispatch する前に、`ospec execute doc-review [changes/active/<change>] [--stage design|plan]` で `artifacts/agents/document-review-dispatches/` 配下に project session brief snapshot を含む document reviewer packet を作成し、`artifacts/reviews/design-review.md` または `artifacts/reviews/implementation-plan-review.md` を用意する。design review 承認後に implementation plan review を dispatch する。このコマンドは artifacts のみを記録し、reviewer 起動、shell command 実行、worker status 同期、source file 編集は行わない
 - task 作業を割り当てる前に、`ospec execute status [changes/active/<change>]` または `ospec execute next [changes/active/<change>]` で controller 状態と安全な次の task 候補を確認する
+- Use `ospec execute route [changes/active/<change>]` to write `artifacts/agents/workflow-route.json` and `artifacts/agents/workflow-route.md` with the next recommended OSpec command; this records workflow routing artifacts only and does not edit source files.
+- direction、architecture、API、UI、risk、scope に明示的な user choice が必要な場合は `ospec execute decision [changes/active/<change>] ...` を使う。required pending decisions は bootstrap/status/finish と `artifacts/agents/decisions/index.md` に表示され、selected または skipped まで dispatch をブロックする
 - worker handoff の前に `ospec execute workspace [changes/active/<change>]` で `artifacts/agents/workspace-status.json` と `artifacts/agents/workspace-status.md` を書く。status が `needs_isolation` の場合は、workspace を clean にするか isolated git worktree に移してから parallel dispatch する
 - isolated worktree を作成する前に、`ospec execute worktree [changes/active/<change>] [--branch name] [--path path] [--base ref]` で `artifacts/agents/worktree-plan.json` と `artifacts/agents/worktree-plan.md` を記録する。このコマンドは準備計画のみを記録し、`git worktree add` は実行しない
 - final closeout の前に、`ospec execute finish [changes/active/<change>] [--target main] [--remote origin]` で `artifacts/agents/finish-plan.json` と `artifacts/agents/finish-plan.md` を記録する。このコマンドは readiness と command text のみを記録し、finalize、archive、push、merge、worktree 削除は実行しない
 - `ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]` で parallel-safe な worker packet batch と `artifacts/agents/execution-session.json` を作成する。各 packet には project session brief snapshot と、capability tier、recommended target、target tool mapping、rationale、required behavior を示す worker profile が含まれる。`ospec execute complete <task-id> ...` で worker 結果を記録する。`--task` は明示的な単一 task、`--limit` は dispatch batch size の上限に使う。これらのコマンドは `artifacts/agents/worker-status.md` も同期し、OSpec artifacts のみを更新し、外部 worker は起動しない。結果が `NEEDS_CONTEXT` または `BLOCKED` の場合、`complete` は `artifacts/agents/blockers/` に blocker escalation を書く
-- dispatch 後は `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]` で native agent launch plan を書く。Codex/GPT は `spawn_agent`/`wait_agent`/`close_agent`、Claude Code は Task、Gemini は `@generalist`、OpenCode は `@mention` を使うよう controlling AI に指示する。この command 自体は worker 起動や shell command 実行を行わない
+- dispatch 後は `ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|cursor|copilot|shell|generic] [--dry-run] [--json]` で native agent launch plan を書く。Codex/GPT は `spawn_agent`/`wait_agent`/`close_agent`、Claude Code は Task、Gemini は `@generalist`、OpenCode は `@mention`、Cursor は Agent/task chat、Copilot は CLI/coding-agent task を使うよう controlling AI に指示する。adapter が stdout の machine-readable launch artifact を必要とする場合は `--json` を使う。この command 自体は worker 起動や shell command 実行を行わない
 - multi-worker execution は current harness native subagents が default。`ospec execute dispatch` で safe packet を作り、`launch-plan.md` を読んで、各 safe packet に native worker agent を dispatch し、結果を `ospec execute complete` で記録する
-- `ospec execute orchestrate [changes/active/<change>] --command "..."` は native subagents が使えない場合だけの final CLI fallback。fallback mode は explicit command template で worker command を並行実行し、`artifacts/agents/orchestration-runs/` と task graph collect を記録する
+- `ospec execute orchestrate [changes/active/<change>] --command "..."` は native subagents が使えない場合だけの final CLI fallback。fallback mode は explicit command template で worker command を並行実行し、`artifacts/agents/orchestration-runs/` と task graph collect を記録し、failed-worker retry commands を報告する
 - explicit `--run --command` on `ospec execute launch ... --run --command "..."` は native subagents が使えない、または明示的に bypass する場合だけの single-worker CLI fallback。その後 `ospec execute collect ...` で fallback task result を記録する。修正済み blocked/needs-context/failed work は `ospec execute retry` で再 dispatch する
 - 各 worker task 完了後、`ospec execute review [changes/active/<change>] --task <task-id> --stage spec`、続けて `--stage quality` を使って task-level reviewer handoff packet を作成する。task-level decisions は `artifacts/reviews/tasks/<task-id>/` に保存され、両方が承認されるまで dependent task は dispatch されない
 - すべての task-level review が承認され task graph が完了した後、`--task` なしの `ospec execute review [changes/active/<change>] [--stage spec|quality]` で final whole-change reviewer handoff packet を `artifacts/agents/review-dispatches/` に作成する。final spec review 承認前に final quality review を割り当てない
 - explicit `ospec execute review ... --run --command "..."` の場合のみ local reviewer command を実行し、`artifacts/agents/review-runs/` を記録する。`--decision` がある場合は review decision も書き戻せる
-- review artifact が non-`PENDING` decision を持つ場合は `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` で `artifacts/agents/review-feedback-plan.json` と `artifacts/agents/review-feedback-plan.md` を書く。追加作業を dispatch する前に accept、revise、clarify、blocked の handling を明確にする
-- debugging が change の一部だった場合、`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED` で `artifacts/agents/debug-evidence.json` を記録する。`CONFIRMED` は root cause の隔離、`FIXED` は verified fix、`BLOCKED` は verify failure を意味する
+- review artifact が non-`PENDING` decision を持つ場合は `ospec execute feedback [changes/active/<change>] [--stage spec|quality]` で `artifacts/agents/review-feedback-plan.json` と `artifacts/agents/review-feedback-plan.md` を書く。追加作業を dispatch する前に accept、revise、clarify、blocked の handling を明確にし、feedback が scope、direction、API、UI、risk、accepted tradeoffs を変える場合は required user decision gate を作成する
+- debugging が change の一部だった場合、`ospec execute debug [changes/active/<change>] --phase reproduce|isolate|hypothesize|fix|verify --symptom "..." --root-cause "..." --status FIXED` で `artifacts/agents/debug-evidence.json` を記録する。`CONFIRMED` は root cause の隔離、`FIXED` は verified fix、`BLOCKED` は verify failure を意味する
 - focused test 実行後、`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..." --status ...` で `artifacts/agents/tdd-evidence.json` を記録する。red は通常、期待どおり失敗する test を記録し、green/refactor は passing result を記録する
 - fresh project verification commands を実行した後、`ospec execute verify [changes/active/<change>] --command "..." --status PASSED` で `artifacts/agents/verification-evidence.json` を記録する。chat summary だけで完了を主張しない
 - task graph、execution session、review artifacts、debug evidence、verification checklist を手動編集した後は、`ospec execute sync [changes/active/<change>]` で `artifacts/agents/worker-status.md` を再構築する