sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/ai-tools.ts

@@ -88,193 +88,174 @@ Use the local or globally installed \`sdd\` CLI as the source of truth for this
 
 1. Accept the user's natural-language intent, then run \`sdd status\` first and report only workflow state, blocker/current task, and the recommended next command; do not paste or restate full status unless asked.
 2. Run \`sdd instructions overview --json\` only when the next action is unclear or you need the full dynamic command contract.
-3. Dynamic routing comes from CLI/core output, not this skill text; follow the recommended next command before choosing a projected command entry (\`spec\`, \`plan\`, \`tasks\`, \`do\`, \`test\`, \`ship\`, or \`doctor\`).
-4. If the intent is still ambiguous after status, ask one clarifying question before spec/plan/do/test/ship work.
-5. For risky requests that mention state-machine, concurrency, database, SQL, security, API/schema, CI/build, or external unknowns, run \`sdd lifecycle decide --from-text <text>\` before spec/plan work.
+3. Dynamic routing comes from CLI/core output, not this skill text; follow the recommended next command before choosing a projected command bundle (\`spec\`, \`plan\`, \`tasks\`, \`execute\`, \`ship\`, or \`doctor\`). The fixed public lifecycle is \`/sdd:spec -> /sdd:plan -> /sdd:tasks -> /sdd:execute -> /sdd:ship\`.
+4. If the intent is still ambiguous after status, ask one clarifying question before spec/plan/tasks/execute/ship work.
+5. Treat risk, domain, collaboration, and validation depth as signals inside the fixed lifecycle stages; do not expose removed lifecycle-decision commands as public happy-path commands.
 6. If status reports workflow_status=not_started, start the spec stage for the resolved Git branch partition; do not use \`sdd init\` as the workflow branch entry.
-7. If status points to gaps, drift, or doctor/update work, handle that maintenance action before do/test/ship.
-8. If status recommends a task, run \`sdd tasks inspect <task_id>\` and use the task Boundary and Acceptance before starting \`do\`.
-9. If status recommends do or test, follow the corresponding projected command entry or its canonical CLI command instead of inferring completion from chat.
-10. If status exposes legacy sync-back or projection drift, treat \`sdd sync-back inspect|apply\` as diagnostic/recovery/replay only; do not insert it into the ordinary happy path.
-11. If the user asks to release or go online, run \`sdd ship --branch <branch> --dry-run\` for local readiness first; do not publish, push, tag, or create external release state without explicit confirmation.
+7. If status points to gaps, drift, or doctor/update work, handle that maintenance action before execute/ship.
+8. If status recommends a task, run \`sdd tasks inspect <task_id>\` and use the task Boundary and Acceptance before starting \`/sdd:execute\`.
+9. If status recommends implementation or validation lane work, report it as /sdd:execute lane work instead of exposing removed implementation or validation surfaces as public lifecycle stages.
+10. If status exposes projection drift, run \`sdd doctor\` and follow diagnostic/recovery guidance before resuming the ordinary happy path.
+11. If the user asks to release or go online, run \`sdd ship close --branch <branch> --json\` for local readiness first; do not publish, push, tag, or create external release state without explicit confirmation.
 
 Refresh this managed skill with \`sdd update\` when drift is reported.
 `
       },
 
       commandEntry('sdd-doctor', '.claude/commands/sdd/doctor.md', 'doctor', 'Check project config, scoped run evidence, generated AI entry drift, and use sdd doctor fast|deep|recover for explicit diagnostic scope.'),
