sdd-agent-platform 0.4.1 → 0.5.0

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

@@ -0,0 +1,207 @@
+export type ArtifactDepthStage = 'spec' | 'plan' | 'tasks';
+export type ArtifactDepthIssueSeverity = 'blocker' | 'warning' | 'advisory';
+
+export interface ArtifactDepthIssue {
+  stage: ArtifactDepthStage;
+  severity: ArtifactDepthIssueSeverity;
+  code: string;
+  message: string;
+  repair: string;
+}
+
+export function evaluateSpecArtifactDepth(content: string): ArtifactDepthIssue[] {
+  const problem = extractMarkdownSection(content, 'Problem Reframing / Intent Discovery') ?? '';
+  const requirements = extractMarkdownSection(content, 'Requirements') ?? '';
+  const acceptance = extractMarkdownSection(content, 'Acceptance Criteria / Evidence Targets') ?? '';
+  const definitions = extractMarkdownSection(content, 'Definitions / Rules') ?? '';
+  const ambiguity = extractMarkdownSection(content, 'Open Questions / Ambiguity Ledger') ?? '';
+  const closeEvidence = extractMarkdownSection(content, 'Close Quality Evidence') ?? '';
+  const issues: ArtifactDepthIssue[] = [];
+
+  if (!/surface request/i.test(problem) || !/reframed problem/i.test(problem) || !/inferred real intent|real intent/i.test(problem)) {
+    issues.push(issue('spec', 'spec.too_thin.problem_reframing_missing', 'spec lacks problem reframing depth', 'Rewrite Problem Reframing / Intent Discovery with surface request, reframed problem, inferred intent, and observable success.', 'advisory'));
+  }
+  if (!/\bREQ-\d+\b/i.test(requirements) || !/reasoning|basis|source|constraint|because|why|rule|invariant|domain/i.test(`${requirements}\n${definitions}`)) {
+    issues.push(issue('spec', 'spec.too_thin.domain_rules_missing', 'spec requirements are not tied to domain rules or scope boundaries', 'Add requirement reasoning, source basis, domain rules, invariants, and scope boundaries before plan.', 'advisory'));
+  }
+  if (!/\bAC-\d+\b/i.test(acceptance) || !/evidence target/i.test(acceptance) || !/REQ-\d+/i.test(acceptance)) {
+    issues.push(issue('spec', 'spec.too_thin.acceptance_evidence_missing', 'spec acceptance criteria lack evidence targets tied to requirements', 'Add evidence targets for each core acceptance criterion and map them to requirement IDs.', 'warning'));
+  }
+  if (!/blocking user decisions?|blocking before plan|no blocking/i.test(ambiguity) || !/researchable|resolved by scout|scout|safe assumptions?|assumptions?|deferred/i.test(ambiguity)) {
+    issues.push(issue('spec', 'spec.ambiguity.unrouted', 'spec ambiguity is not explicitly routed', 'Classify uncertainty into researchable gaps, blocking user decisions, assumptions, and deferred items.', 'warning'));
+  }
+  if (closeEvidence && !/downstream_business_guesswork_remaining\s*:\s*\[\s*\]/i.test(closeEvidence)) {
+    issues.push(issue('spec', 'spec.downstream_guesswork.plan_would_rediscover_requirements', 'spec leaves downstream business guesswork for plan', 'Either resolve business guesswork in spec or route it as a blocking user decision before close.', 'blocker'));
+  }
+  return issues;
+}
+
+export function evaluatePlanArtifactDepth(content: string): ArtifactDepthIssue[] {
+  const implementationMap = extractMarkdownSection(content, 'Current Implementation Map') ?? '';
+  const interfaceDesign = extractMarkdownSection(content, 'Interface / API / Schema Design') ?? '';
+  const stateDesign = extractMarkdownSection(content, 'State / Data / Concurrency Design') ?? '';
+  const validationStrategy = extractMarkdownSection(content, 'Validation Strategy') ?? '';
+  const riskControls = extractMarkdownSection(content, 'Risk Controls') ?? '';
+  const closeEvidence = extractMarkdownSection(content, 'Plan Close Quality Evidence') ?? '';
+  const issues: ArtifactDepthIssue[] = [];
+
+  if (!hasConcreteImplementationSurface(implementationMap)) {
+    issues.push(issue('plan', 'plan.too_thin.current_implementation_facts_not_reasoned', 'plan lacks reasoned current implementation facts', 'Connect observed files/classes/data facts to design implications, ownership, reuse/change/do-not-reuse decisions, or scout gaps.', 'advisory'));
+  }
+  if (!hasApiShape(interfaceDesign)) {
+    issues.push(issue('plan', 'plan.too_thin.api_shape_not_decided', 'plan API/interface shape is undecided', 'Specify request/query fields, response DTO/VO shape, error behavior, pagination, and owner surface where applicable.', 'warning'));
+  }
+  if (!hasSqlOrDataMappingDepth(interfaceDesign, stateDesign)) {
+    issues.push(issue('plan', 'plan.too_thin.sql_mapping_missing_join_keys', 'plan SQL/data mapping lacks executable depth', 'Name source fields, join keys, grouping/distinct rules, mapper ownership, date/status filters, or justify non-applicability.', 'warning'));
+  }
+  if (!hasScenarioValidationMatrix(validationStrategy, riskControls)) {
+    issues.push(issue('plan', 'plan.too_thin.validation_not_scenario_level', 'plan validation is not scenario-level', 'Add scenario rows with input/user action, expected API/UI/SQL result, evidence command/manual check, proves, and does-not-prove.', 'warning'));
+  }
+  if (looksDenseButShallow(implementationMap, interfaceDesign, riskControls)) {
+    issues.push(issue('plan', 'plan.dense_but_shallow.code_facts_not_connected_to_decisions', 'plan is dense but code/data facts are not connected to decisions', 'For each important fact, state the design implication, selected decision, rejected alternative, and risk control.', 'warning'));
+  }
+  if (leaksDesignDecisionToImplementation(interfaceDesign, stateDesign)) {
+    issues.push(issue('plan', 'plan.downstream_guesswork.tasks_or_execute_would_redesign', 'plan leaks design decisions to implementation', 'Resolve API/SQL/data decisions in plan before tasks or execute consume the design.', 'blocker'));
+  }
+  if (closeEvidence && !/downstream_design_guesswork_remaining\s*:\s*\[\s*\]/i.test(closeEvidence)) {
+    issues.push(issue('plan', 'plan.downstream_guesswork.tasks_or_execute_would_redesign', 'plan leaves design guesswork for tasks or execute', 'Resolve or explicitly route design guesswork before tasks consume the plan.', 'blocker'));
+  }
+  return issues;
+}
+
+export function evaluateTasksArtifactDepth(content: string): ArtifactDepthIssue[] {
+  const splitBasis = extractMarkdownSection(content, ['Split Basis', 'Task Split Basis', 'Work Unit Split Basis']) ?? '';
+  const implementationTasks = extractMarkdownSection(content, ['Implementation Tasks', 'Implementation Work Units', 'Implementation Task Units']) ?? '';
+  const validationTasks = extractMarkdownSection(content, ['Validation Tasks', 'Validation Work Units', 'Validation Task Units']) ?? '';
+  const dependencies = extractMarkdownSection(content, ['Task Dependencies and Handoff', 'Dependencies and Validation Handoff', 'Task Dependency and Validation Handoff']) ?? '';
+  const openQuestions = extractMarkdownSection(content, ['Open Execution Questions', 'Open Questions', 'Execution Questions']) ?? '';
+  const closeEvidence = extractMarkdownSection(content, ['Tasks Close Quality Evidence', 'Close Quality Evidence']) ?? '';
+  const issues: ArtifactDepthIssue[] = [];
+
+  if (!/why this task exists|work-unit context|plan decision|design part|must not reinterpret|risk/i.test(implementationTasks)) {
+    issues.push(issue('tasks', 'tasks.too_thin.work_unit_context_missing', 'implementation tasks lack work-unit context', 'Explain which plan decision each task implements, why the boundary exists, and what execute must not reinterpret.', 'warning'));
+  }
+  if (!/validationHandoff\s*:/i.test(implementationTasks)) {
+    issues.push(issue('tasks', 'tasks.parser.missing_validation_handoff', 'implementation tasks lack validation handoff metadata', 'Add validationHandoff metadata from each implementation task to later validation task IDs.', 'blocker'));
+  }
+  if (!/validatesImplementationTasks\s*:/i.test(validationTasks) && !/validates_implementation_tasks\s*:/i.test(validationTasks)) {
+    issues.push(issue('tasks', 'tasks.parser.missing_validates_implementation_tasks', 'validation tasks lack implementation task refs', 'Add validatesImplementationTasks metadata to each validation task.', 'blocker'));
+  }
+  if (!/expected result|pass criteria|evidence is enough|does not prove|acceptance checks|manual inspection|test/i.test(validationTasks)) {
+    issues.push(issue('tasks', 'tasks.validation.expected_result_missing', 'validation tasks lack expected results', 'Add expected result, sufficient evidence, and does-not-prove notes for validation tasks.', 'warning'));
+  }
+  if (!/failure routing|failure route|return to|plan repair|spec\/user decision|environment diagnostic|tasks repair/i.test(`${validationTasks}\n${openQuestions}`)) {
+    issues.push(issue('tasks', 'tasks.failure_route.missing', 'tasks lack failure routes', 'Add failure routes to implementation task, tasks repair, plan repair, spec/user decision, or environment diagnostic.', 'blocker'));
+  }
+  if (isOversizedExecutionSlice(implementationTasks) && !hasExecutionSliceDecision(`${splitBasis}\n${implementationTasks}\n${dependencies}`)) {
+    issues.push(issue('tasks', 'tasks.review.split_adjudication_missing', 'tasks contain a broad execution slice without recorded tasks-stage split adjudication', 'Have task-reviewer flag the slice and tasks-manager either split it or record why the rollback unit stays together with an internal execution order before close.', 'warning'));
+  }
+  if (/rollback unit/i.test(implementationTasks) && /parallel/i.test(dependencies) && !/rollback boundary|reverted together|shared rollback|separate rollback|rollback units? stay separate|rollback-separated/i.test(dependencies)) {
+    issues.push(issue('tasks', 'tasks.boundary.rollback_unit_torn', 'tasks parallelism may tear rollback units', 'Explain rollback boundaries and why parallel tasks do not modify the same rollback unit unsafely.', 'blocker'));
+  }
+  if (/execute (?:will|should|must) decide|decide in execute|tbd in execute|implementation will determine|finalize during execute|确定|待实现时确定/i.test(`${implementationTasks}\n${openQuestions}`)) {
+    issues.push(issue('tasks', 'tasks.plan_repair.design_guesswork_leaked_to_execute', 'tasks leak design guesswork into execute', 'Route unresolved SQL/API/data design decisions back to plan before execute.', 'blocker'));
+  }
+  if (closeEvidence && !/downstream_execution_guesswork_remaining\s*:\s*\[\s*\]/i.test(closeEvidence)) {
+    issues.push(issue('tasks', 'tasks.plan_repair.design_guesswork_leaked_to_execute', 'tasks leave execution guesswork unresolved', 'Resolve execution guesswork in tasks or route it to tasks/plan/spec repair before close.', 'blocker'));
+  }
+  return issues;
+}
+
+export function formatArtifactDepthIssues(issues: ArtifactDepthIssue[]): string[] {
+  return issues.map((item) => `${item.severity}:${item.code}: ${item.message}. ${item.repair}`);
+}
+
+export function formatArtifactDepthBlockingIssues(issues: ArtifactDepthIssue[]): string[] {
+  return formatArtifactDepthIssues(issues.filter((item) => item.severity === 'blocker'));
+}
+
+function issue(stage: ArtifactDepthStage, code: string, message: string, repair: string, severity: ArtifactDepthIssueSeverity = 'warning'): ArtifactDepthIssue {
+  return { stage, severity, code, message, repair };
+}
+
+function hasConcreteImplementationSurface(section: string): boolean {
+  if (/scout gap|needs scout|unresolved gap|not applicable|no existing surface/i.test(section)) {
+    return true;
+  }
+  const namedSurfaces = section.match(/\b[A-Z][A-Za-z0-9_]*(?:Controller|Service|ServiceImpl|Mapper|Repository|Entity|DTO|VO|Request|Response|Component|Page|Config|Test)\b/g) ?? [];
+  const fileRefs = section.match(/`[^`]+\.(?:ts|tsx|js|jsx|java|kt|go|py|rs|xml|sql|jsp|vue|md)`/g) ?? [];
+  return namedSurfaces.length + fileRefs.length >= 2 && /reuse|change|do-not-reuse|do not reuse|owner|ownership|convention|boundary|surface|implication|decision|because|therefore/i.test(section);
+}
+
+function hasApiShape(section: string): boolean {
+  if (/not applicable|no interface|no api|no schema/i.test(section) && /because|checked|reason/i.test(section)) {
+    return true;
+  }
+  if (/TypeScript function contract|runtime-store projection schema|projection schema|function contract/i.test(section) && /field|schema|ref|hash|status|owner/i.test(section)) {
+    return true;
+  }
+  return /\b(query|request|response|DTO|VO|endpoint|controller|service|mapper|分页|权限|错误|响应包装)\b/i.test(section)
+    && /\b(field|default|required|optional|error|pagination|shape|字段|参数|返回|错误|分页)\b/i.test(section)
+    && (section.match(/`[^`]+`/g) ?? []).length >= 4;
+}
+
+function hasSqlOrDataMappingDepth(interfaceDesign: string, stateDesign: string): boolean {
+  const combined = `${interfaceDesign}\n${stateDesign}`;
+  if (/not applicable|no sql|no database|no data mapping/i.test(combined) && /because|checked|reason/i.test(combined)) {
+    return true;
+  }
+  if (/runtime-store projection schema|projection state|projection persistence|runtime projection/i.test(combined) && /ref|hash|scopeKey|projectionType|status|rollback/i.test(combined)) {
+    return true;
+  }
+  const requiresSqlDepth = /\b(SQL|MyBatis|mapper XML|database|table|column|join|aggregate|distinct|source field|表|字段|聚合|分组|去重)\b/i.test(combined);
+  if (!requiresSqlDepth) {
+    return true;
+  }
+  return /\b(join key|join keys|foreign key|primary key|source field|mapper owner|grouping|distinct|pagination|filter|status filter|date range|关联键|主键|外键|来源字段|分组|去重|分页|过滤)\b/i.test(combined)
+    && (combined.match(/`[^`]+`/g) ?? []).length >= 5;
+}
+
+function hasScenarioValidationMatrix(validationStrategy: string, riskControls: string): boolean {
+  const combined = `${validationStrategy}\n${riskControls}`;
+  const hasScenario = /scenario|input data|user action|expected|proves|does not prove|场景|输入|预期|证明/i.test(combined);
+  const hasEvidence = /command|evidence|manual|test|api|ui|sql|hook|artifact|证据|检查/i.test(combined);
+  const hasRiskLink = /risk|impact|control|validation hook|task-stage constraint|风险|影响|控制/i.test(combined);
+  return hasScenario && hasEvidence && hasRiskLink;
+}
+
+function looksDenseButShallow(...sections: string[]): boolean {
+  const text = sections.join('\n');
+  const lineCount = text.split(/\r?\n/).filter((line) => line.trim().length > 0).length;
+  const factCount = (text.match(/`[^`]+`|\b[A-Z][A-Za-z0-9_]*(?:Controller|Service|Mapper|Entity|DTO|VO|Request|Response)\b/g) ?? []).length;
+  const reasoningCount = (text.match(/because|therefore|implies|decision|tradeoff|risk control|validation hook|why|so that|因此|所以|取舍|决策|风险控制/g) ?? []).length;
+  return lineCount >= 12 && factCount >= 8 && reasoningCount < 3;
+}
+
+function leaksDesignDecisionToImplementation(...sections: string[]): boolean {
+  return /implementation will determine|finali[sz](?:e|ed) during implementation|decide in implementation|implementation phase will decide|execute (?:will|should|must) decide|decide in execute|tbd in execute|待实现时确定|执行时确定/i.test(sections.join('\n'));
+}
+
+function isOversizedExecutionSlice(section: string): boolean {
+  const codeBlocks = (section.match(/```sdd-task/g) ?? []).length;
+  const touchedAreas = (section.match(/affectedAreas\s*:|affected_files\s*:|Allowed code changes|Allowed files|Controller|Service|Mapper|DTO|VO|XML|SQL|UI|JSP|Vue|React/gi) ?? []).length;
+  return codeBlocks <= 2 && touchedAreas >= 8;
+}
+
+function hasExecutionSliceDecision(section: string): boolean {
+  return /execution slice|split rationale|split chain|split from|work-unit boundary|keep together|single rollback unit|sequence|internal order|ordered steps|step order|rollback unit|rollback boundary|tasks-manager|task manager|reviewed split|split decision|裁决|不拆分|保留|内部顺序|执行顺序|回滚单元/i.test(section);
+}
+
+function extractMarkdownSection(content: string, section: string | string[]): string | null {
+  for (const sectionName of Array.isArray(section) ? section : [section]) {
+    const escaped = escapeRegex(sectionName).replace(/\s+/g, '\\s+');
+    const match = new RegExp(`^##\\s+(?:\\d+(?:\\.\\d+)*\\.?\\s+)?${escaped}\\s*$`, 'im').exec(content);
+    if (!match) {
+      continue;
+    }
+    const start = match.index + match[0].length;
+    const rest = content.slice(start);
+    const next = /^##\s+/im.exec(rest);
+    return (next ? rest.slice(0, next.index) : rest).trim();
+  }
+  return null;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

@@ -1,111 +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. The spec stage 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;
-  }
-}
+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. The spec stage 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;
+  }
+}