sdd-agent-platform 0.3.0 → 0.4.0

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

@@ -0,0 +1,99 @@
+import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
+import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { readRunState } from '../run-state/run-state.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { isSddResultStatus } from './sdd-result.js';
+import type { SddResultStatus } from './sdd-result.js';
+
+export interface SddResultArtifactTemplateOptions {
+  branch?: string;
+  runId?: string;
+  taskId: string;
+  agent: string;
+  artifactPath: string;
+  status?: SddResultStatus;
+}
+
+interface AcceptanceCoverageTarget {
+  label: string;
+  description: string | null;
+}
+
+export async function renderSddResultArtifactTemplate(projectRoot: string, options: SddResultArtifactTemplateOptions): Promise<string> {
+  const runState = options.runId ? await readRunState(projectRoot, options.runId).catch(() => null) : null;
+  const branch = options.branch ?? runState?.partition ?? runState?.gitBranch ?? (await resolveSddContext(projectRoot)).branch;
+  const status = options.status ?? 'PASS';
+  if (!isSddResultStatus(status)) {
+    throw new Error(`Unsupported sdd-result status ${status}.`);
+  }
+  const artifactRootRelativePath = toArtifactRootRelativePath(options.artifactPath);
+  const runRelativeArtifactPath = getRunRelativeArtifactPath(artifactRootRelativePath);
+  const lines = [
+    `# ${options.agent} result`,
+    '',
+    '```sdd-result',
+    `contract: ${SDD_RESULT_CONTRACT}`,
+    `version: ${SDD_RESULT_VERSION}`,
+    `agent: ${options.agent}`,
+    `task: ${options.taskId}`,
+    `status: ${status}`,
+    'artifacts:',
+    `  - ${runRelativeArtifactPath}`,
+    '```',
+    ''
+  ];
+
+  let warning: string | null = null;
+  let task: SddTask | null = null;
+  try {
+    const model = await parseSddBranch(projectRoot, branch);
+    const inspected = inspectSddTask(model, options.taskId);
+    task = inspected.task;
+    if (!task) {
+      warning = `Task ${options.taskId} was not found in specs/${branch}/tasks.md.`;
+    }
+  } catch (error) {
+    warning = `Could not inspect task ${options.taskId} on branch ${branch}: ${messageFromError(error)}`;
+  }
+
+  if (warning) {
+    lines.push('## Warning', '', `- ${warning}`, '');
+  }
+
+  if (options.agent === 'validator' && task) {
+    lines.push('## Acceptance Mapping', '');
+    const targets = taskAcceptanceCoverageTargets(task);
+    lines.push(...(targets.length > 0
+      ? targets.map((target) => `- Acceptance ${target.label}: TODO. Add validation evidence${target.description ? ` for ${target.description}` : ''}.`)
+      : ['- No Acceptance items are declared for this task.']));
+    lines.push('', '## Evidence', '');
+    lines.push(...(task.validation.length > 0
+      ? task.validation.map((command) => `- TODO run validation command: ${command}`)
+      : ['- TODO add validation evidence.']));
+    lines.push('');
+  } else {
+    lines.push('## Evidence', '', `- TODO cite files, commands, and task ${options.taskId} evidence here.`, '');
+  }
+
+  return lines.join('\n');
+}
+
+function taskAcceptanceCoverageTargets(task: SddTask): AcceptanceCoverageTarget[] {
+  if (task.acceptanceRefs.length > 0) {
+    return task.acceptanceRefs.map((ref, index) => ({
+      label: ref,
+      description: task.acceptance[index] ?? null
+    }));
+  }
+  return task.acceptance.map((acceptance) => ({
+    label: acceptance,
+    description: null
+  }));
+}
+
+function messageFromError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,4 @@
+export * from './artifacts/ingestion.js';
+export * from './artifacts/sdd-evidence.js';
+export * from './artifacts/sdd-result.js';
+export * from './artifacts/templates.js';

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

