sdd-agent-platform 0.4.0 → 0.4.1

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

@@ -88,15 +88,15 @@ 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 dedicated \`/sdd:*\` entry.
-4. If the intent is still ambiguous after status, ask one clarifying question before spec/plan/do/test/sync-back/ship work.
+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.
-6. If status reports workflow_status=not_started, use \`/sdd:spec\` to create the current Git branch partition; do not use \`sdd init\` as the workflow branch entry.
+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 offering \`/sdd:do\`.
-9. If status recommends do, test, or sync-back, follow the dedicated \`/sdd:do\`, \`/sdd:test\`, or \`/sdd:sync-back\` entry instead of inferring completion from chat.
-10. If status recommends sync-back, use \`/sdd:sync-back\` to run \`sdd sync-back inspect --branch <branch> --task <task_id>\` first and follow apply_policy; pass an explicit run id only for replay/CI/old-run inspection. Direct-safe tasks may apply directly, confirm-required tasks need human confirmation and \`--approved\`.
-11. If the user asks to release or go online, use \`/sdd:ship\` / \`sdd ship --branch <branch> --dry-run\` for local readiness first; do not publish, push, tag, or create external release state without explicit confirmation.
+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.
 
 Refresh this managed skill with \`sdd update\` when drift is reported.
 `
@@ -119,7 +119,7 @@ sdd instructions spec --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.
 
-Repeated /sdd:spec calls represent requirement revisions. If plan/tasks/run evidence already exists, status must expose stale downstream hash state before plan/tasks/do continues.
+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.
 
 Do not design implementation in \`spec.md\`; stop before plan work when requirements, acceptance IDs, or risk gates are unclear.
 `
@@ -129,7 +129,7 @@ Do not design implementation in \`spec.md\`; stop before plan work when requirem
         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 /sdd:spec revisions can mark this plan stale. Agent visibility: scout/planner/spec-reviewer may participate; evidence lands in plan or review artifacts.
+        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.
 
 Run:
 
@@ -149,7 +149,7 @@ Stop before creating tasks when the technical solution is incomplete or has unre
         kind: 'command',
         relativePath: '.claude/commands/sdd/tasks.md',
         title: 'SDD tasks',
-        body: `Refine the existing SDD tasks document as an executable evidence contract, not a plain TODO list or project-management backlog. Include based_on_plan_hash from status so later plan/spec revisions can mark these tasks stale. Agent visibility: planner/reviewer may participate; execution evidence later lands in implement/review/validation artifacts.
+        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.
 
 Run:
 
