@clawplays/ospec-cli 1.0.2 → 1.1.0

package/dist/services/templates/ProjectTemplateBuilder.js

@@ -1356,40 +1356,156 @@ ${this.formatReferenceList(refs, 'قيد التحديد')}
 1. 优先读取 \`SKILL.index.json\`。
 2. 修改代码前先读取相关 \`SKILL.md\`。
 3. 当前执行工作以 \`changes/active/<change>\` 为准。
-4. 如果项目启用了 Stitch 且当前 change 激活了 \`stitch_design_review\`，先检查 \`artifacts/stitch/approval.json\`，未 \`approved\` 前不要把 change 视为可继续实现或可归档。
-5. 如果涉及 Stitch 安装、provider 切换、doctor 修复、MCP 或认证配置，优先读取仓库内 Stitch 规范；若缺失规范文档，则使用内建基线：Gemini 用 \`%USERPROFILE%/.gemini/settings.json\` 的 \`mcpServers.stitch.httpUrl\` 与 \`headers.X-Goog-Api-Key\`，Codex 用 \`%USERPROFILE%/.codex/config.toml\` 的 \`[mcp_servers.stitch]\`、\`type = "http"\`、\`url = "https://stitch.googleapis.com/mcp"\` 与 \`X-Goog-Api-Key\`。
-6. 如果内建 Codex provider 只读调用正常但 Stitch 写操作卡住，优先检查是否真正走了 \`codex exec --dangerously-bypass-approvals-and-sandbox\`；如果项目覆写了自定义 Codex runner，则该 runner 也必须显式带上这个参数。
-7. 发生重要变更后同步更新技能文档并重建索引。`, `# AI Guide
+4. AI 辅助执行 change 时，先基于需求、\`proposal.md\` 和项目上下文起草或更新 \`design.md\`，再编辑 \`implementation-plan.md\`、推导 \`artifacts/agents/task-graph.json\`、编辑 \`tasks.md\` 或代码。
+5. 只有缺失决策会实质影响架构、API、数据、UI 或风险时，才提出一个简短设计问题；否则把假设写入 \`design.md\`。
+6. \`implementation-plan.md\` 必须从 \`design.md\` 推导，并明确目标文件、预期结果、验证命令、依赖、可并行任务和冲突；\`artifacts/agents/task-graph.json\` 必须从 \`implementation-plan.md\` 推导；\`tasks.md\` 必须从 task graph 推导。
+6. 进入已有 OSpec 项目时，用 \`ospec session [path]\` 写入 \`.ospec/session-brief.json\` 和 \`.ospec/session-brief.md\`，记录 active change、queued change、queue-run、cache fingerprint 和安全下一步命令；这是项目入口简报，不替代 active change 的 \`ospec execute bootstrap\`。
+6. 将已激活的内建质量策略步骤（如 \`tdd_cycle\`、\`root_cause_debug\`、\`verification_evidence\`）视为受归档门禁约束的 \`optional_steps\`；收尾前必须在任务文档、验证文档和对应 evidence artifacts 中覆盖。
+6. 常用 agent artifacts 包括 \`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\`、\`artifacts/agents/worker-status.md\`、\`artifacts/agents/debug-evidence.json\`、\`artifacts/agents/tdd-evidence.json\` 和 \`artifacts/agents/verification-evidence.json\`。
+7. 开始或恢复单个 active change 时，用 \`ospec execute bootstrap [changes/active/<change>]\` 写入带 project session brief snapshot 的 \`artifacts/agents/bootstrap.json\` 和 \`artifacts/agents/bootstrap.md\`，然后按其中的下一步安全动作继续；已有 active dispatch 时，bootstrap 会推荐对应的 \`ospec execute launch ... --task ...\` 命令。
+8. change 需要在 agent、工具、worktree、shell 或人工操作者之间交接时，用 \`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、目标工具映射和安全规则，不会启动 worker 或编辑源码。
+8. 推导或派发实现任务前，用 \`ospec execute doc-review [changes/active/<change>] [--stage design|plan]\` 生成带 project session brief snapshot 的 \`artifacts/agents/document-review-dispatches/\` 交接包，并创建 \`artifacts/reviews/design-review.md\` 或 \`artifacts/reviews/implementation-plan-review.md\`；design review 通过后才能派发 implementation plan review。
+8. 派发 worker 前，用 \`ospec execute workspace [changes/active/<change>]\` 写入 \`artifacts/agents/workspace-status.json\` 和 \`artifacts/agents/workspace-status.md\`；如果状态为 \`needs_isolation\`，先清理当前工作区或转入隔离 git worktree，再进行并行派发。
+9. 创建隔离 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\`。
+10. 最终收尾前，用 \`ospec execute finish [changes/active/<change>] [--target main] [--remote origin]\` 写入 \`artifacts/agents/finish-plan.json\` 和 \`artifacts/agents/finish-plan.md\`；该命令只记录 readiness 和命令文本，不会 finalize、archive、push、merge 或删除 worktree。
+9. 需要 task 级持久交接时，用 \`ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]\` 生成并行安全的 worker 任务包批次和 \`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\` 限制派发批次大小；当 complete 记录 \`NEEDS_CONTEXT\` 或 \`BLOCKED\` 时，会生成 \`artifacts/agents/blockers/\`。
+9. dispatch 后用 \`ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]\` 写入 native agent 启动计划；它要求存在一个 active dispatch 且 workspace 状态为 ready，并说明当前控制 AI 如何使用 harness 原生 agent 机制：Codex/GPT 用 \`spawn_agent\`、\`wait_agent\`、\`close_agent\`，Claude Code 用 Task，Gemini 用 \`@generalist\`，OpenCode 用 \`@mention\`。
+9. 默认多 worker 执行路径是当前 harness 原生 subagent：先 dispatch 并行安全 packet，查看 \`launch-plan.md\`，再为每个安全 packet 启动一个 native agent，并用 \`ospec execute complete\` 记录结果。
+9. 只有当前 AI harness 不支持原生 subagent 时，才用 \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` 作为最后 CLI fallback；fallback 会渲染显式 command template、并发运行 worker command、记录 \`artifacts/agents/orchestration-runs/\`，并把结果 collect 回 task graph。
+9. 只有原生 subagent 不可用或被明确绕过时，才用 \`--run --command\`（即 \`ospec execute launch ... --run --command "..."\`）作为单 worker CLI fallback，并写入 \`artifacts/agents/worker-runs/\`；随后用 \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` 记录 fallback 任务结果。修复 blocked、needs-context 或 failed work 后，用 \`ospec execute retry\` 重新派发；已完成任务必须显式 \`--force\` 才能 retry。
+10. 每个 worker task 完成后，用 \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`，再用 \`--stage quality\` 生成 task 级 reviewer 交接包；task 级 review 决策写入 \`artifacts/reviews/tasks/<task-id>/\`，依赖任务会等这两个 review 通过后才可派发。
+10. 所有 task 级 review 通过且 task graph 完成后，用不带 \`--task\` 的 \`ospec execute review [changes/active/<change>] [--stage spec|quality]\` 在 \`artifacts/agents/review-dispatches/\` 下生成最终 whole-change reviewer 交接包；最终 \`artifacts/reviews/spec-compliance.md\` 通过前不得派发最终 \`artifacts/reviews/code-quality.md\`。
+10. 只有显式使用 \`ospec execute review ... --run --command "..."\` 时才运行本地 reviewer 命令，并写入 \`artifacts/agents/review-runs/\`；提供 \`--decision\` 时可写回 review decision。
+11. review artifact 有非 \`PENDING\` 决策后，用 \`ospec execute feedback [changes/active/<change>] [--stage spec|quality]\` 写入 \`artifacts/agents/review-feedback-plan.json\` 和 \`artifacts/agents/review-feedback-plan.md\`；继续派发工作前要明确接受、修订、澄清或阻塞处理。
+11. 人工修改 task graph、execution session、review artifact、debug evidence 或 verification checklist 后，用 \`ospec execute sync [changes/active/<change>]\` 重建 \`artifacts/agents/worker-status.md\`。
+12. \`ospec session\`、\`ospec execute bootstrap\`、\`handoff\`、\`doc-review\`、\`workspace\`、plan 模式 \`worktree\`、\`finish\`、\`dispatch\`、\`launch\`、\`collect\`、\`retry\`、\`complete\`、\`review\`、\`feedback\`、\`debug\`、\`tdd\`、\`verify\` 与 \`sync\` 只更新 OSpec artifacts；除 \`workspace\`、\`worktree\` 与 \`finish\` 会读取 git 状态外，不直接编辑项目 source files。原生 subagent 由当前 AI harness 启动；只有显式 \`worktree --create\`、\`worktree --cleanup\`、fallback \`launch --run --command\`、\`review --run --command\` 或 fallback \`orchestrate\` 才运行 shell 命令。
+13. \`artifacts/agents/task-graph.json\` 中存在未解决 task 状态、无效依赖、缺失目标文件、缺失验证命令，或顶层 \`status\` 不是 \`completed\` 时，不得 archive。
+14. 实现后必须先完成每个 task 级 spec review，再完成该 task 的 quality review；最终必须先完成 \`artifacts/reviews/spec-compliance.md\`，再完成 \`artifacts/reviews/code-quality.md\`；任一 task 级或最终 review decision 仍为 \`PENDING\`、\`NEEDS_CHANGES\` 或 \`BLOCKED\` 时，不得 archive。
+15. 实现和 review 阶段必须更新 \`artifacts/agents/worker-status.md\`；任一 worker 状态仍为 \`PENDING\`、\`NEEDS_CONTEXT\` 或 \`BLOCKED\` 时不得声称完成，归档前 \`controller_status\` 必须为 \`DONE\`。
+16. 运行聚焦测试后，用 \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` 记录 \`artifacts/agents/tdd-evidence.json\`；该命令只记录 evidence，不会运行 shell 命令。
+17. 调试是 change 的一部分时，用 \`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` 记录 \`artifacts/agents/debug-evidence.json\`；该命令只记录 evidence，不会运行 shell 命令。
+18. 运行最新项目验证命令后，用 \`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\` 记录 \`artifacts/agents/verification-evidence.json\`；不要只用聊天摘要声称完成。
+19. 如果项目启用了 Stitch 且当前 change 激活了 \`stitch_design_review\`，先检查 \`artifacts/stitch/approval.json\`，未 \`approved\` 前不要把 change 视为可继续实现或可归档。
+20. 如果涉及 Stitch 安装、provider 切换、doctor 修复、MCP 或认证配置，优先读取仓库内 Stitch 规范；若缺失规范文档，则使用内建基线：Gemini 用 \`%USERPROFILE%/.gemini/settings.json\` 的 \`mcpServers.stitch.httpUrl\` 与 \`headers.X-Goog-Api-Key\`，Codex 用 \`%USERPROFILE%/.codex/config.toml\` 的 \`[mcp_servers.stitch]\`、\`type = "http"\`、\`url = "https://stitch.googleapis.com/mcp"\` 与 \`X-Goog-Api-Key\`。
+21. 如果内建 Codex provider 只读调用正常但 Stitch 写操作卡住，优先检查是否真正走了 \`codex exec --dangerously-bypass-approvals-and-sandbox\`；如果项目覆写了自定义 Codex runner，则该 runner 也必须显式带上这个参数。
+22. 发生重要变更后同步更新技能文档并重建索引。`, `# AI Guide
 
 ## Working Order
 
 1. Read \`SKILL.index.json\` when available.
 2. Read the relevant \`SKILL.md\` files before editing code.
 3. Use \`changes/active/<change>\` as the execution layer.
-4. If Stitch is enabled and the current change activates \`stitch_design_review\`, inspect \`artifacts/stitch/approval.json\` first and do not treat the change as ready to continue or archive until it is \`approved\`.
-5. If Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read \`.ospec/plugins/stitch/docs/\` first; if those docs are missing, install or enable Stitch to sync them before changing config.
-6. If the built-in Codex provider succeeds on read-only calls but Stitch write operations stall, first verify the run actually uses \`codex exec --dangerously-bypass-approvals-and-sandbox\`; if the project overrides a custom Codex runner, that runner must also pass the same flag explicitly.
-7. Update skill documents and rebuild the index after meaningful changes.`, `# AI ガイド
+4. In AI-assisted change execution, draft or update \`design.md\` from the requirement, \`proposal.md\`, and project context before editing \`implementation-plan.md\`, deriving \`artifacts/agents/task-graph.json\`, editing \`tasks.md\`, or editing code.
+5. 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\`.
+6. Derive \`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\`; derive \`tasks.md\` from the task graph.
+6. When entering an existing OSpec project, use \`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\`.
+6. 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 task documents, verification documents, and matching evidence artifacts before closeout.
+6. Common agent artifacts include \`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\`, \`artifacts/agents/worker-status.md\`, \`artifacts/agents/debug-evidence.json\`, \`artifacts/agents/tdd-evidence.json\`, and \`artifacts/agents/verification-evidence.json\`.
+7. 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.
+8. When a change moves between agents, tools, worktrees, shells, or human operators, use \`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]\` to write \`artifacts/agents/handoff.json\` and \`artifacts/agents/handoff.md\`; this records the project session brief snapshot, target tool mapping, and safety rules only and does not launch workers or edit source files.
+8. 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.
+8. 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.
+9. 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\`; this command records a preparation plan only and does not run \`git worktree add\`.
+10. 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.
+9. When task-level handoff needs durable artifacts, 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; \`complete\` writes \`artifacts/agents/blockers/\` when the result is \`NEEDS_CONTEXT\` or \`BLOCKED\`.
+9. After dispatch, use \`ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]\` to write the native agent launch plan; it requires one active dispatch and ready workspace status and tells the controlling AI how to use the current harness native mechanism: Codex/GPT \`spawn_agent\`/\`wait_agent\`/\`close_agent\`, Claude Code Task, Gemini \`@generalist\`, and OpenCode \`@mention\`.
+9. The default multi-worker path is current-harness native subagents: dispatch parallel-safe packets, inspect \`launch-plan.md\`, start one native agent per safe packet, and record every result with \`ospec execute complete\`.
+9. Use \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` only as the final CLI fallback when the current AI harness cannot dispatch native subagents; fallback renders an explicit command template, runs worker commands concurrently, records \`artifacts/agents/orchestration-runs/\`, and collects results into the task graph.
+9. Use \`--run --command\` (that is, \`ospec execute launch ... --run --command "..."\`) only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; it writes \`artifacts/agents/worker-runs/\`. Then use \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` to record the fallback task result. Use \`ospec execute retry\` to reopen corrected blocked, needs-context, or failed work; completed tasks require \`--force\`.
+10. After each worker task completes, use \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`, 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 reviews are approved.
+10. 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/\`; do not dispatch final \`artifacts/reviews/code-quality.md\` before final \`artifacts/reviews/spec-compliance.md\` is approved.
+10. Only explicit \`ospec execute review ... --run --command "..."\` runs a local reviewer command; it captures \`artifacts/agents/review-runs/\` and can write the review decision when \`--decision\` is provided.
+11. After a review artifact has a non-\`PENDING\` decision, use \`ospec execute feedback [changes/active/<change>] [--stage spec|quality]\` to write \`artifacts/agents/review-feedback-plan.json\` and \`artifacts/agents/review-feedback-plan.md\`; handle feedback as accept, revise, clarify, or blocked before dispatching more work.
+11. 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\`.
+12. \`ospec session\`, \`ospec execute bootstrap\`, \`handoff\`, \`doc-review\`, \`workspace\`, plan-mode \`worktree\`, \`finish\`, \`dispatch\`, \`launch\`, \`collect\`, \`retry\`, \`complete\`, \`review\`, \`feedback\`, \`debug\`, \`tdd\`, \`verify\`, and \`sync\` update OSpec artifacts only; except for \`workspace\`, \`worktree\`, and \`finish\` reading git state, they do not edit project source files directly. Native subagents are launched by the current AI harness; shell commands run only with explicit \`worktree --create\`, \`worktree --cleanup\`, fallback \`launch --run --command\`, \`review --run --command\`, or fallback \`orchestrate\`.
+13. Do not archive while \`artifacts/agents/task-graph.json\` has unresolved task statuses, invalid dependencies, missing target files, missing verification commands, or top-level \`status\` other than \`completed\`.
+14. After implementation, complete each task-level spec review before that task's quality review, then complete final \`artifacts/reviews/spec-compliance.md\` before final \`artifacts/reviews/code-quality.md\`; do not archive while any task-level or final review decision is \`PENDING\`, \`NEEDS_CHANGES\`, or \`BLOCKED\`.
+15. During implementation and review, update \`artifacts/agents/worker-status.md\`; do not claim completion while any worker status is \`PENDING\`, \`NEEDS_CONTEXT\`, or \`BLOCKED\`; \`controller_status\` must be \`DONE\` before archive.
+16. After focused test runs, use \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` to record \`artifacts/agents/tdd-evidence.json\`; this command records evidence only and does not run shell commands.
+17. 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\`; this command records evidence only and does not run shell commands.
+18. 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 a chat summary.
+19. If Stitch is enabled and the current change activates \`stitch_design_review\`, inspect \`artifacts/stitch/approval.json\` first and do not treat the change as ready to continue or archive until it is \`approved\`.
+20. If Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read \`.ospec/plugins/stitch/docs/\` first; if those docs are missing, install or enable Stitch to sync them before changing config.
+21. If the built-in Codex provider succeeds on read-only calls but Stitch write operations stall, first verify the run actually uses \`codex exec --dangerously-bypass-approvals-and-sandbox\`; if the project overrides a custom Codex runner, that runner must also pass the same flag explicitly.
+22. Update skill documents and rebuild the index after meaningful changes.`, `# AI ガイド
 
 ## 作業順序
 
 1. まず \`SKILL.index.json\` を読む。
 2. コード編集前に関連する \`SKILL.md\` を読む。
 3. 現在の作業は \`changes/active/<change>\` を基準に進める。
-4. Stitch が有効で、現在の change が \`stitch_design_review\` を有効化している場合は、先に \`artifacts/stitch/approval.json\` を確認し、\`approved\` になるまで継続や archive 可と見なさない。
-5. Stitch のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定が関係する場合は、まずリポジトリ内の Stitch 仕様を読む。仕様がない場合のみ内蔵ベースラインを使う。
-6. 内蔵 Codex provider が読み取り専用呼び出しでは成功するのに Stitch 書き込みが止まる場合は、\`codex exec --dangerously-bypass-approvals-and-sandbox\` が本当に使われているかを確認する。カスタム Codex runner を使う場合も同じフラグを明示的に渡す。
-7. 重要な変更後は SKILL 文書を更新し、インデックスを再生成する。`, `# دليل الذكاء الاصطناعي
+4. AI 支援で change を進める場合は、要件、\`proposal.md\`、プロジェクト文脈から \`design.md\` を作成または更新してから \`implementation-plan.md\` を編集し、\`artifacts/agents/task-graph.json\` を導出し、\`tasks.md\` やコードを編集する。
+5. 不足判断がアーキテクチャ、API、データ、UI、リスクを実質的に変える場合だけ、短い設計質問を 1 つ行う。それ以外は仮定を \`design.md\` に記録する。
+6. \`implementation-plan.md\` は \`design.md\` から導き、対象ファイル、期待結果、検証コマンド、依存関係、並行可能な作業、競合を記録する。\`artifacts/agents/task-graph.json\` は \`implementation-plan.md\` から導き、\`tasks.md\` は task graph から導く。
+6. 既存の OSpec project に入るときは \`ospec session [path]\` で \`.ospec/session-brief.json\` と \`.ospec/session-brief.md\` を書き、active change、queued change、queue-run、cache fingerprint、次の安全な command context を記録する。これは project entry brief であり、active change の \`ospec execute bootstrap\` を置き換えない。
+6. \`tdd_cycle\`、\`root_cause_debug\`、\`verification_evidence\` など有効化された built-in quality policy steps は、archive-gated \`optional_steps\` として扱う。closeout 前に task documents、verification documents、対応する evidence artifacts で coverage を記録する。
+6. 主な agent artifacts は \`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\`、\`artifacts/agents/worker-status.md\`、\`artifacts/agents/debug-evidence.json\`、\`artifacts/agents/tdd-evidence.json\`、\`artifacts/agents/verification-evidence.json\` である。
+7. 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 を推奨する。
+8. 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 編集は行わない。
+8. 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 する。
+8. 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 する。
+8. 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\` は実行しない。
+9. 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 削除は実行しない。
+9. task-level handoff に durable artifacts が必要な場合は、\`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 result を記録する。\`--task\` は明示的な単一 task、\`--limit\` は dispatch batch size の上限に使う。\`complete\` が \`NEEDS_CONTEXT\` または \`BLOCKED\` を記録した場合は \`artifacts/agents/blockers/\` が生成される。
+9. dispatch 後は \`ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]\` で native agent launch plan を書く。active dispatch と ready workspace status が必要で、Codex/GPT は \`spawn_agent\`/\`wait_agent\`/\`close_agent\`、Claude Code は Task、Gemini は \`@generalist\`、OpenCode は \`@mention\` を使う指示を記録する。
+9. default の multi-worker path は current harness の native subagent である。parallel-safe packet を dispatch し、\`launch-plan.md\` を確認し、安全な packet ごとに native agent を起動し、\`ospec execute complete\` で結果を記録する。
+9. current AI harness が native subagent を使えない場合だけ、\`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` を最後の CLI fallback として使う。fallback は explicit command template を render し、worker command を並行実行し、\`artifacts/agents/orchestration-runs/\` を記録して task graph に collect する。
+9. native subagent が使えない、または明示的に bypass された場合だけ、single-worker CLI fallback として \`--run --command\`（つまり \`ospec execute launch ... --run --command "..."\`）を使い、\`artifacts/agents/worker-runs/\` を記録する。その後 \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` で fallback task result を記録する。blocked/needs-context/failed work の修正後は \`ospec execute retry\` で再 dispatch する。完了済み task は \`--force\` が必要。
+10. 各 worker task 完了後、\`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`、続けて \`--stage quality\` を使い、task-level reviewer packet を作成する。task-level review decision は \`artifacts/reviews/tasks/<task-id>/\` に保存され、両方が承認されるまで dependent task は dispatch されない。
+10. すべての task-level review が承認され task graph が完了した後、\`--task\` なしの \`ospec execute review [changes/active/<change>] [--stage spec|quality]\` で \`artifacts/agents/review-dispatches/\` 配下に final whole-change reviewer packet を作成する。final \`artifacts/reviews/spec-compliance.md\` が approved になる前に final \`artifacts/reviews/code-quality.md\` を dispatch しない。
+10. explicit \`ospec execute review ... --run --command "..."\` の場合のみ local reviewer command を実行し、\`artifacts/agents/review-runs/\` を記録する。\`--decision\` がある場合は review decision も書き戻せる。
+11. 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 を明確にする。
+11. task graph、execution session、review artifact、debug evidence、verification checklist を手動編集した後は \`ospec execute sync [changes/active/<change>]\` で \`artifacts/agents/worker-status.md\` を再構築する。
+12. \`ospec session\`、\`ospec execute bootstrap\`、\`handoff\`、\`doc-review\`、\`workspace\`、plan-mode \`worktree\`、\`finish\`、\`dispatch\`、\`launch\`、\`collect\`、\`retry\`、\`complete\`、\`review\`、\`feedback\`、\`debug\`、\`tdd\`、\`verify\`、\`sync\` は OSpec artifacts のみを更新する。\`workspace\`、\`worktree\`、\`finish\` が git state を読む場合を除き、project source files は直接編集しない。native subagent は current AI harness が起動する。shell command は explicit \`worktree --create\`、\`worktree --cleanup\`、fallback \`launch --run --command\`、\`review --run --command\`、または fallback \`orchestrate\` の場合のみ実行する。
+13. \`artifacts/agents/task-graph.json\` に未解決の task 状態、無効な依存関係、対象ファイル不足、検証コマンド不足、またはトップレベル \`status\` が \`completed\` でない状態がある場合は archive しない。
+14. 実装後は各 task-level spec review をその task の quality review より先に完了し、final \`artifacts/reviews/spec-compliance.md\` を final \`artifacts/reviews/code-quality.md\` より先に完了する。task-level または final review decision が \`PENDING\`、\`NEEDS_CHANGES\`、\`BLOCKED\` のままなら archive しない。
+15. 実装と review の間は \`artifacts/agents/worker-status.md\` を更新する。worker 状態が \`PENDING\`、\`NEEDS_CONTEXT\`、\`BLOCKED\` のままなら完了を主張しない。archive 前に \`controller_status\` は \`DONE\` でなければならない。
+16. focused test 実行後、\`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` で \`artifacts/agents/tdd-evidence.json\` を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない。
+17. debugging が change の一部だった場合、\`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` で \`artifacts/agents/debug-evidence.json\` を記録する。このコマンドは evidence の記録のみを行い、shell command は実行しない。
+18. fresh project verification commands を実行した後、\`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\` で \`artifacts/agents/verification-evidence.json\` を記録する。chat summary だけで完了を主張しない。
+19. Stitch が有効で、現在の change が \`stitch_design_review\` を有効化している場合は、先に \`artifacts/stitch/approval.json\` を確認し、\`approved\` になるまで継続や archive 可と見なさない。
+20. Stitch のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定が関係する場合は、まずリポジトリ内の Stitch 仕様を読む。仕様がない場合のみ内蔵ベースラインを使う。
+21. 内蔵 Codex provider が読み取り専用呼び出しでは成功するのに Stitch 書き込みが止まる場合は、\`codex exec --dangerously-bypass-approvals-and-sandbox\` が本当に使われているかを確認する。カスタム Codex runner を使う場合も同じフラグを明示的に渡す。
+22. 重要な変更後は SKILL 文書を更新し、インデックスを再生成する。`, `# دليل الذكاء الاصطناعي
 
 ## ترتيب العمل
 
 1. اقرأ \`SKILL.index.json\` أولاً إن وجد.
 2. اقرأ ملفات \`SKILL.md\` ذات الصلة قبل تعديل الكود.
 3. استخدم \`changes/active/<change>\` كطبقة التنفيذ الحالية.
-4. إذا كان Stitch مفعلاً وكان change الحالي يفعّل \`stitch_design_review\`، فافحص \`artifacts/stitch/approval.json\` أولاً ولا تعتبر change جاهزاً للاستمرار أو الأرشفة حتى تصبح حالته \`approved\`.
-5. إذا كان العمل يتضمن تثبيت Stitch أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة، فاقرأ مواصفة Stitch المحلية في المستودع أولاً. استخدم الخطوط الأساسية المدمجة فقط عند غياب المواصفة.
-6. إذا نجح provider الداخلي لـ Codex في الاستدعاءات للقراءة فقط لكن توقفت عمليات الكتابة الخاصة بـ Stitch، فتحقق أولاً من أن التشغيل يستخدم فعلاً \`codex exec --dangerously-bypass-approvals-and-sandbox\`. وإذا كان المشروع يبدل Runner مخصصاً لـ Codex فيجب أن يمرر العلم نفسه صراحةً.
-7. حدّث وثائق SKILL وأعد بناء الفهرس بعد التغييرات المهمة.`));
+4. عند تنفيذ change بمساعدة AI، أنشئ \`design.md\` أو حدّثه من المتطلب و\`proposal.md\` وسياق المشروع قبل تعديل \`implementation-plan.md\` أو اشتقاق \`artifacts/agents/task-graph.json\` أو تعديل \`tasks.md\` أو الكود.
+5. لا تطرح أكثر من سؤال تصميم موجز واحد إلا عندما يغيّر القرار الناقص البنية أو API أو البيانات أو UI أو المخاطر فعلياً؛ وإلا فسجل الافتراضات في \`design.md\`.
+6. يجب اشتقاق \`implementation-plan.md\` من \`design.md\` مع الملفات المستهدفة والنتائج المتوقعة وأوامر التحقق والاعتماديات والعمل القابل للتوازي والتعارضات؛ ويجب اشتقاق \`artifacts/agents/task-graph.json\` من \`implementation-plan.md\`؛ ويجب اشتقاق \`tasks.md\` من task graph.
+6. عند الدخول إلى مشروع OSpec موجود، استخدم \`ospec session [path]\` لكتابة \`.ospec/session-brief.json\` و\`.ospec/session-brief.md\` مع سياق active change وqueued change وqueue-run وcache fingerprint والأمر الآمن التالي؛ هذا project entry brief ولا يستبدل \`ospec execute bootstrap\` للـ active change.
+6. تعامل مع خطوات built-in quality policy المفعّلة مثل \`tdd_cycle\` و\`root_cause_debug\` و\`verification_evidence\` كـ \`optional_steps\` خاضعة لـ archive gate؛ غطّها في task documents وverification documents وملفات evidence المطابقة قبل closeout.
+6. تتضمن agent artifacts الشائعة \`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\` و\`artifacts/agents/worker-status.md\` و\`artifacts/agents/debug-evidence.json\` و\`artifacts/agents/tdd-evidence.json\` و\`artifacts/agents/verification-evidence.json\`.
+7. عند بدء أو استئناف 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 ...\` المطابق.
+8. عند نقل 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.
+8. قبل اشتقاق 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.
+8. قبل 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.
+8. قبل إنشاء 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\`.
+9. قبل الإغلاق النهائي، استخدم \`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.
+9. عندما تحتاج task-level handoff إلى durable artifacts، استخدم \`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 results؛ استخدم \`--task\` لمهمة واحدة صريحة و\`--limit\` لتحديد حجم dispatch batch؛ وعندما يسجل \`complete\` النتيجة \`NEEDS_CONTEXT\` أو \`BLOCKED\` يتم إنشاء \`artifacts/agents/blockers/\`.
+9. بعد dispatch، استخدم \`ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]\` لكتابة native agent launch plan؛ يتطلب active dispatch واحدا وحالة workspace ready، ويوضح للـ AI المتحكم آلية harness الأصلية: Codex/GPT عبر \`spawn_agent\`/\`wait_agent\`/\`close_agent\`، وClaude Code عبر Task، وGemini عبر \`@generalist\`، وOpenCode عبر \`@mention\`.
+9. مسار multi-worker الافتراضي هو native subagents في current harness: أنشئ parallel-safe packets، وافحص \`launch-plan.md\`، ثم شغّل native agent واحدا لكل packet آمن، وسجل كل نتيجة عبر \`ospec execute complete\`.
+9. استخدم \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` فقط كآخر CLI fallback عندما لا يدعم current AI harness native subagents؛ يرندر fallback explicit command template، ويشغّل worker commands بالتوازي، ويسجل \`artifacts/agents/orchestration-runs/\`، ثم يجمع النتائج إلى task graph.
+9. استخدم \`--run --command\` (أي \`ospec execute launch ... --run --command "..."\`) فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ يسجل ذلك \`artifacts/agents/worker-runs/\`. بعدها استخدم \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم \`ospec execute retry\` لإعادة dispatch؛ المهام المكتملة تحتاج \`--force\`.
+10. بعد اكتمال كل worker task، استخدم \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\` ثم \`--stage quality\` لإنشاء task-level reviewer packets؛ تحفظ قرارات task-level داخل \`artifacts/reviews/tasks/<task-id>/\` وتبقى المهام التابعة محجوبة حتى اعتماد المراجعتين.
+10. بعد اعتماد كل task-level reviews واكتمال task graph، استخدم \`ospec execute review [changes/active/<change>] [--stage spec|quality]\` من دون \`--task\` لإنشاء final whole-change reviewer packets تتضمن project session brief snapshot تحت \`artifacts/agents/review-dispatches/\`؛ لا ترسل final \`artifacts/reviews/code-quality.md\` قبل اعتماد final \`artifacts/reviews/spec-compliance.md\`.
+10. لا يشغّل OSpec local reviewer command إلا عند استخدام \`ospec execute review ... --run --command "..."\` صراحة؛ يسجل ذلك \`artifacts/agents/review-runs/\` ويمكنه كتابة review decision عند تمرير \`--decision\`.
+11. بعد أن يحتوي 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 عمل إضافي.
+11. بعد تعديل task graph أو execution session أو review artifact أو debug evidence أو verification checklist يدويا، استخدم \`ospec execute sync [changes/active/<change>]\` لإعادة بناء \`artifacts/agents/worker-status.md\`.
+12. \`ospec session\` و\`ospec execute bootstrap\` و\`handoff\` و\`doc-review\` و\`workspace\` وplan-mode \`worktree\` و\`finish\` و\`dispatch\` و\`launch\` و\`collect\` و\`retry\` و\`complete\` و\`review\` و\`feedback\` و\`debug\` و\`tdd\` و\`verify\` و\`sync\` تحدّث OSpec artifacts فقط؛ وباستثناء قراءة \`workspace\` و\`worktree\` و\`finish\` لحالة git، لا تعدّل project source files مباشرة. يتم تشغيل native subagents بواسطة current AI harness؛ ولا تعمل أوامر shell إلا مع explicit \`worktree --create\` أو \`worktree --cleanup\` أو fallback \`launch --run --command\` أو \`review --run --command\` أو fallback \`orchestrate\`.
+13. لا تؤرشف عندما يحتوي \`artifacts/agents/task-graph.json\` على حالات مهام غير محسومة أو اعتماديات غير صالحة أو ملفات مستهدفة ناقصة أو أوامر تحقق ناقصة أو عندما لا يكون \`status\` العلوي \`completed\`.
+14. بعد التنفيذ، أكمل كل task-level spec review قبل quality review الخاصة بها، ثم أكمل final \`artifacts/reviews/spec-compliance.md\` قبل final \`artifacts/reviews/code-quality.md\`؛ ولا تؤرشف ما دام أي task-level أو final review decision هو \`PENDING\` أو \`NEEDS_CHANGES\` أو \`BLOCKED\`.
+15. أثناء التنفيذ والمراجعة، حدّث \`artifacts/agents/worker-status.md\`؛ ولا تدّعِ الاكتمال ما دامت أي حالة worker هي \`PENDING\` أو \`NEEDS_CONTEXT\` أو \`BLOCKED\`؛ ويجب أن تكون \`controller_status\` هي \`DONE\` قبل الأرشفة.
+16. بعد تشغيل focused tests، استخدم \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` لتسجيل \`artifacts/agents/tdd-evidence.json\`؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell.
+17. عندما يكون debugging جزءا من change، استخدم \`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` لتسجيل \`artifacts/agents/debug-evidence.json\`؛ هذا الأمر يسجل evidence فقط ولا يشغّل أوامر shell.
+18. بعد تشغيل project verification commands حديثة، استخدم \`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\` لتسجيل \`artifacts/agents/verification-evidence.json\`؛ ولا تدّعِ الاكتمال بمجرد ملخص داخل المحادثة.
+19. إذا كان Stitch مفعلاً وكان change الحالي يفعّل \`stitch_design_review\`، فافحص \`artifacts/stitch/approval.json\` أولاً ولا تعتبر change جاهزاً للاستمرار أو الأرشفة حتى تصبح حالته \`approved\`.
+20. إذا كان العمل يتضمن تثبيت Stitch أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة، فاقرأ مواصفة Stitch المحلية في المستودع أولاً. استخدم الخطوط الأساسية المدمجة فقط عند غياب المواصفة.
+21. إذا نجح provider الداخلي لـ Codex في الاستدعاءات للقراءة فقط لكن توقفت عمليات الكتابة الخاصة بـ Stitch، فتحقق أولاً من أن التشغيل يستخدم فعلاً \`codex exec --dangerously-bypass-approvals-and-sandbox\`. وإذا كان المشروع يبدل Runner مخصصاً لـ Codex فيجب أن يمرر العلم نفسه صراحةً.
+22. حدّث وثائق SKILL وأعد بناء الفهرس بعد التغييرات المهمة.`));
     }
     generateExecutionProtocolTemplate(input) {
         const language = input?.documentLanguage === 'zh-CN' ||
@@ -1407,15 +1523,73 @@ ${this.formatReferenceList(refs, 'قيد التحديد')}
 ## 真正来源
 
 - \`.skillrc\`
+- \`.ospec/session-brief.md\`
 - \`changes/active/<change>/proposal.md\`
+- \`changes/active/<change>/design.md\`
+- \`changes/active/<change>/implementation-plan.md\`
+- \`changes/active/<change>/artifacts/agents/task-graph.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.md\`
+- \`changes/active/<change>/artifacts/agents/handoff.json\`
+- \`changes/active/<change>/artifacts/agents/handoff.md\`
+- \`changes/active/<change>/artifacts/agents/document-review-dispatches/\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.json\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.md\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.json\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.md\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.json\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.md\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.json\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.md\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.json\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.md\`
 - \`changes/active/<change>/tasks.md\`
+- \`changes/active/<change>/artifacts/reviews/design-review.md\`
+- \`changes/active/<change>/artifacts/reviews/implementation-plan-review.md\`
+- \`changes/active/<change>/artifacts/reviews/spec-compliance.md\`
+- \`changes/active/<change>/artifacts/reviews/code-quality.md\`
+- \`changes/active/<change>/artifacts/agents/worker-status.md\`
+- \`changes/active/<change>/artifacts/agents/debug-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/tdd-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/verification-evidence.json\`
 - \`changes/active/<change>/state.json\`
 - \`changes/active/<change>/verification.md\`
 
+change 相对 agent artifacts 包括 \`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\`、\`artifacts/agents/worker-status.md\`、\`artifacts/agents/debug-evidence.json\`、\`artifacts/agents/tdd-evidence.json\` 和 \`artifacts/agents/verification-evidence.json\`。
+
 ## 规则
 
 项目级文档和分层技能文档用于承载长期知识。
 active change 文档用于承载当前实现工作。
+进入已有 OSpec 项目时，用 \`ospec session [path]\` 写入 \`.ospec/session-brief.json\` 和 \`.ospec/session-brief.md\`；该项目入口简报只记录 active change、queued change、queue-run、cache fingerprint 和安全下一步命令，不替代 active change 的 \`ospec execute bootstrap\`。
+将已激活的内建质量策略步骤（如 \`tdd_cycle\`、\`root_cause_debug\`、\`verification_evidence\`）视为受归档门禁约束的 \`optional_steps\`；收尾前必须在任务文档、验证文档和对应 evidence artifacts 中覆盖。
+AI 辅助执行 change 时，先基于需求、\`proposal.md\` 和项目上下文起草或更新 \`design.md\`，再编辑 \`implementation-plan.md\`、推导 \`artifacts/agents/task-graph.json\`、编辑 \`tasks.md\` 或代码。
+只有缺失决策会实质影响架构、API、数据、UI 或风险时，才提出一个简短设计问题；否则把假设写入 \`design.md\`。
+\`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>]\` 写入带 project session brief snapshot 的 \`artifacts/agents/bootstrap.json\` 和 \`artifacts/agents/bootstrap.md\`，然后按其中的下一步安全动作继续；已有 active dispatch 时，bootstrap 会推荐对应的 \`ospec execute launch ... --task ...\` 命令。
+change 需要在 agent、工具、worktree、shell 或人工操作者之间交接时，用 \`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、目标工具映射和安全规则，不会启动 worker 或编辑源码。
+推导或派发实现任务前，用 \`ospec execute doc-review [changes/active/<change>] [--stage design|plan]\` 生成带 project session brief snapshot 的 \`artifacts/agents/document-review-dispatches/\` 交接包，并创建 \`artifacts/reviews/design-review.md\` 或 \`artifacts/reviews/implementation-plan-review.md\`；design review 通过后才能派发 implementation plan review。
+派发 worker 前，用 \`ospec execute workspace [changes/active/<change>]\` 写入 \`artifacts/agents/workspace-status.json\` 和 \`artifacts/agents/workspace-status.md\`；如果状态为 \`needs_isolation\`，先清理当前工作区或转入隔离 git worktree，再进行并行派发。
+创建隔离 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\`；该命令只记录 readiness 和命令文本，不会 finalize、archive、push、merge 或删除 worktree。
+用 \`ospec execute dispatch [changes/active/<change>] [--task task-id] [--limit N]\` 生成并行安全的 worker 任务包批次和 \`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\` 限制派发批次大小；当 complete 记录 \`NEEDS_CONTEXT\` 或 \`BLOCKED\` 时，会生成 \`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 启动计划；它要求存在一个 active dispatch 且 workspace 状态为 ready，并说明当前控制 AI 如何使用 harness 原生 agent 机制：Codex/GPT 用 \`spawn_agent\`、\`wait_agent\`、\`close_agent\`，Claude Code 用 Task，Gemini 用 \`@generalist\`，OpenCode 用 \`@mention\`。
+默认多 worker 执行路径是当前 harness 原生 subagent：先 dispatch 并行安全 packet，查看 \`launch-plan.md\`，再为每个安全 packet 启动一个 native agent，并用 \`ospec execute complete\` 记录结果。
+只有当前 AI harness 不支持原生 subagent 时，才用 \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` 作为最后 CLI fallback；fallback 会渲染显式 command template、并发运行 worker command、记录 \`artifacts/agents/orchestration-runs/\`，并把结果 collect 回 task graph。
+只有原生 subagent 不可用或被明确绕过时，才用 \`--run --command\`（即 \`ospec execute launch ... --run --command "..."\`）作为单 worker CLI fallback，并写入 \`artifacts/agents/worker-runs/\`；随后用 \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` 记录 fallback 任务结果。修复 blocked、needs-context 或 failed work 后，用 \`ospec execute retry\` 重新派发；已完成任务必须显式 \`--force\` 才能 retry。
+每个 worker task 完成后，用 \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`，再用 \`--stage quality\` 生成 task 级 reviewer 交接包；task 级 review 决策写入 \`artifacts/reviews/tasks/<task-id>/\`，依赖任务会等这两个 review 通过后才可派发。
+所有 task 级 review 通过且 task graph 完成后，用不带 \`--task\` 的 \`ospec execute review [changes/active/<change>] [--stage spec|quality]\` 在 \`artifacts/agents/review-dispatches/\` 下生成最终 whole-change reviewer 交接包；\`artifacts/reviews/spec-compliance.md\` 通过前不得派发最终 \`artifacts/reviews/code-quality.md\`。
+只有显式使用 \`ospec execute review ... --run --command "..."\` 时才运行本地 reviewer 命令，并写入 \`artifacts/agents/review-runs/\`；提供 \`--decision\` 时可写回 review 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\`；继续派发工作前要明确接受、修订、澄清或阻塞处理。
+人工修改 task graph、execution session、review artifact、debug evidence 或 verification checklist 后，用 \`ospec execute sync [changes/active/<change>]\` 重建 \`artifacts/agents/worker-status.md\`。
+\`ospec session\`、\`ospec execute bootstrap\`、\`handoff\`、\`doc-review\`、\`workspace\`、plan 模式 \`worktree\`、\`finish\`、\`dispatch\`、\`launch\`、\`collect\`、\`retry\`、\`complete\`、\`review\`、\`feedback\`、\`debug\`、\`tdd\`、\`verify\` 与 \`sync\` 只更新 OSpec artifacts；除 \`workspace\`、\`worktree\` 与 \`finish\` 会读取 git 状态外，不直接编辑项目 source files。原生 subagent 由当前 AI harness 启动；只有显式 \`worktree --create\`、\`worktree --cleanup\`、fallback \`launch --run --command\`、\`review --run --command\` 或 fallback \`orchestrate\` 才运行 shell 命令。
+\`artifacts/agents/task-graph.json\` 中存在未解决 task 状态、无效依赖、缺失执行细节，或顶层 \`status\` 不是 \`completed\` 时，不得 archive。
+实现和 review 阶段必须更新 \`artifacts/agents/worker-status.md\`；任一 worker 状态仍为 \`PENDING\`、\`NEEDS_CONTEXT\` 或 \`BLOCKED\` 时，不得声称完成。
+归档前 \`controller_status\` 必须为 \`DONE\`。
+运行聚焦测试后，必须用 \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` 记录 \`artifacts/agents/tdd-evidence.json\`，或记录不适用原因。
+调试是 change 的一部分时，必须用 \`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` 记录 \`artifacts/agents/debug-evidence.json\`，或记录不适用原因。
+运行最新项目验证命令后，必须用 \`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\` 记录 \`artifacts/agents/verification-evidence.json\`。
+实现后必须先完成每个 task 级 spec review，再完成该 task 的 quality review；最终必须先完成 \`artifacts/reviews/spec-compliance.md\`，再完成 \`artifacts/reviews/code-quality.md\`；任一 task 级或最终 review decision 仍为 \`PENDING\`、\`NEEDS_CHANGES\` 或 \`BLOCKED\` 时，不得 archive。
 
 ## 插件阻断
 
@@ -1429,15 +1603,73 @@ active change 文档用于承载当前实现工作。
 ## Source of Truth
 
 - \`.skillrc\`
+- \`.ospec/session-brief.md\`
 - \`changes/active/<change>/proposal.md\`
+- \`changes/active/<change>/design.md\`
+- \`changes/active/<change>/implementation-plan.md\`
+- \`changes/active/<change>/artifacts/agents/task-graph.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.md\`
+- \`changes/active/<change>/artifacts/agents/handoff.json\`
+- \`changes/active/<change>/artifacts/agents/handoff.md\`
+- \`changes/active/<change>/artifacts/agents/document-review-dispatches/\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.json\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.md\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.json\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.md\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.json\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.md\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.json\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.md\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.json\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.md\`
 - \`changes/active/<change>/tasks.md\`
+- \`changes/active/<change>/artifacts/reviews/design-review.md\`
+- \`changes/active/<change>/artifacts/reviews/implementation-plan-review.md\`
+- \`changes/active/<change>/artifacts/reviews/spec-compliance.md\`
+- \`changes/active/<change>/artifacts/reviews/code-quality.md\`
+- \`changes/active/<change>/artifacts/agents/worker-status.md\`
+- \`changes/active/<change>/artifacts/agents/debug-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/tdd-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/verification-evidence.json\`
 - \`changes/active/<change>/state.json\`
 - \`changes/active/<change>/verification.md\`
 
+Change-relative agent artifacts include \`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\`, \`artifacts/agents/worker-status.md\`, \`artifacts/agents/debug-evidence.json\`, \`artifacts/agents/tdd-evidence.json\`, and \`artifacts/agents/verification-evidence.json\`.
+
 ## Rule
 
 Use project-level docs and layered skill files for long-lived knowledge.
 Use active changes for current implementation work.
+When entering an existing OSpec project, use \`ospec session [path]\` to write \`.ospec/session-brief.json\` and \`.ospec/session-brief.md\`; this project entry brief records active change, queued change, queue-run, cache fingerprint, and safe next command context only and does not replace active-change \`ospec execute bootstrap\`.
+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 task documents, verification documents, and matching evidence artifacts before closeout.
+During AI-assisted change execution, draft or update \`design.md\` from the requirement, \`proposal.md\`, and project context before editing \`implementation-plan.md\`, 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\`.
+Derive \`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\`; derive \`tasks.md\` from the task graph.
+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.
+When a change moves between agents, tools, worktrees, shells, or human operators, use \`ospec execute handoff [changes/active/<change>] [--target codex|gpt|claude|gemini|opencode|shell|generic]\` to write \`artifacts/agents/handoff.json\` and \`artifacts/agents/handoff.md\`; this records the project session brief snapshot, target tool mapping, and safety rules only and does not launch workers or edit 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.
+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\`; this command records a preparation plan only and does not run \`git worktree add\`.
+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; \`complete\` writes \`artifacts/agents/blockers/\` when the result is \`NEEDS_CONTEXT\` or \`BLOCKED\`.
+After dispatch, use \`ospec execute launch [changes/active/<change>] [--task task-id] [--target codex|gpt|claude|gemini|opencode|shell|generic] [--dry-run]\` to write the native agent launch plan; it requires one active dispatch and ready workspace status and tells the controlling AI how to use the current harness native mechanism: Codex/GPT \`spawn_agent\`/\`wait_agent\`/\`close_agent\`, Claude Code Task, Gemini \`@generalist\`, and OpenCode \`@mention\`.
+The default multi-worker path is current-harness native subagents: dispatch parallel-safe packets, inspect \`launch-plan.md\`, start one native agent per safe packet, and record every result with \`ospec execute complete\`.
+Use \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` only as the final CLI fallback when the current AI harness cannot dispatch native subagents; fallback renders an explicit command template, runs worker commands concurrently, records \`artifacts/agents/orchestration-runs/\`, and collects results into the task graph.
+Use \`--run --command\` (that is, \`ospec execute launch ... --run --command "..."\`) only as single-worker CLI fallback when native subagents are unavailable or explicitly bypassed; it writes \`artifacts/agents/worker-runs/\`. Then use \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` to record the fallback task result. Use \`ospec execute retry\` to reopen corrected blocked, needs-context, or failed work; completed tasks require \`--force\`.
+After each worker task completes, use \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`, 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 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/\`; do not dispatch final \`artifacts/reviews/code-quality.md\` before final \`artifacts/reviews/spec-compliance.md\` is approved.
+Only explicit \`ospec execute review ... --run --command "..."\` runs a local reviewer command; it captures \`artifacts/agents/review-runs/\` and can write the review decision when \`--decision\` is provided.
+After a review artifact has a non-\`PENDING\` decision, use \`ospec execute feedback [changes/active/<change>] [--stage spec|quality]\` to write \`artifacts/agents/review-feedback-plan.json\` and \`artifacts/agents/review-feedback-plan.md\`; handle feedback as accept, revise, clarify, or blocked before dispatching more work.
+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\`.
+\`ospec session\`, \`ospec execute bootstrap\`, \`handoff\`, \`doc-review\`, \`workspace\`, plan-mode \`worktree\`, \`finish\`, \`dispatch\`, \`launch\`, \`collect\`, \`retry\`, \`complete\`, \`review\`, \`feedback\`, \`debug\`, \`tdd\`, \`verify\`, and \`sync\` update OSpec artifacts only; except for \`workspace\`, \`worktree\`, and \`finish\` reading git state, they do not edit project source files directly. Native subagents are launched by the current AI harness; shell commands run only with explicit \`worktree --create\`, \`worktree --cleanup\`, fallback \`launch --run --command\`, \`review --run --command\`, or fallback \`orchestrate\`.
+Do not archive while \`artifacts/agents/task-graph.json\` has unresolved task statuses, invalid dependencies, missing execution details, or top-level \`status\` other than \`completed\`.
+During implementation and review, update \`artifacts/agents/worker-status.md\`; do not claim completion while any worker status is \`PENDING\`, \`NEEDS_CONTEXT\`, or \`BLOCKED\`.
+\`controller_status\` must be \`DONE\` before archive.
+After focused test runs, record \`artifacts/agents/tdd-evidence.json\` with \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\`, or record why it is not applicable.
+When debugging is part of the change, record \`artifacts/agents/debug-evidence.json\` with \`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\`, or record why it is not applicable.
+After running fresh project verification commands, record \`artifacts/agents/verification-evidence.json\` with \`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\`.
+After implementation, complete each task-level spec review before that task's quality review, then complete final \`artifacts/reviews/spec-compliance.md\` before final \`artifacts/reviews/code-quality.md\`; do not archive while any task-level or final review decision is \`PENDING\`, \`NEEDS_CHANGES\`, or \`BLOCKED\`.
 
 ## Plugin Gates
 
@@ -1451,15 +1683,73 @@ Use active changes for current implementation work.
 ## 参照元
 
 - \`.skillrc\`
+- \`.ospec/session-brief.md\`
 - \`changes/active/<change>/proposal.md\`
+- \`changes/active/<change>/design.md\`
+- \`changes/active/<change>/implementation-plan.md\`
+- \`changes/active/<change>/artifacts/agents/task-graph.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.md\`
+- \`changes/active/<change>/artifacts/agents/handoff.json\`
+- \`changes/active/<change>/artifacts/agents/handoff.md\`
+- \`changes/active/<change>/artifacts/agents/document-review-dispatches/\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.json\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.md\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.json\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.md\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.json\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.md\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.json\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.md\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.json\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.md\`
 - \`changes/active/<change>/tasks.md\`
+- \`changes/active/<change>/artifacts/reviews/design-review.md\`
+- \`changes/active/<change>/artifacts/reviews/implementation-plan-review.md\`
+- \`changes/active/<change>/artifacts/reviews/spec-compliance.md\`
+- \`changes/active/<change>/artifacts/reviews/code-quality.md\`
+- \`changes/active/<change>/artifacts/agents/worker-status.md\`
+- \`changes/active/<change>/artifacts/agents/debug-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/tdd-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/verification-evidence.json\`
 - \`changes/active/<change>/state.json\`
 - \`changes/active/<change>/verification.md\`
 
+Change-relative agent artifacts include \`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\`, \`artifacts/agents/worker-status.md\`, \`artifacts/agents/debug-evidence.json\`, \`artifacts/agents/tdd-evidence.json\`, and \`artifacts/agents/verification-evidence.json\`.
+
 ## ルール
 
 長期知識にはプロジェクト文書とレイヤー化された SKILL を使う。
 現在の実装作業には active change を使う。
+既存の OSpec project に入るときは \`ospec session [path]\` で \`.ospec/session-brief.json\` と \`.ospec/session-brief.md\` を書く。この project entry brief は active change、queued change、queue-run、cache fingerprint、次の安全な command context のみを記録し、active change の \`ospec execute bootstrap\` を置き換えない。
+\`tdd_cycle\`、\`root_cause_debug\`、\`verification_evidence\` など有効化された built-in quality policy steps は、archive-gated \`optional_steps\` として扱う。closeout 前に task documents、verification documents、対応する evidence artifacts で coverage を記録する。
+AI 支援で change を進める場合は、要件、\`proposal.md\`、プロジェクト文脈から \`design.md\` を作成または更新してから \`implementation-plan.md\` を編集し、\`artifacts/agents/task-graph.json\` を導出し、\`tasks.md\` やコードを編集する。
+不足判断がアーキテクチャ、API、データ、UI、リスクを実質的に変える場合だけ、短い設計質問を 1 つ行う。それ以外は仮定を \`design.md\` に記録する。
+\`implementation-plan.md\` は \`design.md\` から導き、対象ファイル、期待結果、検証コマンド、依存関係、並行可能な作業、競合を記録する。\`artifacts/agents/task-graph.json\` は \`implementation-plan.md\` から導き、\`tasks.md\` は task graph から導く。
+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 編集は行わない。
+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 する。
+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 result を記録する。\`--task\` は明示的な単一 task、\`--limit\` は dispatch batch size の上限に使う。\`complete\` が \`NEEDS_CONTEXT\` または \`BLOCKED\` を記録した場合は \`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 を書く。active dispatch と ready workspace status が必要で、Codex/GPT は \`spawn_agent\`/\`wait_agent\`/\`close_agent\`、Claude Code は Task、Gemini は \`@generalist\`、OpenCode は \`@mention\` を使う指示を記録する。
+multi-worker execution は current harness native subagents が default。parallel-safe packet を dispatch し、\`artifacts/agents/launch-plan.md\` を確認し、安全な packet ごとに native agent を起動し、\`ospec execute complete\` で結果を記録する。
+current AI harness が native subagent を使えない場合だけ、\`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` を最後の CLI fallback として使う。fallback は explicit command template を render し、worker command を並行実行し、\`artifacts/agents/orchestration-runs/\` を記録して task graph に collect する。
+native subagent が使えない、または明示的に bypass された場合だけ、single-worker CLI fallback として \`--run --command\`（つまり \`ospec execute launch ... --run --command "..."\`）を使い、\`artifacts/agents/worker-runs/\` を記録する。その後 \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` で fallback task result を記録する。blocked/needs-context/failed work の修正後は \`ospec execute retry\` で再 dispatch する。完了済み task は \`--force\` が必要。
+各 worker task 完了後、\`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\`、続けて \`--stage quality\` を使い、task-level reviewer packet を作成する。task-level review decision は \`artifacts/reviews/tasks/<task-id>/\` に保存され、両方が承認されるまで dependent task は dispatch されない。
+すべての task-level review が承認され task graph が完了した後、\`--task\` なしの \`ospec execute review [changes/active/<change>] [--stage spec|quality]\` で \`artifacts/agents/review-dispatches/\` 配下に final whole-change reviewer packet を作成する。\`artifacts/reviews/spec-compliance.md\` が approved になる前に final \`artifacts/reviews/code-quality.md\` を dispatch しない。
+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 を明確にする。
+task graph、execution session、review artifact、debug evidence、verification checklist を手動編集した後は \`ospec execute sync [changes/active/<change>]\` で \`artifacts/agents/worker-status.md\` を再構築する。
+\`ospec session\`、\`ospec execute bootstrap\`、\`handoff\`、\`doc-review\`、\`workspace\`、plan-mode \`worktree\`、\`finish\`、\`dispatch\`、\`launch\`、\`collect\`、\`retry\`、\`complete\`、\`review\`、\`feedback\`、\`debug\`、\`tdd\`、\`verify\`、\`sync\` は OSpec artifacts のみを更新する。\`workspace\`、\`worktree\`、\`finish\` が git state を読む場合を除き、project source files は直接編集しない。native subagent は current AI harness が起動する。shell command は explicit \`worktree --create\`、\`worktree --cleanup\`、fallback \`launch --run --command\`、\`review --run --command\`、または fallback \`orchestrate\` の場合のみ実行する。
+\`artifacts/agents/task-graph.json\` に未解決の task 状態、無効な依存関係、不足した実行詳細、またはトップレベル \`status\` が \`completed\` でない状態がある場合は archive しない。
+実装と review の間は \`artifacts/agents/worker-status.md\` を更新する。worker 状態が \`PENDING\`、\`NEEDS_CONTEXT\`、\`BLOCKED\` のままなら完了を主張しない。
+archive 前に \`controller_status\` は \`DONE\` でなければならない。
+focused test 実行後、\`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` で \`artifacts/agents/tdd-evidence.json\` を記録するか、適用外の理由を記録する。
+debugging が change の一部だった場合、\`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` で \`artifacts/agents/debug-evidence.json\` を記録するか、適用外の理由を記録する。
+fresh project verification commands を実行した後、\`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\` で \`artifacts/agents/verification-evidence.json\` を記録する。
+実装後は各 task-level spec review をその task の quality review より先に完了し、final \`artifacts/reviews/spec-compliance.md\` を final \`artifacts/reviews/code-quality.md\` より先に完了する。task-level または final review decision が \`PENDING\`、\`NEEDS_CHANGES\`、\`BLOCKED\` のままなら archive しない。
 
 ## プラグインゲート
 
@@ -1473,15 +1763,73 @@ Use active changes for current implementation work.
 ## مصدر الحقيقة
 
 - \`.skillrc\`
+- \`.ospec/session-brief.md\`
 - \`changes/active/<change>/proposal.md\`
+- \`changes/active/<change>/design.md\`
+- \`changes/active/<change>/implementation-plan.md\`
+- \`changes/active/<change>/artifacts/agents/task-graph.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.json\`
+- \`changes/active/<change>/artifacts/agents/bootstrap.md\`
+- \`changes/active/<change>/artifacts/agents/handoff.json\`
+- \`changes/active/<change>/artifacts/agents/handoff.md\`
+- \`changes/active/<change>/artifacts/agents/document-review-dispatches/\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.json\`
+- \`changes/active/<change>/artifacts/agents/workspace-status.md\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.json\`
+- \`changes/active/<change>/artifacts/agents/worktree-plan.md\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.json\`
+- \`changes/active/<change>/artifacts/agents/finish-plan.md\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.json\`
+- \`changes/active/<change>/artifacts/agents/launch-plan.md\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.json\`
+- \`changes/active/<change>/artifacts/agents/review-feedback-plan.md\`
 - \`changes/active/<change>/tasks.md\`
+- \`changes/active/<change>/artifacts/reviews/design-review.md\`
+- \`changes/active/<change>/artifacts/reviews/implementation-plan-review.md\`
+- \`changes/active/<change>/artifacts/reviews/spec-compliance.md\`
+- \`changes/active/<change>/artifacts/reviews/code-quality.md\`
+- \`changes/active/<change>/artifacts/agents/worker-status.md\`
+- \`changes/active/<change>/artifacts/agents/debug-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/tdd-evidence.json\`
+- \`changes/active/<change>/artifacts/agents/verification-evidence.json\`
 - \`changes/active/<change>/state.json\`
 - \`changes/active/<change>/verification.md\`
 
+Change-relative agent artifacts include \`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\`, \`artifacts/agents/worker-status.md\`, \`artifacts/agents/debug-evidence.json\`, \`artifacts/agents/tdd-evidence.json\`, and \`artifacts/agents/verification-evidence.json\`.
+
 ## القاعدة
 
 استخدم وثائق المشروع وملفات SKILL متعددة الطبقات للمعرفة طويلة الأمد.
 واستخدم التغييرات النشطة للأعمال التنفيذية الحالية.
+عند الدخول إلى مشروع OSpec موجود، استخدم \`ospec session [path]\` لكتابة \`.ospec/session-brief.json\` و\`.ospec/session-brief.md\`؛ هذا project entry brief يسجل سياق active change وqueued change وqueue-run وcache fingerprint والأمر الآمن التالي فقط ولا يستبدل \`ospec execute bootstrap\` للـ active change.
+تعامل مع خطوات built-in quality policy المفعّلة مثل \`tdd_cycle\` و\`root_cause_debug\` و\`verification_evidence\` كـ \`optional_steps\` خاضعة لـ archive gate؛ غطّها في task documents وverification documents وملفات evidence المطابقة قبل closeout.
+عند تنفيذ change بمساعدة AI، أنشئ \`design.md\` أو حدّثه من المتطلب و\`proposal.md\` وسياق المشروع قبل تعديل \`implementation-plan.md\` أو اشتقاق \`artifacts/agents/task-graph.json\` أو تعديل \`tasks.md\` أو الكود.
+لا تطرح أكثر من سؤال تصميم موجز واحد إلا عندما يغيّر القرار الناقص البنية أو API أو البيانات أو UI أو المخاطر فعلياً؛ وإلا فسجل الافتراضات في \`design.md\`.
+يجب اشتقاق \`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.
+قبل اشتقاق 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.
+قبل 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 results؛ استخدم \`--task\` لمهمة واحدة صريحة و\`--limit\` لتحديد حجم dispatch batch؛ وعندما يسجل \`complete\` النتيجة \`NEEDS_CONTEXT\` أو \`BLOCKED\` يتم إنشاء \`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؛ يتطلب active dispatch واحدا وحالة workspace ready، ويوضح للـ AI المتحكم آلية harness الأصلية: Codex/GPT عبر \`spawn_agent\`/\`wait_agent\`/\`close_agent\`، وClaude Code عبر Task، وGemini عبر \`@generalist\`، وOpenCode عبر \`@mention\`.
+مسار multi-worker الافتراضي هو native subagents في current harness: أنشئ parallel-safe packets، وافحص \`artifacts/agents/launch-plan.md\`، ثم شغّل native agent واحدا لكل packet آمن، وسجل كل نتيجة عبر \`ospec execute complete\`.
+استخدم \`ospec execute orchestrate [changes/active/<change>] --command "..." [--limit N] [--max-rounds N] [--timeout-ms N]\` فقط كآخر CLI fallback عندما لا يدعم current AI harness native subagents؛ يرندر fallback explicit command template، ويشغّل worker commands بالتوازي، ويسجل \`artifacts/agents/orchestration-runs/\`، ثم يجمع النتائج إلى task graph.
+استخدم \`--run --command\` (أي \`ospec execute launch ... --run --command "..."\`) فقط كـ single-worker CLI fallback عندما لا تتوفر native subagents أو يتم تجاوزها صراحة؛ يسجل ذلك \`artifacts/agents/worker-runs/\`. بعدها استخدم \`ospec execute collect [changes/active/<change>] [--task task-id] [--run run-id]\` لتسجيل fallback task result. بعد إصلاح blocked أو needs-context أو failed work استخدم \`ospec execute retry\` لإعادة dispatch؛ المهام المكتملة تحتاج \`--force\`.
+بعد اكتمال كل worker task، استخدم \`ospec execute review [changes/active/<change>] --task <task-id> --stage spec\` ثم \`--stage quality\` لإنشاء task-level reviewer 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 packets تتضمن project session brief snapshot تحت \`artifacts/agents/review-dispatches/\`؛ لا ترسل final \`artifacts/reviews/code-quality.md\` قبل اعتماد final \`artifacts/reviews/spec-compliance.md\`.
+لا يشغّل 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 عمل إضافي.
+بعد تعديل task graph أو execution session أو review artifact أو debug evidence أو verification checklist يدويا، استخدم \`ospec execute sync [changes/active/<change>]\` لإعادة بناء \`artifacts/agents/worker-status.md\`.
+\`ospec session\` و\`ospec execute bootstrap\` و\`handoff\` و\`doc-review\` و\`workspace\` وplan-mode \`worktree\` و\`finish\` و\`dispatch\` و\`launch\` و\`collect\` و\`retry\` و\`complete\` و\`review\` و\`feedback\` و\`debug\` و\`tdd\` و\`verify\` و\`sync\` تحدّث OSpec artifacts فقط؛ وباستثناء قراءة \`workspace\` و\`worktree\` و\`finish\` لحالة git، لا تعدّل project source files مباشرة. يتم تشغيل native subagents بواسطة current AI harness؛ ولا تعمل أوامر shell إلا مع explicit \`worktree --create\` أو \`worktree --cleanup\` أو fallback \`launch --run --command\` أو \`review --run --command\` أو fallback \`orchestrate\`.
+لا تؤرشف عندما يحتوي \`artifacts/agents/task-graph.json\` على حالات مهام غير محسومة أو اعتماديات غير صالحة أو تفاصيل تنفيذ ناقصة أو عندما لا يكون \`status\` العلوي \`completed\`.
+أثناء التنفيذ والمراجعة، حدّث \`artifacts/agents/worker-status.md\`؛ ولا تدّعِ الاكتمال ما دامت أي حالة worker هي \`PENDING\` أو \`NEEDS_CONTEXT\` أو \`BLOCKED\`.
+ويجب أن تكون \`controller_status\` هي \`DONE\` قبل الأرشفة.
+بعد تشغيل focused tests، سجل \`artifacts/agents/tdd-evidence.json\` باستخدام \`ospec execute tdd [changes/active/<change>] --phase red|green|refactor --command "..."\` أو سجل سبب عدم الانطباق.
+عندما يكون debugging جزءا من change، سجل \`artifacts/agents/debug-evidence.json\` باستخدام \`ospec execute debug [changes/active/<change>] --symptom "..." --root-cause "..." --status FIXED\` أو سجل سبب عدم الانطباق.
+بعد تشغيل project verification commands حديثة، سجل \`artifacts/agents/verification-evidence.json\` باستخدام \`ospec execute verify [changes/active/<change>] --command "..." --status PASSED\`.
+بعد التنفيذ، أكمل كل task-level spec review قبل quality review الخاصة بها، ثم أكمل final \`artifacts/reviews/spec-compliance.md\` قبل final \`artifacts/reviews/code-quality.md\`؛ ولا تؤرشف ما دام أي task-level أو final review decision هو \`PENDING\` أو \`NEEDS_CHANGES\` أو \`BLOCKED\`.
 
 ## بوابات الإضافات