@@ -0,0 +1,79 @@
+import type { RuntimeConfidence, RuntimeRef, RuntimeScope } from '../contracts.js';
+import { CODING_FACT_SET_CONTRACT_VERSION } from '../contracts.js';
+
+export type CodingFactKind = 'document' | 'task' | 'file' | 'test' | 'runtime' | 'evidence' | 'external';
+export type CodingFileFactClass = 'spec-doc' | 'runtime-state' | 'cli-source' | 'core-source' | 'test-source' | 'generated-ai-entry' | 'release-doc' | 'unknown';
+
+export interface CodingFact<TValue = unknown> {
+  id: string;
+  kind: CodingFactKind;
+  source: string;
+  scope: RuntimeScope;
+  confidence: RuntimeConfidence;
+  observedAt: string;
+  inputHash?: string;
+  refs: RuntimeRef[];
+  reasons: string[];
+  value: TValue;
+}
+
+export interface CodingFileFact {
+  path: string;
+  fileClass: CodingFileFactClass;
+  changed: boolean;
+  publicApi: boolean;
+  generated: boolean;
+  reasons: string[];
+}
+
+export interface CodingTestFact {
+  command: string;
+  acceptanceRefs: string[];
+  required: boolean;
+  sourceRefs: RuntimeRef[];
+}
+
+export interface CodingRuntimeFact {
+  name: string;
+  status: 'present' | 'missing' | 'stale' | 'failed' | 'unknown';
+  refs: RuntimeRef[];
+  reasons: string[];
+}
+
+export interface CodingEvidenceFact {
+  acceptanceRef: string;
+  evidenceRefs: RuntimeRef[];
+  status: 'present' | 'missing' | 'stale' | 'failed';
+  reasons: string[];
+}
+
+export interface CodingExternalFact {
+  name: string;
+  known: boolean;
+  confidence: RuntimeConfidence;
+  refs: RuntimeRef[];
+  reasons: string[];
+}
+
+export interface CodingFactSet {
+  contract: typeof CODING_FACT_SET_CONTRACT_VERSION;
+  scope: RuntimeScope;
+  request: {
+    intentKnown: boolean;
+    acceptanceKnown: boolean;
+    validationKnown: boolean;
+  };
+  documents: {
+    specExists: boolean;
+    planExists: boolean;
+    tasksExists: boolean;
+    verifiesExists: boolean;
+  };
+  facts: CodingFact[];
+  files: CodingFileFact[];
+  tests: CodingTestFact[];
+  runtime: CodingRuntimeFact[];
+  evidence: CodingEvidenceFact[];
+  external: CodingExternalFact[];
+  generatedAt: string;
+}

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

@@ -0,0 +1 @@
+export * from './coding-facts/contracts.js';

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