@@ -158,9 +158,9 @@ sdd instructions tasks --json
 sdd tasks format
 \`\`\`
 
-Then write or refine \`specs/<branch>/tasks.md\` from the approved spec and plan. Include Delivery Map, Wave Plan, task blocks with acceptance_refs and plan_refs, affected_files, 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.
+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. Stop before \`sdd do task\` when task boundary, acceptance refs, plan refs, or evidence requirements are unclear.
+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.
 `
       },
       {
@@ -168,25 +168,28 @@ Keep metadata inside the \`\`\`sdd-task fenced block and companion sections outs
         kind: 'command',
         relativePath: '.claude/commands/sdd/test.md',
         title: 'SDD test',
-        body: `Execute task validation commands, capture command output, evaluate acceptance evidence coverage, and return one unified test judgment for the task.
+        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 verifies inspect --branch <branch>
+# 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>
 \`\`\`
 
 Workflow:
 
-1. Confirm \`verify.md\` exists and is current for the selected branch.
-2. Run \`sdd test task <task_id> --branch <branch>\` to execute task validation commands and evaluate mapped acceptance coverage; use \`--command\` only for a deliberate narrowed override.
-3. Treat generated command logs, test index, validator artifact, and unified evidence projection as runtime evidence references, not as workflow documents.
-4. If \`/sdd:test\` returns PASS, proceed to \`/sdd:sync-back\` / \`sdd sync-back inspect\`; if it returns FAIL or BLOCKED, fix the reported command or evidence gaps and rerun \`/sdd:test\`.
+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, create sync-back proposals, commit, publish, or treat command success alone as semantic PASS.
+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.
 `
       },
       {
@@ -212,10 +215,10 @@ Agent evidence flow: scout gathers bounded context only; implementer edits only
 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, use templates such as \`sdd artifact template artifacts/implement-<task_id>.md --task <task_id> --agent implementer\`, \`sdd artifact template artifacts/review-<task_id>.md --task <task_id> --agent reviewer\`, and \`sdd artifact template artifacts/validation-<task_id>.md --task <task_id> --agent validator\`; save the physical file under branch evidence \`.sdd/runs/<branchSlug>/evidence/artifacts/\`, pass the run-relative \`artifacts/<file>\` path to CLI flags, and keep source/test files in \`## Evidence\`, not in \`sdd-result.artifacts\`.
+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, recommend \`/sdd:test\` / \`sdd test task <task_id> --branch <branch>\` so command execution and acceptance coverage are judged together.
+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.
 `
@@ -225,7 +228,7 @@ Do not create worktrees, auto commit, or mark missing evidence as PASS.
         kind: 'command',
         relativePath: '.claude/commands/sdd/sync-back.md',
         title: 'SDD sync-back',
-        body: `Inspect and optionally apply the verified task completion proposal back into tasks.md. Sync-back is a document write-back gate, not another implementation step.
+        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:
 
@@ -235,16 +238,16 @@ sdd instructions sync-back --json
 sdd sync-back inspect --branch <branch> --task <task_id>
 \`\`\`
 
-Workflow:
+Diagnostic workflow:
 
-1. Resolve exactly one task id and workflow partition from \`sdd status\`, the recommended command, or the user request. Stop and ask if either is ambiguous.
+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>\`.
+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 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.
+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, and do not change source files during sync-back.
+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.
 `
       },
       {
@@ -340,7 +343,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 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\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`
   };
 }
 

package/node_modules/@sdd-agent-platform/core/src/artifacts/sdd-result.test.ts

@@ -1,21 +1,21 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { initProject } from '../config/init-project.js';
 import { writeArtifact } from '../run-state/artifacts.js';
 import { createRun } from '../run-state/run-state.js';
-import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
-import { getArtifactPath, getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { getLegacyArtifactPath, getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
 import { parseSddResultMarkdown, validateSddResultArtifact } from './sdd-result.js';
 import { renderSddResultArtifactTemplate } from './templates.js';
 
 test('artifact path cannot escape artifacts directory', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-'));
   try {
-    assert.throws(() => getArtifactPath(root, 'run-1', '../outside.md'), /escapes artifacts directory/);
+    assert.throws(() => getLegacyArtifactPath(root, 'run-1', '../outside.md'), /escapes artifacts directory/);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
@@ -76,6 +76,52 @@ artifacts:
   }
 });
 
+test('validateSddResultArtifact accepts legacy run artifact directory for replay compatibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-result-legacy-artifact-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'run-1' });
+    const legacyPath = getLegacyArtifactPath(root, state.runId, 'review-T1.md');
+    await mkdir(path.dirname(legacyPath), { recursive: true });
+    await writeFile(legacyPath, `# Review
+
+\`\`\`sdd-result
+contract: sdd-result-v1
+version: 1.3.0
+agent: reviewer
+task: T1
+status: PASS
+artifacts:
+  - artifacts/review-T1.md
+\`\`\`
+`, 'utf8');
+
+    const report = await validateSddResultArtifact(root, state.runId, 'artifacts/review-T1.md', { expectedTask: 'T1', expectedAgent: 'reviewer' });
+
+    assert.equal(report.valid, true);
+    assert.equal(report.result?.task, 'T1');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeArtifact stores new payloads in branch evidence without creating legacy artifact dirs', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-result-evidence-artifact-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1', branch: 'feature', taskId: 'T1' });
+    const written = await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    const portablePath = written.absolutePath.replace(/\\/g, '/');
+
+    assert.equal(written.runRelativePath, 'artifacts/review-T1.md');
+    assert.match(portablePath, /\.sdd\/runs\/feature\/evidence\/artifacts\/review-T1-run-1-[a-f0-9]{12}\.md$/);
+    await assert.rejects(stat(path.join(root, '.sdd', 'runs', state.runId, 'artifacts')), /ENOENT/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('renderSddResultArtifactTemplate renders self-referencing reviewer artifact', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-artifact-template-review-'));
   try {

package/node_modules/@sdd-agent-platform/core/src/config/init-project.test.ts

@@ -203,13 +203,13 @@ test('initProject projects managed Claude Code entries by default', async () =>
     assert.match(skill, /do not paste or restate full status/);
     assert.match(skill, /natural-language intent/);
     assert.match(skill, /CLI\/core output/);
-    assert.match(skill, /\/sdd:\*/);
+    assert.match(skill, /projected command entry/);
     assert.match(skill, /ambiguous after status/);
     assert.match(skill, /sdd tasks inspect <task_id>/);
-    assert.match(skill, /sdd sync-back inspect --branch <branch> --task <task_id>/);
-    assert.match(skill, /\/sdd:ship/);
-    assert.match(skill, /\/sdd:test/);
-    assert.match(skill, /follow apply_policy/);
+    assert.match(skill, /treat `sdd sync-back inspect\|apply` as diagnostic\/recovery\/replay only/);
+    assert.match(skill, /sdd ship --branch <branch> --dry-run/);
+    assert.match(skill, /`test`/);
+    assert.doesNotMatch(skill, /follow apply_policy/);
     assert.match(skill, /workflow_status=not_started/);
     assert.match(skill, /workflow branch entry/);
     assert.match(doctorCommand, /sdd instructions doctor --json/);
@@ -240,7 +240,7 @@ test('initProject projects managed Claude Code entries by default', async () =>
     assert.match(planCommand, /based_on_spec_hash/);
     assert.match(planCommand, /PlantUML/);
     assert.match(planCommand, /state-machine risk needs a state diagram/);
-    assert.match(tasksCommand, /executable evidence contract/);
+    assert.match(tasksCommand, /executable task and verification contracts/);
     assert.match(tasksCommand, /based_on_plan_hash/);
     assert.match(doCommand, /sdd status/);
     assert.match(doCommand, /sdd instructions do --json/);
@@ -248,13 +248,16 @@ test('initProject projects managed Claude Code entries by default', async () =>
     assert.match(doCommand, /artifacts\/implement-<task_id>\.md/);
     assert.match(doCommand, /--agent implementer/);
     assert.match(doCommand, /sdd do task <task_id>/);
-    assert.match(doCommand, /sdd test task <task_id> --branch <branch>/);
+    assert.match(doCommand, /sdd test batch/);
+    assert.match(doCommand, /sdd test wave/);
     assert.match(testCommand, /sdd instructions test --json/);
-    assert.match(testCommand, /sdd verifies inspect --branch <branch>/);
-    assert.match(testCommand, /Execute task validation commands/);
+    assert.match(testCommand, /sdd test batch <batch_id> --branch <branch>/);
+    assert.match(testCommand, /sdd test wave --branch <branch> --wave <n>/);
+    assert.match(testCommand, /Execute validation from the frozen tasks\.md \+ verify\.md contract/);
+    assert.match(testCommand, /sdd ship --branch <branch> --dry-run/);
     assert.match(syncBackCommand, /sdd instructions sync-back --json/);
     assert.match(syncBackCommand, /sdd sync-back inspect --branch <branch> --task <task_id>/);
-    assert.match(syncBackCommand, /approval_required=true/);
+    assert.match(syncBackCommand, /explicit recovery\/replay/);
     assert.match(syncBackCommand, /Do not apply without inspect/);
     assert.match(shipCommand, /sdd instructions ship --json/);
     assert.match(shipCommand, /sdd ship --branch <branch> --dry-run/);

package/node_modules/@sdd-agent-platform/core/src/config/init-project.ts

@@ -33,11 +33,12 @@ export async function applyInitDocuments(projectRoot: string, options: { branch:
   assertSafePathSegment(options.branch, 'branch');
   const docsRoot = path.join(projectRoot, 'specs', options.branch);
   const now = new Date().toISOString();
+  const tasksContent = renderInitTasksDocument(options.branch, now, options.docsLanguage);
   const documents = [
     { name: 'spec.md', content: renderInitSpecDocument(options.branch, now, options.docsLanguage) },
     { name: 'plan.md', content: renderInitPlanDocument(options.branch, now, options.docsLanguage) },
-    { name: 'tasks.md', content: renderInitTasksDocument(options.branch, now, options.docsLanguage) },
-    { name: 'verify.md', content: renderInitVerifyDocument(options.branch, now, options.docsLanguage) }
+    { name: 'tasks.md', content: tasksContent },
+    { name: 'verify.md', content: renderInitVerifyDocument(options.branch, now, options.docsLanguage, tasksContent) }
   ];
 
   if (!options.scaffoldDocuments) {

package/node_modules/@sdd-agent-platform/core/src/config/starter-documents.ts

@@ -1,3 +1,5 @@
+import { hashDocumentContent, hashTasksContract } from '../sdd-docs/document-hashes.js';
+
 function usesChineseInitDocs(value: string): boolean {
   return value === 'zh-CN';
 }
@@ -389,21 +391,29 @@ ${implementationNotes}
 `;
 }
 
-export function renderInitVerifyDocument(branch: string, timestamp: string, docsLanguage: string): string {
+export function renderInitVerifyDocument(branch: string, timestamp: string, docsLanguage: string, tasksContent: string): string {
   const zh = usesChineseInitDocs(docsLanguage);
   const title = zh ? '# Verify: Project Onboarding / 项目入门' : '# Verify: Project Onboarding';
   const purpose = zh
-    ? '这份 verify.md 是从 starter tasks 派生的 verification guidance，不是 runtime evidence，也不替代 `/sdd:test` 产生的验证证据。'
-    : 'This verify.md is task-derived verification guidance, not runtime evidence, and it does not replace validation evidence produced by `/sdd:test`.';
+    ? '这份 verify.md 是从 starter tasks 派生的 verification guidance，不是 runtime evidence，也不替代 `sdd test task|batch|wave` 产生的验证证据。'
+    : 'This verify.md is task-derived verification guidance, not runtime evidence, and it does not replace validation evidence produced by `sdd test task|batch|wave`.';
   const availability = zh
     ? '在替换真实 spec/plan/tasks 前，只能检查 onboarding scaffold 是否仍然可见且未被误当作已批准实现。'
     : 'Before replacing the real spec/plan/tasks, verification can only inspect that the onboarding scaffold is visible and not mistaken for approved implementation.';
+  const tasksContractHash = hashTasksContract(tasksContent) ?? 'missing';
+  const tasksHash = hashDocumentContent(tasksContent);
   return `---
 template: sdd-init-onboarding-verify-v1
 version: 1.4.0
 contract: sdd-verify-doc-v1
 sdd_managed_starter: true
 branch: ${branch}
+based_on_tasks_contract_hash: ${tasksContractHash}
+based_on_tasks_hash: ${tasksHash}
+author_role: verification-designer
+independent_from_roles:
+  - task-planner
+  - implementer
 created_at: ${timestamp}
 updated_at: ${timestamp}
 ---
@@ -418,13 +428,13 @@ ${purpose}
 
 | Task | Acceptance refs | Validation commands | Required artifacts | Verification availability |
 |---|---|---|---|---|
-| ONBOARDING-1 | AC-1<br>AC-2 | sdd status --branch ${branch}<br>sdd verifies inspect --branch ${branch} | none | ${availability} |
+| ONBOARDING-1 | AC-1<br>AC-2 | sdd status --branch ${branch}<br>sdd test task ONBOARDING-1 --branch ${branch} | none | ${availability} |
 
 ## 3. Verification Rules
 
 - This starter verify contract does not authorize source changes, validation execution, runtime mutation, sync-back, commit, push, publish, or release.
 - Replace starter spec, plan, tasks, and verify documents with a real branch contract before implementation.
-- Runtime PASS is judged by \`/sdd:test\` / \`sdd test task <task_id> --branch ${branch}\`; low-level verify remains available for compatibility diagnostics.
+- Runtime PASS is judged by \`sdd test task <task_id> --branch ${branch}\`, \`sdd test batch <batch_id> --branch ${branch}\`, or \`sdd test wave --branch ${branch}\` consuming the current verify contract; low-level verify remains available for compatibility diagnostics.
 - Re-run \`sdd verifies write --branch ${branch} --force\` only after reviewing changed task expectations.
 
 ## 4. Out of Scope

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

@@ -56,6 +56,8 @@ export const WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION = 'phase-7.3-workflow-stat
 export const VERIFY_DOCUMENT_CONTRACT_VERSION = 'sdd-verify-doc-v1';
 export const AGENT_CAPABILITY_CATALOG_CONTRACT_VERSION = 'phase-7.6-agent-capability-catalog-v1';
 export const COMMAND_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-7.7-command-team-runtime-v1';
+export const STAGE_TEAM_RUNTIME_CONTRACT_VERSION = 'phase-8.15-stage-team-runtime-v1';
+export const WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION = 'phase-8.16-workflow-gate-runtime-v1';
 export const RUNTIME_PROJECTION_ENVELOPE_CONTRACT_VERSION = 'sdd-runtime-projection-envelope-v1';
 export const CODING_FACT_SET_CONTRACT_VERSION = 'sdd-coding-fact-set-v1';
 export const CODING_RISK_PROFILE_CONTRACT_VERSION = 'sdd-coding-risk-profile-v1';

package/node_modules/@sdd-agent-platform/core/src/doctor/checks/run-evidence.ts

@@ -109,11 +109,11 @@ export async function inspectRunEvidence(projectRoot: string, options: { allRuns
       }
       if (routePreflightEvents.length > 0 && agentExecutionRecords.length === 0) {
         issueCount += 1;
-        checks.push({ level: 'FAIL', check: 'agent_execution_record', message: `${runId}: agent_router_preflight exists but no AgentExecutionRecord was persisted.`, action: 'Persist blocked/skipped/claimed/completed execution provenance under .sdd/runs/<run_id>/agent-executions/.' });
+        checks.push({ level: 'FAIL', check: 'agent_execution_record', message: `${runId}: agent_router_preflight exists but no AgentExecutionRecord was persisted.`, action: 'Persist blocked/skipped/claimed/completed execution provenance in runtime.sqlite agent_executions.' });
       }
       if (routePreflightEvents.some(routePreflightNeedsTeamSession) && teamSessionRecords.length === 0) {
         issueCount += 1;
-        checks.push({ level: 'FAIL', check: 'team_session_record', message: `${runId}: team-mode preflight exists but no TeamSessionRecord was persisted.`, action: 'Persist team-mode provenance under .sdd/runs/<run_id>/team-sessions/.' });
+        checks.push({ level: 'FAIL', check: 'team_session_record', message: `${runId}: team-mode preflight exists but no TeamSessionRecord was persisted.`, action: 'Persist team-mode provenance in runtime.sqlite team_sessions.' });
       }
       for (const delegation of Object.values(state.delegations).filter((candidate) => isDelegationTerminal(candidate.status))) {
         if (agentExecutionRecords.length > 0 && !agentExecutionRecords.some((record) => record.delegationId === delegation.delegationId)) {
@@ -167,7 +167,7 @@ export async function inspectRunEvidence(projectRoot: string, options: { allRuns
 
 
   if (states.length === 0) {
-    checks.push({ level: 'WARN', check: 'run_evidence', message: 'No runs found in runtime.sqlite.', action: 'Create a run before /sdd:do or /sdd:test.' });
+    checks.push({ level: 'WARN', check: 'run_evidence', message: 'No runs found in runtime.sqlite.', action: 'Create a run before do/test execution.' });
   } else if (inspected.length === 0 && issueCount === 0) {
     checks.push({ level: 'WARN', check: 'run_evidence', message: branchPartition ? `No non-archived runs were inspected for branch ${branchPartition}.` : 'No non-archived runs were inspected.', action: 'Use sdd doctor --all-runs to audit archived history or create a new run.' });
   } else if (issueCount === 0) {

package/node_modules/@sdd-agent-platform/core/src/doctor/doctor.test.ts

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { execFile } from 'node:child_process';
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
@@ -20,7 +20,8 @@ import { recordStageRunProjection, recordWorkflowHandoffProjection, type StageRu
 import { decideContextOffload, evaluateContextLoadSignal, recordContextLoadSignalProjection, recordContextOffloadDecisionProjection } from '../context-offload.js';
 import { recordSubagentDispatchProjection, type SubagentDispatch } from '../subagents.js';
 import { runShip } from '../lifecycle/ship.js';
-import { withRuntimeStore } from '../storage/runtime-store.js';
+import { recordRuntimeSyncBackDecision, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
+import { getProjectStatus } from '../status/project-status.js';
 import { doctor } from './doctor.js';
 
 const execFileAsync = promisify(execFile);
@@ -409,6 +410,34 @@ test('doctor reports unavailable Phase 8 runtime checks as warnings', async () =
   }
 });
 
+test('Phase 8.9 surfaces capability health in status, doctor, and ship gates', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-capability-health-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', capabilityHealthTaskMarkdown('SECURITY'));
+
+    const status = await getProjectStatus(root, { branch: 'master' });
+    const report = await doctor(root, { latestOnly: true, branch: 'master' });
+    const ship = await runShip(root, { branch: 'master', dryRun: true });
+    const doctorCheck = report.checks.find((check) => check.check === 'capability_health');
+    const shipCheck = ship.checks.find((check) => check.name === 'capability_health');
+
+    assert.equal(status.capabilityHealth.status, 'warn');
+    assert.equal(status.capabilityHealth.missingBaselineDomains.length, 0);
+    assert.equal(status.capabilityHealth.sources.quarantined > 0, true);
+    assert.equal(status.capabilityHealth.sources.denied > 0, true);
+    assert.deepEqual(status.capabilityHealth.releaseCriticalGaps, ['security-engineering']);
+    assert.equal(status.capabilityHealth.warnings.some((warning) => /release-critical capability gap security-engineering/.test(warning)), true);
+    assert.equal(doctorCheck?.level, 'WARN');
+    assert.match(doctorCheck?.message ?? '', /release_critical_gaps=security-engineering/);
+    assert.equal(shipCheck?.status, 'PASS');
+    assert.match(shipCheck?.message ?? '', /release_critical_gaps=security-engineering/);
+    assert.equal(shipCheck?.nextAction, undefined);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('ship reports token pressure as diagnostic pass', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-ship-token-diagnostic-'));
   try {
@@ -432,8 +461,8 @@ test('ship reports token pressure as diagnostic pass', async () => {
   }
 });
 
-test('ship blocks validated runs until sync-back is applied', async () => {
-  const root = await mkdtemp(path.join(tmpdir(), 'sdd-ship-syncback-required-'));
+test('ship accepts validated runs without requiring sync-back apply', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-ship-syncback-not-required-'));
   try {
     await initProject(root);
     await writeBranchDocs(root, 'master', validTaskMarkdown('T1', []));
@@ -453,13 +482,66 @@ test('ship blocks validated runs until sync-back is applied', async () => {
     const ship = await runShip(root, { branch: 'master', dryRun: true });
     const latestRunCheck = ship.checks.find((check) => check.name === 'latest_run');
 
-    assert.equal(latestRunCheck?.status, 'BLOCKED');
+    assert.equal(latestRunCheck?.status, 'PASS');
     assert.match(latestRunCheck?.message ?? '', /sync_back=not_created/);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
 
+test('doctor reports Phase 8.18 compatibility and Phase 9 readiness diagnostics', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase818-doctor-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1', branch: 'master', taskId: 'T1' });
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    const legacyRunDir = path.join(root, '.sdd', 'runs', state.runId);
+    await mkdir(path.join(legacyRunDir, 'agent-executions'), { recursive: true });
+    await writeFile(path.join(legacyRunDir, 'state.json'), '{}', 'utf8');
+    await writeFile(path.join(legacyRunDir, 'events.jsonl'), '{}\n', 'utf8');
+    await writeFile(path.join(legacyRunDir, 'invocations.jsonl'), '{}\n', 'utf8');
+    await writeFile(path.join(legacyRunDir, 'agent-executions', 'legacy.json'), '{}', 'utf8');
+    await writeRunState(root, {
+      ...state,
+      syncBack: {
+        ...state.syncBack,
+        status: 'proposed',
+        proposalPath: 'artifacts/sync-back-proposal.md',
+        proposalDigest: 'legacy-digest'
+      }
+    });
+    await recordRuntimeSyncBackDecision(root, {
+      decisionId: runtimeScopedId(state.runId, 'T1', 'sync-back'),
+      runId: state.runId,
+      branch: 'master',
+      taskId: 'T1',
+      status: 'blocked',
+      proposalPath: 'artifacts/sync-back-proposal.md',
+      proposalDigest: 'legacy-digest',
+      proposalPayloadId: null,
+      reasons: ['legacy divergence'],
+      createdAt: '2026-05-21T00:00:00.000Z',
+      updatedAt: '2026-05-21T00:00:00.000Z',
+      payload: {}
+    });
+
+    const report = await doctor(root, { allRuns: true, branch: 'master' });
+
+    const legacyRunFiles = report.checks.find((check) => check.check === 'phase8_18_legacy_run_files');
+    assert.equal(legacyRunFiles?.level, 'WARN');
+    assert.match(legacyRunFiles?.message ?? '', /run-1:state\.json/);
+    assert.match(legacyRunFiles?.message ?? '', /run-1:events\.jsonl/);
+    assert.match(legacyRunFiles?.message ?? '', /run-1:invocations\.jsonl/);
+    assert.doesNotMatch(legacyRunFiles?.message ?? '', /evidence/);
+    assert.equal(report.checks.some((check) => check.check === 'phase8_18_legacy_sidecars' && check.level === 'WARN' && /run-1/.test(check.message)), true);
+    assert.equal(report.checks.some((check) => check.check === 'phase8_18_sync_back_compat' && check.level === 'WARN' && /proposed->blocked/.test(check.message)), true);
+    assert.equal(report.checks.some((check) => check.check === 'phase9_readiness' && check.level === 'PASS' && /optional_advisory_only/.test(check.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('ship still blocks context offload curation', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-ship-context-curation-'));
   try {
@@ -486,6 +568,36 @@ test('ship still blocks context offload curation', async () => {
   }
 });
 
+function capabilityHealthTaskMarkdown(taskId: string): string {
+  return `# Tasks
+
+### ${taskId}: Security readiness task
+
+\`\`\`sdd-task
+id: ${taskId}
+status: pending
+wave: 1
+depends_on: []
+acceptance_refs:
+  - AC-1
+affected_files:
+  - packages/core/src/auth.ts
+validation:
+  - npm test
+risk:
+  - security
+\`\`\`
+
+#### Boundary
+
+Stay inside security readiness fixtures.
+
+#### Acceptance
+
+- AC-1: Security readiness is covered.
+`;
+}
+
 const doctorScope: RuntimeScope = { branch: 'master', taskId: 'T1', runId: 'run-1' };
 
 function doctorStageRun(): StageRun {