sdd-agent-platform 0.2.0 → 0.4.0

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

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { CONTEXT_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
+import { branchToSafePartition, normalizePortablePath, safeBranchOrNull } from '../path-safety.js';
+import { getProjectConfigPath } from '../runtime-paths.js';
+import type { RunState } from '../run-state/model.js';
+import { parseProjectConfig } from '../config/project-config.js';
+
+const execFileAsync = promisify(execFile);
+
+export type ContextBranchSource = 'explicit_option' | 'cli_option' | 'project_config' | 'git_branch';
+
+export interface ContextResolverContract {
+  contract: typeof CONTEXT_RESOLVER_CONTRACT_VERSION;
+  branch: string;
+  partition: string;
+  rawBranch: string;
+  branchSource: ContextBranchSource;
+  currentGitBranch: string | null;
+  workingTreeMatched: boolean | null;
+  specDir: string;
+}
+
+export async function resolveSddContext(projectRoot: string, options: { branch?: string | null; branchSource?: ContextBranchSource } = {}): Promise<ContextResolverContract> {
+  const currentGitBranch = await getCurrentGitBranch(projectRoot);
+  const requestedBranch = options.branch?.trim();
+  if (requestedBranch) {
+    return resolvedContext(projectRoot, requestedBranch, options.branchSource ?? 'explicit_option', currentGitBranch);
+  }
+
+  if (currentGitBranch) {
+    return resolvedContext(projectRoot, currentGitBranch, 'git_branch', currentGitBranch);
+  }
+
+  const projectConfigBranch = await resolveProjectConfigBranch(projectRoot);
+  if (projectConfigBranch) {
+    return resolvedContext(projectRoot, projectConfigBranch, 'project_config', currentGitBranch);
+  }
+
+  throw new Error('Cannot resolve SDD branch. Run from a Git branch, pass --branch <branch>, or set sdd.default_branch in .sdd/project.yml. /sdd:spec is the workflow partition entry.');
+}
+
+export async function resolveRunStateContext(projectRoot: string, state: RunState): Promise<ContextResolverContract> {
+  if (!state.partition && !state.gitBranch) {
+    return resolveSddContext(projectRoot);
+  }
+
+  const currentGitBranch = await getCurrentGitBranch(projectRoot);
+  const partition = state.partition ?? branchToSafePartition(state.gitBranch ?? '');
+  const rawBranch = state.gitBranch ?? state.partition ?? partition;
+  return {
+    contract: CONTEXT_RESOLVER_CONTRACT_VERSION,
+    branch: partition,
+    partition,
+    rawBranch,
+    branchSource: 'explicit_option',
+    currentGitBranch,
+    workingTreeMatched: currentGitBranch ? currentGitBranch === rawBranch : null,
+    specDir: normalizePortablePath(path.relative(projectRoot, path.join(projectRoot, 'specs', partition)))
+  };
+}
+
+function resolvedContext(projectRoot: string, rawBranch: string, branchSource: ContextBranchSource, currentGitBranch: string | null): ContextResolverContract {
+  const partition = branchToSafePartition(rawBranch);
+  return {
+    contract: CONTEXT_RESOLVER_CONTRACT_VERSION,
+    branch: partition,
+    partition,
+    rawBranch,
+    branchSource,
+    currentGitBranch,
+    workingTreeMatched: currentGitBranch ? currentGitBranch === rawBranch : null,
+    specDir: normalizePortablePath(path.relative(projectRoot, path.join(projectRoot, 'specs', partition)))
+  };
+}
+
+async function resolveProjectConfigBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const configPath = getProjectConfigPath(projectRoot);
+    const raw = await readFile(configPath, 'utf8');
+    const config = parseProjectConfig(raw, configPath);
+    const defaultBranch = safeBranchOrNull(config.sdd.default_branch ?? '');
+    if (defaultBranch) {
+      return defaultBranch;
+    }
+
+    const specDir = normalizePortablePath(config.sdd.spec_dir);
+    if (specDir.includes('<branch>')) {
+      return null;
+    }
+    const parts = specDir.split('/');
+    if (parts.length === 2 && parts[0] === 'specs') {
+      return safeBranchOrNull(parts[1]);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function getCurrentGitBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const result = await execFileAsync('git', ['-C', projectRoot, 'branch', '--show-current']);
+    const branch = result.stdout.trim();
+    return branch.length > 0 ? branch : null;
+  } catch {
+    return null;
+  }
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/run-binding.ts

@@ -0,0 +1,86 @@
+import { appendEvent } from '../run-state/events.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import type { RunDocumentSnapshot, RunState } from '../run-state/model.js';
+import type { ContextResolverContract } from './context.js';
+import type { SddTask, SddTaskModel } from './task-parser.js';
+
+export async function bindRunStateToTask(projectRoot: string, state: RunState, context: ContextResolverContract, model: SddTaskModel, task: SddTask | null, taskId: string): Promise<RunState> {
+  if (state.partition && state.partition !== context.partition) {
+    throw new Error(`Run ${state.runId} belongs to partition ${state.partition}, not ${context.partition}.`);
+  }
+  if (state.taskId && state.taskId !== taskId) {
+    throw new Error(`Run ${state.runId} belongs to task ${state.taskId}, not ${taskId}.`);
+  }
+  if (state.gitBranch && state.gitBranch !== context.rawBranch) {
+    throw new Error(`Run ${state.runId} belongs to Git branch ${state.gitBranch}, not ${context.rawBranch}.`);
+  }
+
+  const nextState: RunState = {
+    ...state,
+    currentTask: taskId,
+    partition: context.partition,
+    gitBranch: context.rawBranch,
+    taskId,
+    affectedFiles: task?.affectedFiles ?? state.affectedFiles,
+    documentSnapshot: documentSnapshotFromModel(model)
+  };
+  await writeRunState(projectRoot, nextState);
+  await appendEvent(projectRoot, state.runId, {
+    event: 'run_context_bound',
+    runId: state.runId,
+    summary: `Run bound to ${context.partition}/${taskId}`,
+    data: {
+      partition: context.partition,
+      gitBranch: context.rawBranch,
+      task: taskId,
+      affectedFiles: nextState.affectedFiles,
+      documentSnapshot: nextState.documentSnapshot
+    }
+  });
+  return readRunState(projectRoot, state.runId);
+}
+
+export async function bindRunStateToTaskContext(projectRoot: string, state: RunState, context: ContextResolverContract, model: SddTaskModel, task: SddTask | null, taskId: string): Promise<RunState> {
+  if (!state.taskId || state.taskId === taskId) {
+    return bindRunStateToTask(projectRoot, state, context, model, task, taskId);
+  }
+  if (state.partition && state.partition !== context.partition) {
+    throw new Error(`Run ${state.runId} belongs to partition ${state.partition}, not ${context.partition}.`);
+  }
+  if (state.gitBranch && state.gitBranch !== context.rawBranch) {
+    throw new Error(`Run ${state.runId} belongs to Git branch ${state.gitBranch}, not ${context.rawBranch}.`);
+  }
+
+  const nextState: RunState = {
+    ...state,
+    currentTask: taskId,
+    partition: context.partition,
+    gitBranch: context.rawBranch,
+    affectedFiles: [...new Set([...state.affectedFiles, ...(task?.affectedFiles ?? [])])],
+    documentSnapshot: documentSnapshotFromModel(model)
+  };
+  await writeRunState(projectRoot, nextState);
+  await appendEvent(projectRoot, state.runId, {
+    event: 'run_context_bound',
+    runId: state.runId,
+    summary: `Run context updated for ${context.partition}/${taskId}`,
+    data: {
+      partition: context.partition,
+      gitBranch: context.rawBranch,
+      task: taskId,
+      affectedFiles: nextState.affectedFiles,
+      documentSnapshot: nextState.documentSnapshot
+    }
+  });
+  return readRunState(projectRoot, state.runId);
+}
+
+export function documentSnapshotFromModel(model: SddTaskModel): RunDocumentSnapshot {
+  return {
+    specHash: model.documents.specHash ?? null,
+    planHash: model.documents.planHash ?? null,
+    tasksHash: model.documents.tasksHash ?? null,
+    planBasedOnSpecHash: model.documents.planBasedOnSpecHash ?? null,
+    tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/task-inspection.ts

@@ -0,0 +1,39 @@
+import type { SddTask, SddTaskGap, SddTaskModel } from './task-parser.js';
+
+export function inspectSddTask(model: SddTaskModel, taskId: string): { task: SddTask | null; gaps: SddTaskGap[] } {
+  const matchingTasks = model.tasks.filter((candidate) => candidate.id === taskId);
+  if (matchingTasks.length > 1) {
+    return {
+      task: null,
+      gaps: [
+        ...model.gaps.filter((gap) => gap.taskId === taskId),
+        taskGap(
+          taskId,
+          'id',
+          `Task id ${taskId} is ambiguous; ${matchingTasks.length} tasks share this id: ${matchingTasks.map(taskSourceEvidence).join('; ')}.`,
+          'Inspect by a unique task id, or rename duplicate task ids before implementation.'
+        )
+      ]
+    };
+  }
+  const task = matchingTasks[0] ?? null;
+  return {
+    task,
+    gaps: model.gaps.filter((gap) => gap.taskId === taskId || (task === null && gap.taskId === null))
+  };
+}
+
+export function taskGap(taskId: string, field: string, message: string, recommendation: string): SddTaskGap {
+  return {
+    type: 'Task Gap',
+    severity: 'blocking',
+    taskId,
+    field,
+    message,
+    recommendation
+  };
+}
+
+function taskSourceEvidence(task: Pick<SddTask, 'id' | 'source'>): string {
+  return `${task.id} at ${task.source.filePath}:${task.source.lineStart}-${task.source.lineEnd}`;
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/task-parser.test.ts

@@ -0,0 +1,262 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { validTaskMarkdown } from '../test-support/fixtures.js';
+import { inspectSddTask } from './task-inspection.js';
+import { parseSddBranch, parseSddTasksMarkdown } from './task-parser.js';
+import { renderTaskGapReport } from './task-rendering.js';
+
+test('parseSddTasksMarkdown extracts task metadata and companion sections', () => {
+  const markdown = `# Tasks
+
+### T1: Parser foundation
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - packages/core/src/index.ts
+validation:
+  - npm test => AC-1, AC-2
+risk:
+  - parser boundary
+\`\`\`
+
+#### Boundary
+
+Only parse Markdown metadata; do not execute tasks.
+
+#### Acceptance
+
+- Task metadata is structured.
+- Boundary is retained.
+
+#### Implementation Notes
+
+None yet.
+`;
+  const model = parseSddTasksMarkdown(markdown, { tasksPath: 'specs/master/tasks.md' });
+
+  assert.equal(model.gaps.length, 0);
+  assert.equal(model.tasks.length, 1);
+  assert.equal(model.tasks[0].id, 'T1');
+  assert.equal(model.tasks[0].status, 'pending');
+  assert.equal(model.tasks[0].wave, 1);
+  assert.deepEqual(model.tasks[0].dependsOn, []);
+  assert.deepEqual(model.tasks[0].affectedFiles, ['packages/core/src/index.ts']);
+  assert.deepEqual(model.tasks[0].validation, ['npm test']);
+  assert.deepEqual(model.tasks[0].validationCommands, [{ command: 'npm test', acceptanceRefs: ['AC-1', 'AC-2'], raw: 'npm test => AC-1, AC-2' }]);
+  assert.deepEqual(model.tasks[0].risk, ['parser boundary']);
+  assert.match(model.tasks[0].boundary ?? '', /Only parse Markdown metadata/);
+  assert.deepEqual(model.tasks[0].acceptance, ['Task metadata is structured.', 'Boundary is retained.']);
+});
+
+test('parseSddTasksMarkdown does not leak companion sections across indented task headings', () => {
+  const markdown = `# Tasks
+
+  ### ERP-SCRK-1: 固化入库同步状态机边界
+
+\`\`\`sdd-task
+id: ERP-SCRK-1
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - src/main/java/com/acme/erp/InboundSyncService.java
+validation:
+  - mvn test -Dtest=InboundSyncServiceTest
+risk:
+  - state-machine
+\`\`\`
+
+#### Boundary
+
+Only state-machine logic.
+
+#### Acceptance
+
+- Terminal states never roll back.
+
+  ### ERP-SCRK-2: 移除 Mapper SQL 拼接
+
+\`\`\`sdd-task
+id: ERP-SCRK-2
+status: pending
+wave: 2
+depends_on:
+  - ERP-SCRK-1
+affected_files:
+  - src/main/java/com/acme/erp/InboundSyncMapper.java
+validation:
+  - mvn test
+risk:
+  - sql
+\`\`\`
+
+#### Boundary
+
+Only mapper SQL parameterization.
+
+#### Acceptance
+
+- Mapper has no SQL string concatenation.
+`;
+  const model = parseSddTasksMarkdown(markdown, { tasksPath: 'specs/master/tasks.md' });
+
+  assert.equal(model.gaps.length, 0);
+  assert.equal(model.tasks.length, 2);
+  assert.deepEqual(model.tasks[0].acceptance, ['Terminal states never roll back.']);
+  assert.deepEqual(model.tasks[1].acceptance, ['Mapper has no SQL string concatenation.']);
+  assert.doesNotMatch(model.tasks[0].boundary ?? '', /Mapper SQL/);
+});
+
+test('parseSddTasksMarkdown reports task metadata and dependency gaps', () => {
+  const markdown = `# Tasks
+
+### T2: Gap case
+
+\`\`\`sdd-task
+id: T2
+status: surprise
+depends_on:
+  - T404
+affected_files: []
+validation: []
+risk: []
+\`\`\`
+`;
+  const model = parseSddTasksMarkdown(markdown);
+  const fields = model.gaps.map((gap) => gap.field);
+
+  assert.equal(model.tasks.length, 1);
+  assert.equal(model.gaps.every((gap) => gap.severity === 'blocking'), true);
+  assert.equal(fields.includes('status'), true);
+  assert.equal(fields.includes('wave'), true);
+  assert.equal(fields.includes('affected_files'), true);
+  assert.equal(fields.includes('validation'), true);
+  assert.equal(fields.includes('Boundary'), true);
+  assert.equal(fields.includes('Acceptance'), true);
+  assert.equal(fields.includes('depends_on'), true);
+  assert.match(renderTaskGapReport({
+    branch: 'master',
+    specPath: 'spec.md',
+    planPath: 'plan.md',
+    tasksPath: 'tasks.md',
+    verifyPath: 'verify.md',
+    documents: { specExists: true, planExists: true, tasksExists: true, verifyExists: true },
+    tasks: model.tasks,
+    gaps: model.gaps
+  }), /BLOCKED/);
+});
+
+test('parseSddBranch reads branch docs and inspectSddTask filters gaps', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-parser-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n', 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), '# Plan\n', 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), `# Tasks
+
+### T1: Valid task
+
+\`\`\`sdd-task
+id: T1
+status: pending
+wave: 1
+depends_on: []
+affected_files:
+  - a.ts
+validation:
+  - npm test
+risk: []
+\`\`\`
+
+#### Boundary
+
+Stay in a.ts.
+
+#### Acceptance
+
+- a.ts behavior is covered.
+`, 'utf8');
+
+    const model = await parseSddBranch(root, 'feature');
+    const inspected = inspectSddTask(model, 'T1');
+
+    assert.equal(model.documents.specExists, true);
+    assert.equal(model.documents.planExists, true);
+    assert.equal(model.documents.tasksExists, true);
+    assert.equal(model.gaps.length, 0);
+    assert.equal(inspected.task?.id, 'T1');
+    assert.equal(inspected.gaps.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('retained phase fallback detects aggregate duplicate task ids and inspect ambiguity', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-duplicate-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n', 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), '# Plan\n', 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), '# Tasks\nLegacy index only.\n', 'utf8');
+    await writeFile(path.join(branchDir, 'phase1.0-tasks.md'), validTaskMarkdown('T1', []), 'utf8');
+    await writeFile(path.join(branchDir, 'phase1.1-tasks.md'), validTaskMarkdown('T1', []), 'utf8');
+
+    const model = await parseSddBranch(root, 'feature');
+    const inspected = inspectSddTask(model, 'T1');
+
+    assert.equal(model.tasks.length, 2);
+    assert.equal(model.gaps.some((gap) => gap.field === 'id' && gap.taskId === 'T1' && /Duplicate task id T1 across parsed task files/.test(gap.message)), true);
+    assert.equal(inspected.task, null);
+    assert.equal(inspected.gaps.some((gap) => /ambiguous/.test(gap.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('retained phase fallback validates cross-file dependencies over aggregate tasks', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-cross-deps-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n', 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), '# Plan\n', 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), '# Tasks\nLegacy index only.\n', 'utf8');
+    await writeFile(path.join(branchDir, 'phase1.0-tasks.md'), validTaskMarkdown('P1.0-T1', []), 'utf8');
+    await writeFile(path.join(branchDir, 'phase1.1-tasks.md'), validTaskMarkdown('P1.1-T1', ['P1.0-T1']), 'utf8');
+
+    const model = await parseSddBranch(root, 'feature');
+
+    assert.equal(model.tasks.length, 2);
+    assert.equal(model.gaps.length, 0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('retained phase fallback still reports unknown dependencies', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-unknown-deps-'));
+  try {
+    const branchDir = path.join(root, 'specs', 'feature');
+    await mkdir(branchDir, { recursive: true });
+    await writeFile(path.join(branchDir, 'spec.md'), '# Spec\n', 'utf8');
+    await writeFile(path.join(branchDir, 'plan.md'), '# Plan\n', 'utf8');
+    await writeFile(path.join(branchDir, 'tasks.md'), '# Tasks\nLegacy index only.\n', 'utf8');
+    await writeFile(path.join(branchDir, 'phase1.0-tasks.md'), validTaskMarkdown('P1.0-T1', ['P9.9-T404']), 'utf8');
+
+    const model = await parseSddBranch(root, 'feature');
+
+    assert.equal(model.gaps.some((gap) => gap.type === 'Dependency Gap' && gap.taskId === 'P1.0-T1' && /unknown task P9.9-T404/.test(gap.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});