@@ -0,0 +1,303 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { getProjectStatus } from './project-status.js';
+import { initProject } from './init-project.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { readAgentRuntimeProjectConfig as readProjectConfig } from '../router/agent-runtime-config.js';
+
+
+test('initProject creates readable project config', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-'));
+  try {
+    const init = await initProject(root);
+    assert.equal(init.created, true);
+    const config = await readProjectConfig(root);
+    assert.equal(config.contract, 'phase-1.2-project-contract');
+    assert.equal(config.sdd.docs_language, 'zh-CN');
+    assert.equal(config.lifecycle.decision_required, true);
+    assert.match(await readFile(init.configPath, 'utf8'), /Project-level SDD document prose language/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject creates starter semantic documents by default', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-docs-'));
+  try {
+    const init = await initProject(root);
+    const spec = await readFile(path.join(root, 'specs', 'master', 'spec.md'), 'utf8');
+    const plan = await readFile(path.join(root, 'specs', 'master', 'plan.md'), 'utf8');
+    const tasks = await readFile(path.join(root, 'specs', 'master', 'tasks.md'), 'utf8');
+    const verify = await readFile(path.join(root, 'specs', 'master', 'verify.md'), 'utf8');
+    const branch = await parseSddBranch(root, 'master');
+    const status = await getProjectStatus(root, { branch: 'master' });
+
+    assert.equal(init.documents.branch, 'master');
+    assert.equal(init.documents.documents.every((document) => document.status === 'created'), true);
+    assert.match(spec, /sdd-init-onboarding-spec-v1/);
+    assert.match(spec, /## 1\. Objective \/ Customer Value/);
+    assert.match(spec, /## 4\. User Stories \/ Scenarios/);
+    assert.match(spec, /\| AC-1 \|/);
+    assert.match(spec, /Assumptions \/ Dependencies/);
+    assert.match(spec, /Risks \/ Hard Gates/);
+    assert.match(spec, /项目入门/);
+    assert.match(spec, /仓库在第一个真实变更前/);
+    assert.match(plan, /sdd-init-onboarding-plan-v1/);
+    assert.match(plan, /## 3\. Current State Analysis/);
+    assert.match(plan, /## 5\. Architecture \/ Component Design/);
+    assert.match(plan, /```plantuml/);
+    assert.match(plan, /Risk-driven Plan Requirements/);
+    assert.match(plan, /业务背景与技术背景/);
+    assert.match(tasks, /sdd-init-onboarding-tasks-v1/);
+    assert.match(tasks, /## 1\. Delivery Map/);
+    assert.match(tasks, /acceptance_refs:/);
+    assert.match(tasks, /plan_refs:/);
+    assert.match(tasks, /allowed_agents:/);
+    assert.match(tasks, /required_artifacts:/);
+    assert.match(tasks, /verification_availability:/);
+    assert.match(tasks, /#### Definition of Done/);
+    assert.match(tasks, /#### Evidence Expectations/);
+    assert.match(tasks, /Allowed scope 仅限/);
+    assert.match(verify, /sdd-init-onboarding-verify-v1/);
+    assert.match(verify, /contract: sdd-verify-doc-v1/);
+    assert.match(verify, /ONBOARDING-1/);
+    assert.match(verify, /不是 runtime evidence/);
+    assert.equal(branch.tasks.some((task) => task.id === 'ONBOARDING-1'), true);
+    assert.equal(status.documents.specExists, true);
+    assert.equal(status.documents.planExists, true);
+    assert.equal(status.documents.tasksExists, true);
+    assert.equal(status.documents.verifyExists, true);
+    assert.equal(status.gaps.some((gap) => gap.type === 'Document Gap'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject falls back to English starter document prose for non-Chinese docs_language', async () => {
+  for (const docsLanguage of ['en-US', 'fr-FR']) {
+    const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-language-fallback-'));
+    try {
+      await initProject(root, { scaffoldDocuments: false });
+      const configPath = path.join(root, '.sdd', 'project.yml');
+      const config = await readFile(configPath, 'utf8');
+      await writeFile(configPath, config.replace('docs_language: zh-CN', `docs_language: ${docsLanguage}`), 'utf8');
+
+      await initProject(root);
+      const spec = await readFile(path.join(root, 'specs', 'master', 'spec.md'), 'utf8');
+      const plan = await readFile(path.join(root, 'specs', 'master', 'plan.md'), 'utf8');
+      const tasks = await readFile(path.join(root, 'specs', 'master', 'tasks.md'), 'utf8');
+      const verify = await readFile(path.join(root, 'specs', 'master', 'verify.md'), 'utf8');
+
+      assert.match(spec, /# Spec: Project Onboarding/);
+      assert.match(spec, /the repository has a visible SDD entrypoint/);
+      assert.match(plan, /business and technical context/);
+      assert.match(tasks, /Allowed scope is limited/);
+      assert.match(verify, /task-derived verification guidance/);
+      assert.doesNotMatch(`${spec}\n${plan}\n${tasks}\n${verify}`, /项目入门|仓库在第一个真实变更前|业务背景与技术背景|Allowed scope 仅限|不是 runtime evidence/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+});
+
+test('initProject preserves existing semantic documents by default', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-preserve-'));
+  try {
+    await mkdir(path.join(root, 'specs', 'master'), { recursive: true });
+    await writeFile(path.join(root, 'specs', 'master', 'spec.md'), 'user spec', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'plan.md'), 'user plan', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'tasks.md'), 'user tasks', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'verify.md'), 'user verify', 'utf8');
+    const init = await initProject(root);
+
+    assert.equal(await readFile(path.join(root, 'specs', 'master', 'spec.md'), 'utf8'), 'user spec');
+    assert.equal(await readFile(path.join(root, 'specs', 'master', 'plan.md'), 'utf8'), 'user plan');
+    assert.equal(await readFile(path.join(root, 'specs', 'master', 'tasks.md'), 'utf8'), 'user tasks');
+    assert.equal(await readFile(path.join(root, 'specs', 'master', 'verify.md'), 'utf8'), 'user verify');
+    assert.equal(init.documents.documents.every((document) => document.status === 'unchanged'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject force overwrites semantic documents', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-force-'));
+  try {
+    await mkdir(path.join(root, 'specs', 'master'), { recursive: true });
+    await writeFile(path.join(root, 'specs', 'master', 'spec.md'), 'user spec', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'plan.md'), 'user plan', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'tasks.md'), 'user tasks', 'utf8');
+    await writeFile(path.join(root, 'specs', 'master', 'verify.md'), 'user verify', 'utf8');
+    const init = await initProject(root, { force: true });
+    const spec = await readFile(path.join(root, 'specs', 'master', 'spec.md'), 'utf8');
+    const plan = await readFile(path.join(root, 'specs', 'master', 'plan.md'), 'utf8');
+    const tasks = await readFile(path.join(root, 'specs', 'master', 'tasks.md'), 'utf8');
+    const verify = await readFile(path.join(root, 'specs', 'master', 'verify.md'), 'utf8');
+
+    assert.match(spec, /sdd-init-onboarding-spec-v1/);
+    assert.match(plan, /sdd-init-onboarding-plan-v1/);
+    assert.match(tasks, /sdd-init-onboarding-tasks-v1/);
+    assert.match(verify, /sdd-init-onboarding-verify-v1/);
+    assert.equal(init.documents.documents.every((document) => document.status === 'overwritten'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject scaffolds custom branch documents', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-branch-'));
+  try {
+    const init = await initProject(root, { branch: 'feature-x' });
+    const status = await getProjectStatus(root, { branch: 'feature-x' });
+
+    assert.equal(init.documents.branch, 'feature-x');
+    assert.match(await readFile(path.join(root, 'specs', 'feature-x', 'tasks.md'), 'utf8'), /id: ONBOARDING-1/);
+    assert.match(await readFile(path.join(root, 'specs', 'feature-x', 'verify.md'), 'utf8'), /sdd-init-onboarding-verify-v1/);
+    assert.equal(status.documents.specExists, true);
+    assert.equal(status.documents.planExists, true);
+    assert.equal(status.documents.tasksExists, true);
+    assert.equal(status.documents.verifyExists, true);
+    assert.equal(status.gaps.some((gap) => gap.type === 'Document Gap'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject can skip semantic document scaffold', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-init-skip-docs-'));
+  try {
+    const init = await initProject(root, { scaffoldDocuments: false });
+
+    await assert.rejects(readFile(path.join(root, 'specs', 'master', 'spec.md'), 'utf8'), /ENOENT/);
+    await assert.rejects(readFile(path.join(root, 'specs', 'master', 'verify.md'), 'utf8'), /ENOENT/);
+    assert.equal(init.documents.documents.every((document) => document.status === 'skipped'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject projects managed Claude Code entries by default', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-ai-init-'));
+  try {
+    const init = await initProject(root);
+    const skill = await readFile(path.join(root, '.claude', 'skills', 'sdd', 'SKILL.md'), 'utf8');
+    const doctorCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'doctor.md'), 'utf8');
+
+    const specCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'spec.md'), 'utf8');
+    const planCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'plan.md'), 'utf8');
+    const tasksCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'tasks.md'), 'utf8');
+    const doCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'do.md'), 'utf8');
+    const testCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'test.md'), 'utf8');
+    const syncBackCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'sync-back.md'), 'utf8');
+    const shipCommand = await readFile(path.join(root, '.claude', 'commands', 'sdd', 'ship.md'), 'utf8');
+
+    assert.equal(init.aiTools.length, 1);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.status === 'created'), true);
+    assert.match(skill, /sdd_contract: sdd-ai-entry-v1/);
+    assert.match(skill, /sdd_hash: sha256:/);
+    assert.match(skill, /manual `\/sdd` root intent router/);
+    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, /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, /workflow_status=not_started/);
+    assert.match(skill, /workflow branch entry/);
+    assert.match(doctorCommand, /sdd instructions doctor --json/);
+    assert.match(doctorCommand, /explicit diagnostic scope/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd.md')), /ENOENT/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd', 'init.md')), /ENOENT/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd', 'verify.md')), /ENOENT/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd', 'verifies.md')), /ENOENT/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd', 'update.md')), /ENOENT/);
+    await assert.rejects(access(path.join(root, '.claude', 'commands', 'sdd', 'instructions.md')), /ENOENT/);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-root'), false);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-init'), false);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-verify'), false);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-verifies'), false);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-update'), false);
+    assert.equal(init.aiTools[0].entries.some((entry) => entry.id === 'sdd-instructions'), false);
+    assert.match(specCommand, /sdd instructions spec --json/);
+    assert.match(planCommand, /sdd instructions plan --json/);
+    assert.match(tasksCommand, /sdd instructions tasks --json/);
+    assert.match(tasksCommand, /sdd tasks format/);
+    assert.match(tasksCommand, /acceptance_refs and plan_refs/);
+    assert.match(tasksCommand, /required_artifacts, verification_availability, autonomy/);
+    assert.match(tasksCommand, /metadata inside the ```sdd-task fenced block/);
+    assert.match(specCommand, /workflow partition entry/);
+    assert.match(specCommand, /not a technical design/);
+    assert.match(planCommand, /Refine the existing SDD plan document/);
+    assert.match(planCommand, /deliverable technical solution/);
+    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, /based_on_plan_hash/);
+    assert.match(doCommand, /sdd status/);
+    assert.match(doCommand, /sdd instructions do --json/);
+    assert.match(doCommand, /sdd tasks inspect <task_id>/);
+    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(testCommand, /sdd instructions test --json/);
+    assert.match(testCommand, /sdd verifies inspect --branch <branch>/);
+    assert.match(testCommand, /Execute task validation commands/);
+    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, /Do not apply without inspect/);
+    assert.match(shipCommand, /sdd instructions ship --json/);
+    assert.match(shipCommand, /sdd ship --branch <branch> --dry-run/);
+    assert.match(shipCommand, /does not authorize npm publish/);
+    assert.match(shipCommand, /statusline --branch <branch>/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject detects Maven multi-module Java projects', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-maven-'));
+  try {
+    await writeFile(path.join(root, 'pom.xml'), '<project><packaging>pom</packaging><modules><module>emp-api</module></modules></project>');
+    await initProject(root);
+    const config = await readProjectConfig(root);
+    assert.equal(config.project.language, 'java');
+    assert.equal(config.project.framework, 'ssm-maven-multimodule');
+    assert.deepEqual(config.validation.default, ['mvn compile']);
+    assert.equal(config.detection?.primary, 'java-ssm-maven-multimodule');
+    assert.equal(config.detection?.confidence, 'medium');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('initProject classifies mixed Java and Node repos by source evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-mixed-'));
+  try {
+    await writeFile(path.join(root, 'pom.xml'), '<project><packaging>pom</packaging><modules><module>emp-api</module></modules><dependencies><dependency><groupId>org.springframework</groupId></dependency><dependency><groupId>org.mybatis</groupId></dependency></dependencies></project>');
+    await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'tooling-only', devDependencies: { typescript: '^5.0.0' } }));
+    await mkdir(path.join(root, 'emp-api', 'src', 'main', 'java', 'com', 'emp'), { recursive: true });
+    await mkdir(path.join(root, 'emp-api', 'src', 'main', 'resources'), { recursive: true });
+    await writeFile(path.join(root, 'emp-api', 'src', 'main', 'java', 'com', 'emp', 'ApiController.java'), 'class ApiController {}');
+    await writeFile(path.join(root, 'emp-api', 'src', 'main', 'resources', 'applicationContext.xml'), '<beans></beans>');
+    await initProject(root);
+    const config = await readProjectConfig(root);
+    assert.equal(config.project.language, 'java');
+    assert.equal(config.project.framework, 'ssm-maven-multimodule');
+    assert.deepEqual(config.validation.default, ['mvn compile']);
+    assert.equal(config.detection?.mixed_stack, true);
+    assert.equal(config.detection?.candidates.some((candidate) => candidate.id === 'typescript-node'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,119 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { applyAiToolEntries, type AiProjectionResult, type AiToolSelection } from '../ai-tools.js';
+import { getProjectConfigPath, getRunsDir, getSddDir } from '../runtime-paths.js';
+import { detectProjectConfig, readProjectConfig, renderProjectConfig } from './project-config.js';
+import { assertSafePathSegment } from '../path-safety.js';
+import { exists } from '../storage/json-io.js';
+import { renderInitPlanDocument, renderInitSpecDocument, renderInitTasksDocument, renderInitVerifyDocument } from './starter-documents.js';
+
+export type InitDocumentStatus = 'created' | 'unchanged' | 'overwritten' | 'skipped';
+
+export interface InitDocumentReport {
+  branch: string;
+  relativePath: string;
+  status: InitDocumentStatus;
+  message: string;
+}
+
+export interface InitDocumentsResult {
+  branch: string;
+  root: string;
+  documents: InitDocumentReport[];
+}
+
+export interface InitProjectResult {
+  configPath: string;
+  created: boolean;
+  documents: InitDocumentsResult;
+  aiTools: AiProjectionResult[];
+}
+
+export async function applyInitDocuments(projectRoot: string, options: { branch: string; force?: boolean; scaffoldDocuments: boolean; docsLanguage: string }): Promise<InitDocumentsResult> {
+  assertSafePathSegment(options.branch, 'branch');
+  const docsRoot = path.join(projectRoot, 'specs', options.branch);
+  const now = new Date().toISOString();
+  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) }
+  ];
+
+  if (!options.scaffoldDocuments) {
+    return {
+      branch: options.branch,
+      root: path.relative(projectRoot, docsRoot),
+      documents: documents.map((document) => ({
+        branch: options.branch,
+        relativePath: `specs/${options.branch}/${document.name}`,
+        status: 'skipped',
+        message: 'Starter semantic document scaffold skipped.'
+      }))
+    };
+  }
+
+  await mkdir(docsRoot, { recursive: true });
+  const reports: InitDocumentReport[] = [];
+  for (const document of documents) {
+    const absolutePath = path.join(docsRoot, document.name);
+    const relativePath = `specs/${options.branch}/${document.name}`;
+    const existed = await exists(absolutePath);
+    if (existed && !options.force) {
+      reports.push({
+        branch: options.branch,
+        relativePath,
+        status: 'unchanged',
+        message: 'Existing semantic document preserved.'
+      });
+      continue;
+    }
+
+    await writeFile(absolutePath, document.content, 'utf8');
+    reports.push({
+      branch: options.branch,
+      relativePath,
+      status: existed ? 'overwritten' : 'created',
+      message: existed ? 'Starter semantic document overwritten by explicit force.' : 'Starter semantic document created.'
+    });
+  }
+
+  return { branch: options.branch, root: path.relative(projectRoot, docsRoot), documents: reports };
+}
+
+export async function initProject(projectRoot: string, options: { force?: boolean; aiTool?: AiToolSelection; branch?: string; scaffoldDocuments?: boolean } = {}): Promise<InitProjectResult> {
+  const sddDir = getSddDir(projectRoot);
+  const runsDir = getRunsDir(projectRoot);
+  const configPath = getProjectConfigPath(projectRoot);
+  const requestedBranch = options.branch?.trim();
+  const scaffoldDocuments = options.scaffoldDocuments ?? true;
+  const branch = requestedBranch || 'master';
+  assertSafePathSegment(branch, 'branch');
+  await mkdir(runsDir, { recursive: true });
+
+  let created = false;
+  let projectConfig = null;
+  if (options.force || !await exists(configPath)) {
+    const projectName = path.basename(path.resolve(projectRoot));
+    const config = await detectProjectConfig(projectRoot, projectName);
+    config.sdd.default_branch = requestedBranch || (scaffoldDocuments ? branch : undefined);
+    await writeFile(configPath, renderProjectConfig(config), 'utf8');
+    projectConfig = config;
+    created = true;
+  }
+
+  if (!projectConfig) {
+    projectConfig = await readProjectConfig(projectRoot);
+  }
+
+  const documents = await applyInitDocuments(projectRoot, {
+    branch,
+    force: options.force,
+    scaffoldDocuments,
+    docsLanguage: projectConfig.sdd.docs_language
+  });
+
+  await mkdir(sddDir, { recursive: true });
+  const aiTools = await applyAiToolEntries(projectRoot, { tool: options.aiTool ?? 'auto' });
+  return { configPath, created, documents, aiTools };
+}