+      {
+        id: 'sdd-update',
+        kind: 'command',
+        relativePath: '.claude/commands/sdd/update.md',
+        title: 'SDD update',
+        body: `Refresh SDD-managed AI entries and re-import declared external/user-global/project skill capability metadata through the same idempotent update path used by init bootstrap. Use this for existing initialized projects when generated entries drift or a skill import needs dedupe/refresh.
+
+Run:
+
+\`\`\`bash
+sdd update
+sdd update --import-skill <capability_id> --source project|user-global|external --source-ref <path-or-reference> --domain <domain> --stage <stage>
+\`\`\`
+
+This command is maintenance only: it updates SDD-managed projections and non-authoritative skill capability metadata in .sdd/project.yml. It does not execute imported skills, grant lifecycle authority, close gates, or publish external state.
+`
+      },
       {
         id: 'sdd-spec',
         kind: 'command',
         relativePath: '.claude/commands/sdd/spec.md',
         title: 'SDD spec',
-        body: `Create or refine the SDD spec document as the workflow partition entry, not a technical design. Omit --branch to use the current Git branch partition; pass --branch <name> only when intentionally writing another partition. Agent visibility: scout may gather bounded context; spec-reviewer may review objective, scope, acceptance, and risk gates; evidence lands in spec review artifacts.
+        body: `Enter the SDD spec stage through the runtime projection and hand off to spec-manager. Do not treat this generated command as permission to directly draft a full spec.md from prompt text, and do not write subagent results as runtime primary evidence.
 
 Run:
 
 \`\`\`bash
 sdd status
 sdd instructions spec --json
+sdd spec close --branch <branch> --json
 \`\`\`
 
-Then create or refine \`specs/<partition>/spec.md\` with objective/customer value, problem/intent, users/actors, user stories or scenarios, in-scope/out-of-scope boundaries, functional and non-functional requirements, acceptance criteria with stable IDs such as AC-1, assumptions/dependencies, risks/hard gates, open questions, and lifecycle decision reference.
+Use the JSON payload's \`specStageWorkOrderHandoff\` as the required handoff to \`spec-manager\`. If the handoff is missing, follow the runtime authority repair reason instead of writing \`specs/<partition>/spec.md\`.
 
-Repeated spec-stage revisions represent requirement revisions. If plan/tasks/run evidence already exists, status must expose stale downstream hash state before plan/tasks/do continues.
+Spec-manager owns the content chain: surface request -> reframed problem -> real intent -> scope boundary -> acceptance criterion -> evidence target. It may use scout for knowable evidence and spec-reviewer for pressure review of changelog-only specs, hidden user decisions, weak acceptance evidence, and plan/task leakage, but those side logs do not become runtime primary truth.
 
-Do not design implementation in \`spec.md\`; stop before plan work when requirements, acceptance IDs, or risk gates are unclear.
-`
+Final spec.md V3 contains Problem Reframing / Intent Discovery, Change Delta, Scope, Requirements with reasoning, Acceptance Criteria / Evidence Targets, Definitions / Rules, Planning Constraints / Signals, Open Questions / Ambiguity Ledger, and Close Quality Evidence. It is the semantic contract for plan/tasks and the only runtime primary spec artifact.
+
+Scout, review, and manager outputs may exist as internal side logs, but runtime spec close accepts final \`specs/<partition>/spec.md\` ref/hash plus boundary facts, not those side logs as required evidence.
+
+Do not include legacy lifecycle metadata, runtime gate metadata, candidate/analyzer handoff wording, implementation plan, task list, validation plan, or subagent trace in \`spec.md\`. If blocking user decisions remain before plan, spec-manager must ask the user before producing a close-ready final spec.md. After final spec.md V3 is ready, run \`sdd spec close --branch <branch> --json\`.`
       },
       {
         id: 'sdd-plan',
         kind: 'command',
         relativePath: '.claude/commands/sdd/plan.md',
         title: 'SDD plan',
-        body: `Refine the existing SDD plan document as a deliverable technical solution, not a lightweight approach summary. Include based_on_spec_hash from status so later spec-stage revisions can mark this plan stale. Agent visibility: scout/planner/spec-reviewer may participate; evidence lands in plan or review artifacts.
+        body: `Enter the plan stage through projection-backed PlanStageWorkOrderHandoff. Plan-manager produces final \`specs/<branch>/plan.md\` V3 as an AI-ready Technical Design / Detailed Design artifact for tasks.
 
 Run:
 
 \`\`\`bash
+sdd status
 sdd instructions plan --json
+sdd plan close --branch <branch> --json
 \`\`\`
 
-Then write or refine \`specs/<branch>/plan.md\` as the technical bridge from approved spec to task-ready execution. Include background, goals/non-goals, current state, target design, architecture/component impact, interaction/sequence design, state/data design, API/schema design, concurrency/transaction/consistency design, key decisions, alternatives, risk control, rollout/rollback, validation matrix, and task breakdown rationale.
+Use the JSON payload's \`planStageWorkOrderHandoff\` as the required handoff to \`plan-manager\`. If the handoff is missing, follow the runtime authority repair reason instead of planning from latest \`specs/<partition>/spec.md\`.
 
-Use PlantUML fences for diagrams when useful: component diagrams for impact surface, sequence/activity diagrams for workflows and concurrency, state diagrams for state-machine risk, and deployment/data diagrams when release or data topology matters. Apply risk-driven requirements before task writing: state-machine risk needs a state diagram; concurrency risk needs sequence/activity plus consistency design; database risk needs data/transaction/rollback design; api_schema risk needs interface/schema compatibility; security/sql risk needs explicit risk controls.
+Plan-manager owns technical design synthesis through the chain: code/data fact -> design implication -> technical decision -> risk control -> validation scenario. It verifies the accepted spec ref/hash, builds a concrete implementation map, resolves scout gaps, defines interface/API/schema mappings, state/data/failure/rollback model, risk controls, scenario validation matrix, and task-stage constraints.
 
-Stop before creating tasks when the technical solution is incomplete or has unresolved design gaps.
-`
+Use \`plan-scout\` only as bounded evidence-to-plan input when code/data/domain facts are missing. Use \`plan-review-agent\` to detect \`TOO_THIN_FOR_TASKS\`, \`DENSE_BUT_SHALLOW\`, vague mappings, missing risk controls, weak validation hooks, and task-list leakage. Side logs are never runtime primary truth.
+
+Final plan.md V3 should contain Upstream Spec Trace, Planning Problem / Strategy Framing, Current Implementation Map, Target Design Overview, Change Topology / Responsibility Boundaries, Interface / API / Schema Design, State / Data / Concurrency Design, Key Design Decisions, Alternatives Considered, Risk Controls, Validation Strategy, Rollout / Rollback / Compatibility, Task-stage Constraints, Open Questions / User Decisions, and Plan Close Quality Evidence.
+
+Plan side logs and professional agent findings may exist as optional internal audit material, but runtime plan close accepts final \`specs/<branch>/plan.md\` ref/hash plus boundary facts, not .sdd/runs side logs as required evidence. Tasks-stage must consume accepted spec and accepted plan refs/hashes only.
+
+Do not include task graph, task units, task decomposition, code diff, validation results, runtime gate metadata, candidate/analyzer wording, or subagent trace in \`plan.md\`. Do not let runtime author, repair, normalize, or migrate Markdown. If blocking design decisions remain before tasks, ask the user before producing a close-ready final plan.md.`
       },
       {
         id: 'sdd-tasks',
         kind: 'command',
         relativePath: '.claude/commands/sdd/tasks.md',
         title: 'SDD tasks',
-        body: `Refine the existing SDD tasks stage outputs as executable task and verification contracts, not a plain TODO list or project-management backlog. Include based_on_plan_hash from status so later plan/spec revisions can mark these contracts stale. Agent visibility: task-planner writes tasks.md; task-quality, dependency/parallelization, validation-strategy, verification-designer, and verification-reviewer roles may participate before contracts freeze.
+        body: `Enter the tasks stage through projection-backed TasksStageWorkOrderHandoff. Tasks-manager produces final \`specs/<branch>/tasks.md\` V2 as AI-ready Implementation Tickets / Execution Playbook for \`/sdd:execute\`, not as a thin parser contract or backlog.
 
 Run:
 
 \`\`\`bash
+sdd status
 sdd instructions tasks --json
 sdd tasks format
+sdd tasks close --branch <branch> --json
 \`\`\`
 
-Then write or refine \`specs/<branch>/tasks.md\` from the approved spec and plan, and ensure \`specs/<branch>/verify.md\` is created or refreshed by the verification-designer after the task contract is stable. Include Delivery Map, implementation waves, validation batches/waves, review gate declarations, task blocks with acceptance_refs and plan_refs, affected_files, change_surface, implementation_wave, validation_batch, validation_timing, requires_verify_before_next, validation, risk, agent_fit, allowed_agents, required_artifacts, verification_availability, autonomy, plus companion sections for Boundary, Acceptance, Definition of Done, Evidence Expectations, and Implementation Notes.
-
-Keep metadata inside the \`\`\`sdd-task fenced block and companion sections outside it. Use \`validation_timing: task_end\` and \`requires_verify_before_next: true\` for strict/high-risk tasks; use \`batch_end\` or \`wave_end\` with \`validation_batch\` only when sequential accumulation is safe. Frontend-only tasks must not declare Maven/Gradle backend build validation. Stop before \`sdd do task\` when task boundary, acceptance refs, plan refs, evidence requirements, validation batches/waves, or verify contract expectations are unclear.
-`
-      },
-      {
-        id: 'sdd-test',
-        kind: 'command',
-        relativePath: '.claude/commands/sdd/test.md',
-        title: 'SDD test',
-        body: `Execute validation from the frozen tasks.md + verify.md contract, capture command output, evaluate acceptance evidence coverage, and return one unified test or validation-wave judgment.
-
-Run:
-
-\`\`\`bash
-sdd status
-sdd instructions test --json
-# sdd test consumes the current verify.md contract and blocks if it is missing or stale; do not generate verify.md here.
-sdd test task <task_id> --branch <branch>
-sdd test batch <batch_id> --branch <branch>
-sdd test wave --branch <branch> --wave <n>
-\`\`\`
+Use the JSON payload's \`tasksStageWorkOrderHandoff\` as the required handoff to \`tasks-manager\`. If the handoff is missing, follow the runtime authority repair reason instead of slicing from latest spec.md or plan.md.
 
 Workflow:
 
-1. Confirm \`verify.md\` exists and is current for the selected branch; if it is missing or stale, return to \`/sdd:tasks\` or use explicit \`sdd verifies write\` recovery before testing.
-2. Use \`sdd test task <task_id>\` for strict or task_end tasks, or for deliberate narrowed overrides with \`--command\`, \`--run\`, \`--command-json\`, \`--command-file\`, or passthrough argv.
-3. For batch_end or wave_end tasks, use the verify-declared \`sdd test batch <batch_id>\` or \`sdd test wave\` boundary so accumulated implementation evidence is judged together; default \`sdd test task\` routes batch_end tasks to their batch and wave_end tasks to their wave boundary.
-4. Treat generated command logs, test index, validator artifact, acceptance maps, and workflow gate decisions as runtime evidence references, not as workflow documents.
-5. If validation returns PASS, proceed to a decision card if policy requires one, otherwise run \`sdd ship --branch <branch> --dry-run\`; if it returns FAIL or BLOCKED, fix the reported command or evidence gaps and rerun the same test boundary.
-
-Do not auto-fix failures, author or refresh \`verify.md\`, mutate \`tasks.md\`, apply sync-back, commit, publish, or treat command success alone as semantic PASS.
-`
+1. Verify opened \`specs/<partition>/spec.md\` and \`specs/<partition>/plan.md\` content hashes match \`tasksStageWorkOrderHandoff.acceptedSpecRef\` and \`acceptedPlanRef\`.
+2. Build coverage across requirements, acceptance criteria, plan decisions, risks, and non-goals.
+3. Write or refine \`specs/<branch>/tasks.md\` using the chain: plan decision -> work-unit boundary -> dependency / rollback rationale -> internal execution sequence -> completion evidence -> one-to-one validation task -> failure route.
+4. Do not mechanically split by file type. If backend Java, SQL, XML/Dubbo wiring, UI/config, or other surfaces are one rollback unit, keep them in one implementation task and write ordered internal steps for execute.
+5. Every implementation task must hand off to exactly one validation task, and every validation task must validate exactly one implementation task; split broad validation scenarios into per-task checks instead of many-to-one mappings.
+6. Use \`task-slicer\` when rollback unit, dependency unlock, validation closure, shared writable ownership, or parallelism safety is unclear.
+7. Use \`task-review-agent\` to detect \`TOO_THIN_FOR_EXECUTE\`, \`CHECKLIST_TASKS\`, \`SCHEMA_FIRST_TASKS\`, \`BOUNDARY_CONFLICT\`, \`VALIDATION_INSUFFICIENT\`, oversized-without-sequence, many-to-one validation, scope expansion, missing expected results, and missing failure routes.
+8. Each implementation task must include readable work-unit context, upstream trace, allowed and forbidden modification boundaries, rollback unit, internal sequence when broad, dependency rationale, completion evidence, one-to-one validation handoff, and failure route; \`sdd-task\` metadata supports routing but cannot replace task substance.
+9. Run \`sdd tasks close --branch <branch> --json\`; accepted tasks ref/hash is handed off to execute and materialized into a minimal task routing/read model.
+
+Do not implement code, run validation commands, silently advance to execute, expose removed verification routes as public lifecycle stages, write candidate/analyzer wording or obligation/projection payloads into tasks.md, or let runtime author Markdown.`
       },
       {
-        id: 'sdd-do',
+        id: 'sdd-execute',
         kind: 'command',
-        relativePath: '.claude/commands/sdd/do.md',
-        title: 'SDD do',
-        body: `Execute one approved SDD task boundary through the ingestion-aware task workflow.
+        relativePath: '.claude/commands/sdd/execute.md',
+        title: 'SDD execute',
+        body: `Use this generated command for the public /sdd:execute stage. Execute consumes an accepted tasks.md ref/hash, materializes TaskUnitProjection/ExecutionLaneProjection/TaskDependencyGraphProjection through \`sdd execute --branch <branch> --json\`, then coordinates implementation and validation boards. It may read spec.md and plan.md only as shallow constraints for ambiguity, acceptance mapping, and goal validation; it must not reread them to invent task semantics.
 
 Run:
 
 \`\`\`bash
 sdd status
-sdd instructions do --json
-sdd tasks inspect <task_id>
+sdd instructions execute --json
+sdd execute --branch <branch> --json
 \`\`\`
 
 Workflow:
 
-Agent evidence flow: scout gathers bounded context only; implementer edits only inside the selected task boundary; reviewer records review evidence; debugger is optional after review failure; validator records validation and acceptance mapping. Artifact flags use run-relative paths such as \`artifacts/implement-<task_id>.md\`, \`artifacts/review-<task_id>.md\`, and \`artifacts/validation-<task_id>.md\`; physical files live under branch evidence \`.sdd/runs/<branchSlug>/evidence/artifacts/\`. This command entry does not authorize autonomous background execution.
+1. Confirm status routes to execute or that the active public stage is execute.
+2. Use \`sdd execute --branch <branch> --json\` as the runtime entry: it must reject missing/stale tasks handoff, and when the handoff is fresh it materializes task projections from the accepted tasks ref/hash before implementation.
+3. Route implementation, review, and debug work through the implementation board; route validation, checkpoint, evidence-judgment, and goal-validation work through the validation board.
+4. Load agent-team capability only for ready task routes from agentRouting; defer blocked tasks until dependencies clear and invalid tasks until contract repair.
+5. Keep implementation, review, validation, checkpoint, and evidence-judgment inside /sdd:execute; execute closure is sdd execute close --branch <branch> --json.
+6. Optional execute side evidence may be registered through runtime commands, but execute close validates accepted tasks ref/hash and materialized projections rather than fixed Markdown evidence files.
+7. Report implementation and validation board state as execute lane state, not as separate public lifecycle stages.
 
-
-1. Resolve exactly one task id from the user request or from the \`sdd status\` recommended next command. Stop and ask if it is ambiguous.
-2. Read \`sdd tasks inspect <task_id>\` and restate the task Boundary, Acceptance, gaps, and validation commands.
-3. Work only inside the selected task boundary; do not expand scope without a checkpoint.
-4. Before creating explicit result artifacts, create the task run first, then write templates through the CLI writer: \`sdd artifact template artifacts/implement-<task_id>.md --task <task_id> --agent implementer --run <run_id> --write\`, \`sdd artifact template artifacts/review-<task_id>.md --task <task_id> --agent reviewer --run <run_id> --write\`, and \`sdd artifact template artifacts/validation-<task_id>.md --task <task_id> --agent validator --run <run_id> --write\`; do not manually create copies under \`specs/<branch>/artifacts/\` or \`specs/<branch>/evidence/artifacts/\`. Pass the run-relative \`artifacts/<file>\` path to CLI flags, and keep source/test files in \`## Evidence\`, not in \`sdd-result.artifacts\`.
-5. Run \`sdd artifact validate <run_id> <artifact> --task <task_id> --agent <agent>\` before passing artifacts into \`sdd do task <task_id>\`.
-6. Run \`sdd do task <task_id>\` with explicit artifact paths when evidence is available; this path records Phase 3 artifact ingestion evidence for doctor.
-7. Report the run id, status, agent evidence artifacts, gaps, and next gate. If completed, follow the \`sdd status\` recommended next command: continue sequential \`sdd do task\` when safe, run \`sdd test task\` for strict/task_end work, or run \`sdd test batch\` / \`sdd test wave\` at the declared validation boundary.
-
-Do not create worktrees, auto commit, or mark missing evidence as PASS.
-`
-      },
-      {
-        id: 'sdd-sync-back',
-        kind: 'command',
-        relativePath: '.claude/commands/sdd/sync-back.md',
-        title: 'SDD sync-back',
-        body: `Inspect or replay legacy task completion write-back state for diagnostic, recovery, or compatibility use. Sync-back is a low-level projection repair command, not an ordinary happy-path workflow stage.
-
-Run:
-
-\`\`\`bash
-sdd status
-sdd instructions sync-back --json
-sdd sync-back inspect --branch <branch> --task <task_id>
-\`\`\`
-
-Diagnostic workflow:
-
-1. Resolve exactly one task id and workflow partition from an explicit recovery request, old run replay, CI inspection, or doctor/status diagnostic. Stop and ask if either is ambiguous.
-2. Run \`sdd sync-back inspect --branch <branch> --task <task_id>\` before any apply; pass \`<run_id>\` only for replay, CI, or old-run inspection.
-3. Report what apply would write: target tasks file, task id, markdown status transition, proposal path, evidence artifacts, apply_policy, and policy reasons.
-4. If inspect reports \`status=ready\` and \`apply_policy=direct\`, run \`sdd sync-back apply --branch <branch> --task <task_id>\` only for explicit recovery/replay.
-5. If inspect reports approval_required=true, ask for explicit human confirmation and only then run \`sdd sync-back apply --branch <branch> --task <task_id> --approved\`.
-6. Explain that default apply writes only tasks.md for the target task, appends the sync-back implementation note, marks run sync_back applied, and rebuilds the local run index; \`--refresh-verify\` is an explicit recovery option after reviewed task-contract changes.
-
-Do not apply without inspect, do not use \`--approved\` without human confirmation, do not change source files during sync-back, and do not recommend sync-back after normal \`/sdd:test\` PASS.
-`
+Do not treat /sdd:cmd, CLI help, or this generated entry as a stage agent command menu; AgentAssignment.allowedCommands must come from runtime CommandObligation.`
       },
       {
         id: 'sdd-ship',
         kind: 'command',
         relativePath: '.claude/commands/sdd/ship.md',
         title: 'SDD ship',
-        body: `Run local release-readiness checks and optionally write \`specs/<branch>/release.md\`. This command is a preflight/release-summary gate; it does not authorize npm publish, git push, git tag, deploy, or external release creation.
+        body: `Close ship readiness through agent-authored .sdd/runs/<branch>/ship/*.md evidence. Optional specs/<branch>/release.md is ship-agent authored, not runtime-authored.
 
 Run:
 
 \`\`\`bash
-sdd ship --branch <branch> --dry-run
+sdd status
 sdd instructions ship --json
+sdd ship close --branch <branch> --json
 \`\`\`
 
 Workflow:
 
 1. Resolve the target branch/partition from \`sdd status\` or the user's explicit branch.
-2. Run \`sdd ship --branch <branch> --dry-run\` first; inspect PASS/BLOCKED readiness and next actions without writing \`release.md\`.
-3. If the readiness output is acceptable, run \`sdd ship --branch <branch>\` to write \`specs/<branch>/release.md\`.
-4. Use \`sdd statusline --branch <branch>\` for compact runtime/test/team/token/evidence health when reporting progress.
+2. Confirm execute has accepted implementation, validation, checkpoint, and evidence-judgment evidence for the branch.
+3. Have ship-manager/release agent author \`.sdd/runs/<branch>/ship/*.md\` evidence, including \`ship-collaboration-contract-vN.md\`; write \`specs/<branch>/release.md\` only as an explicit ship-agent artifact if needed.
+4. Run \`sdd ship close --branch <branch> --json\`; runtime validates readiness refs/contracts/truthAlignment and writes only \`.sdd/runtime.sqlite\`.
 5. Run generated-entry drift, current-run health, typecheck, test, build, and package dry-run gates when preparing a real package release.
 6. Stop before publish, push, tag, deploy, or external release creation unless the user explicitly approves that separate action.
 
-Do not skip failed gates, do not treat historical doctor debt as a release blocker unless it affects current evidence, and do not mutate external release state from this preflight command.
-`
+Do not skip failed gates, do not treat historical doctor debt as a release blocker unless it affects current evidence, and do not let runtime author release Markdown.`
       }
     ];
   }
@@ -333,7 +314,7 @@ function commandEntry(id: string, relativePath: string, action: string, summary:
     kind: 'command',
     relativePath,
     title: `SDD ${action}`,
-    body: `${summary}\n\nRun:\n\n\`\`\`bash\nsdd instructions ${action} --json\n\`\`\`\n\nThen follow the returned CLI/core instruction payload.\n`
+    body: `${summary}\n\nRun:\n\n\`\`\`bash\nsdd instructions ${action} --json\n\`\`\`\n\nRead projectionRender.nextAction plus projectionRender.allowedCommands from the returned CLI/core instruction payload. Do not treat allowedCommands as a free-choice stage agent menu, and do not use diagnostic-only commands as the happy path.\n`
   };
 }
 
@@ -343,7 +324,7 @@ function workflowCommandEntry(id: string, relativePath: string, action: string,
     kind: 'command',
     relativePath,
     title: `SDD ${action}`,
-    body: `${summary}\n\nRun:\n\n\`\`\`bash\nsdd instructions ${action} --json\n${helperCommand}\n\`\`\`\n\nUse the helper command output as the canonical format reference. Keep harness metadata such as change_surface, implementation_wave, validation_batch, validation_timing, requires_verify_before_next, agent_fit, verification_availability, autonomy, allowed_agents, and required_artifacts inside the fenced sdd-task block; keep companion sections such as #### Boundary and #### Acceptance outside the fence. Then follow the returned CLI/core instruction payload.\n`
+    body: `${summary}\n\nRun:\n\n\`\`\`bash\nsdd instructions ${action} --json\n${helperCommand}\n\`\`\`\n\nRead projectionRender.nextAction plus projectionRender.requiredCommands[].command/effectKind/status from the returned CLI/core instruction payload. Use the helper command output only as a canonical format reference; it is not workflow authority and allowedCommands is not a free-choice stage agent menu. Keep only stable V2 anchors such as taskClass, unitType, dependencies, wave, affectedAreas, validationHandoff, validatesImplementationTasks, routingHints, sourceRequirements, sourceAcceptanceCriteria, and planRefs inside fenced sdd-task blocks; put task rationale, scope, done criteria, validation scope, pass criteria, and failure routing in readable prose outside the fence. Then follow the returned CLI/core instruction payload.\n`
   };
 }