sdd-agent-platform 0.4.2 → 0.5.0

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

@@ -88,13 +88,13 @@ 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 bundle (\`spec\`, \`plan\`, \`tasks\`, \`do\`, \`test\`, \`ship\`, or \`doctor\`). The \`tasks\` bundle covers \`tasks -> verifies\`; the \`test\` bundle covers \`test -> goal-verify\`.
-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, tasks, or test, follow the corresponding projected command bundle or its canonical CLI command instead of inferring completion from chat.
+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.
 
@@ -125,48 +125,59 @@ This command is maintenance only: it updates SDD-managed projections and non-aut
         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 specs/<branch>/plan.md and .sdd/runs/<branch>/plan/*.md as agent-authored plan-stage evidence. Runtime close validates refs, hashes, contracts, and handoff state into .sdd/runtime.sqlite; it must not create or modify Markdown.
+        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. Have planner/reviewer/plan-manager author \`.sdd/runs/<branch>/plan/*.md\` evidence, including \`plan-collaboration-contract-vN.md\`, before close.
+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\`.
+
+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.
+
+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.
 
-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. Stop before tasks when the technical solution is incomplete or has unresolved design gaps.
+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.
 
-Do not let runtime author, repair, normalize, or migrate Markdown.`
+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: `Use this generated command as the user-visible bundle for the \`tasks -> verifies\` runtime stages. First refine specs/<branch>/tasks.md and .sdd/runs/<branch>/tasks/*.md as agent-authored tasks-stage evidence, then continue to verifies through this bundle only after runtime/status targets that internal stage.
+        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:
 
@@ -175,78 +186,50 @@ sdd status
 sdd instructions tasks --json
 sdd tasks format
 sdd tasks close --branch <branch> --json
-sdd tasks close --branch <branch> --target verifies --json
 \`\`\`
 
-Workflow:
-
-1. Write or refine \`specs/<branch>/tasks.md\` from the approved spec and plan. 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.
-2. Have task-planner/reviewer/tasks-manager author \`.sdd/runs/<branch>/tasks/*.md\` evidence, including \`tasks-collaboration-contract-vN.md\`, before \`sdd tasks close\`. Keep metadata inside the \`\`\`sdd-task fenced block and companion sections outside it.
-3. Run \`sdd tasks close --branch <branch> --json\`; runtime validates refs/frontmatter/hashes/contracts and writes only SQLite.
-4. If the fresh runtime handoff targets \`verifies\` inside this same bundle, have verification-designer/reviewer/verifies-manager author \`specs/<branch>/verify.md\` plus \`.sdd/runs/<branch>/verifies/*.md\` evidence, including \`verifies-collaboration-contract-vN.md\`.
-5. Run \`sdd tasks close --branch <branch> --target verifies --json\`; runtime validates verifies-stage refs/contracts and returns the next legal route.
-
-Do not implement code, run validation commands, silently advance to do, or let runtime author Markdown.`
-      },
-      {
-        id: 'sdd-test',
-        kind: 'command',
-        relativePath: '.claude/commands/sdd/test.md',
-        title: 'SDD test',
-        body: `Use this generated command as the user-visible bundle for the \`test -> goal-verify\` runtime stages. Bind validation intent to an accepted verify.md validation unit, execute that unit, keep command summaries in runtime read models, have test-stage agents author .sdd/runs/<branch>/test/*.md evidence, then continue to goal verification through this bundle only after runtime/status targets that internal stage.
-
-Run:
-
-\`\`\`bash
-sdd status
-sdd instructions test --json
-sdd test <validation_unit_id-or-validation_text> --branch <branch>
-sdd test close --branch <branch> --json
-sdd test close --branch <branch> --target goal-verify --json
-\`\`\`
+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 accepted \`verify.md\` exists for the selected branch; if missing or stale, return to verifies through the tasks bundle.
-2. Use \`sdd test <validation_unit_id-or-validation_text> --branch <branch>\` as the normal entry; task id, validation batch id, and accepted task title/text are equivalent only when they bind to one verify.md validation unit.
-3. Use \`sdd test task|batch|wave\` only for explicit low-level diagnostics, replay, or narrowed override flags such as \`--command\`, \`--run\`, \`--command-json\`, \`--command-file\`, or passthrough argv.
-4. Have test-runner/reviewer/test-manager author \`.sdd/runs/<branch>/test/*.md\` evidence, including \`test-collaboration-contract-vN.md\`; PASS command output should not create log artifacts unless the validation contract explicitly needs stdout/stderr as primary evidence.
-5. Run \`sdd test close --branch <branch> --json\`; runtime validates refs/frontmatter/hashes/contracts and writes only SQLite.
-6. If the fresh runtime handoff targets \`goal-verify\` inside this same bundle, have goal-verifier/reviewer author \`.sdd/runs/<branch>/goal-verify/*.md\` evidence, then run \`sdd test close --branch <branch> --target goal-verify --json\` so runtime records truthAlignment before ship readiness.
-
-Do not auto-fix failures, author or refresh \`verify.md\`, mutate \`tasks.md\`, 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: `Semantically bind /sdd:do or sdd do task input to one accepted task boundary, then run do-stage collaboration: implementer/reviewer/do-manager write .sdd/runs/<branch>/do/*.md evidence and runtime reconciles gate truth into SQLite.
+        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 <bound_task_id>
+sdd instructions execute --json
+sdd execute --branch <branch> --json
 \`\`\`
 
 Workflow:
 
-Use CLI/core output as the source of truth. Task id and accepted task title/text are equivalent when they bind to the same accepted task boundary. Agent evidence flow: implementer edits only inside the bound task boundary and writes \`.sdd/runs/<branch>/do/implementation-vN.md\`; code-reviewer writes \`.sdd/runs/<branch>/do/code-review-vN.md\`; do-manager writes \`.sdd/runs/<branch>/do/do-manager-vN.md\` as a closure request. Runtime reads these Markdown refs/hashes/frontmatter, validates the gate, and writes only SQLite projections/run state. 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. Run \`sdd status\`, then let CLI/core bind the user request or recommended next command to exactly one accepted task boundary. Stop if binding is ambiguous, missing, stale, or boundary-expanding.
-2. Run \`sdd instructions do --json\` and \`sdd tasks inspect <bound_task_id>\`; restate only the bound task Boundary, blocking gaps, and validation commands.
-3. Work only inside the selected task boundary; do not expand scope without a checkpoint.
-4. Implement within affected_files and capture changed file refs/hashes in \`.sdd/runs/<branch>/do/implementation-vN.md\` frontmatter.
-5. Have code-reviewer write \`.sdd/runs/<branch>/do/code-review-vN.md\` against the implementation evidence hash, whether approved or blocked.
-6. Have do-manager write \`.sdd/runs/<branch>/do/do-manager-vN.md\` as a closure request that references the reviewed implementation and review hash.
-7. Run \`sdd do task <task_id-or-task-text> --branch <branch>\`; runtime must read \`.sdd/runs/<branch>/do/*.md\`, validate frontmatter/hash/review/manager closure, and write only SQLite projections/run state.
-8. Report the run id, status, binding target, blocking gaps, accepted evidence refs, and next gate. If completed, proceed to \`sdd test <validation_unit_id-or-validation_text> --branch <branch>\` for verification.
-
-Do not create worktrees, auto commit, mark missing evidence as PASS, or let runtime author Markdown artifacts.
-`
+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',
@@ -266,7 +249,7 @@ sdd ship close --branch <branch> --json
 Workflow:
 
 1. Resolve the target branch/partition from \`sdd status\` or the user's explicit branch.
-2. Confirm goal-verify has recorded aligned truthAlignment or validated reconciliation truth.
+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.
@@ -331,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`
   };
 }
 
@@ -341,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`
   };
 }