sdd-agent-platform 0.4.2 → 0.5.1

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

@@ -0,0 +1,380 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { evaluatePlanArtifactDepth, evaluateSpecArtifactDepth, evaluateTasksArtifactDepth, formatArtifactDepthBlockingIssues } from './artifact-depth.js';
+
+test('spec artifact depth reports missing evidence targets and unrouted ambiguity', () => {
+  const issues = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Thin Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request: change the report. Reframed problem: clarify the reporting contract. Inferred real intent: reduce downstream ambiguity.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add the report. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Priority |
+|---|---|---|---|
+| AC-1 | It works. | REQ-1 | Must |
+
+## Definitions / Rules
+
+Domain rule: reporting scope is branch-local.
+
+## Open Questions / Ambiguity Ledger
+
+None.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'spec.ambiguity.unrouted',
+    'spec.too_thin.acceptance_evidence_missing'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['spec.ambiguity.unrouted', 'warning'],
+    ['spec.too_thin.acceptance_evidence_missing', 'warning']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('plan artifact depth treats implementation-decided API and SQL as blocker', () => {
+  const issues = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Thin Plan
+
+## Current Implementation Map
+
+Observed \`ReportController\` and \`ReportMapper.xml\`; therefore the design must reuse existing controller ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+The API and SQL will be finalized during implementation. It uses SQL table joins and source fields.
+
+## State / Data / Concurrency Design
+
+The database query reads report tables and aggregates rows.
+
+## Risk Controls
+
+Risk: wrong aggregation. Control: validation hook in scenario tests.
+
+## Validation Strategy
+
+Scenario: query report. Input data: seeded rows. Expected SQL result: exact grouped rows. Command / evidence: integration test. Proves aggregation. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'plan.downstream_guesswork.tasks_or_execute_would_redesign',
+    'plan.too_thin.api_shape_not_decided',
+    'plan.too_thin.sql_mapping_missing_join_keys'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['plan.downstream_guesswork.tasks_or_execute_would_redesign', 'blocker'],
+    ['plan.too_thin.api_shape_not_decided', 'warning'],
+    ['plan.too_thin.sql_mapping_missing_join_keys', 'warning']
+  ]);
+  assert.equal(formatArtifactDepthBlockingIssues(issues).length, 1);
+});
+
+test('plan artifact depth keeps thin but decided mapping as warning-only diagnostics', () => {
+  const issues = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Warning Plan
+
+## Current Implementation Map
+
+Observed 'ReportController' and 'ReportMapper.xml'; therefore the design reuses existing controller ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+The endpoint returns report rows from the existing mapper. SQL uses report joins and source fields selected by the accepted plan.
+
+## State / Data / Concurrency Design
+
+The database query reads report tables and aggregates rows.
+
+## Risk Controls
+
+Risk: wrong aggregation. Control: validation hook in scenario tests.
+
+## Validation Strategy
+
+Scenario: query report. Input data: seeded rows. Expected SQL result: exact grouped rows. Command / evidence: integration test. Proves aggregation. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['plan.too_thin.api_shape_not_decided', 'warning'],
+    ['plan.too_thin.sql_mapping_missing_join_keys', 'warning']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('tasks artifact depth reports missing failure route and leaked execute guesswork', () => {
+  const issues = evaluateTasksArtifactDepth(`---
+contract: sdd-tasks-doc-v2
+---
+
+# Thin Tasks
+
+## Split Basis
+
+Split from plan decisions into implementation and validation tasks.
+
+## Implementation Tasks
+
+### T1 — Implement report
+
+Why this task exists: implements PLAN-1 and execute must not reinterpret scope.
+
+Implementation will determine the final SQL join and response fields.
+
+\`\`\`sdd-task
+id: T1
+status: pending
+taskClass: implementation
+unitType: core
+wave: 1
+validationHandoff:
+  - T2
+\`\`\`
+
+## Validation Tasks
+
+### T2 — Validate report
+
+Expected result: report rows match the accepted plan.
+
+\`\`\`sdd-task
+id: T2
+status: pending
+taskClass: validation
+unitType: validation
+wave: 2
+validatesImplementationTasks:
+  - T1
+\`\`\`
+
+## Task Dependencies and Handoff
+
+T2 depends on T1.
+
+## Open Execution Questions
+
+None.
+
+## Tasks Close Quality Evidence
+
+- downstream_execution_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'tasks.failure_route.missing',
+    'tasks.plan_repair.design_guesswork_leaked_to_execute'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['tasks.failure_route.missing', 'blocker'],
+    ['tasks.plan_repair.design_guesswork_leaked_to_execute', 'blocker']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues).map((item) => item.replace(/:.*/, '')), ['blocker', 'blocker']);
+});
+
+test('tasks artifact depth accepts oversized slice when tasks-manager records keep-together decision', () => {
+  const issues = evaluateTasksArtifactDepth(`---
+contract: sdd-tasks-doc-v2
+---
+
+# Reviewed Tasks
+
+## Split Basis
+
+Tasks-manager reviewed the split decision: keep together as one backend/runtime rollback unit because Controller, Service, Mapper, DTO, VO, XML, and SQL must be reverted together. Internal order: controller route, service read model, mapper XML, SQL filters, DTO/VO wiring.
+
+## Implementation Tasks
+
+### T1 — Implement report read model
+
+Why this task exists: implements PLAN-1. Work-unit context: the backend/runtime rollback unit must stay together. Plan decision: preserve existing controller ownership. Risk: execute must not reinterpret SQL ownership.
+
+Change Controller, Service, Mapper, DTO, VO, mapper XML, SQL, JSP, and UI configuration in one task. Affected surfaces: ReportController, ReportService, ReportMapper, ReportDTO, ReportVO, mapper XML, permission SQL, JSP, and UI route.
+
+\`\`\`sdd-task
+id: T1
+status: pending
+taskClass: implementation
+unitType: core
+wave: 1
+validationHandoff:
+  - T2
+\`\`\`
+
+## Validation Tasks
+
+### T2 — Validate report read model
+
+Expected result: report rows match the accepted plan. Evidence is enough when SQL/API review proves the read model; does not prove release readiness.
+
+\`\`\`sdd-task
+id: T2
+status: pending
+taskClass: validation
+unitType: validation
+wave: 2
+validatesImplementationTasks:
+  - T1
+\`\`\`
+
+## Task Dependencies and Handoff
+
+T2 depends on T1.
+
+## Open Execution Questions
+
+No blocking execution questions. Failure route: tasks repair, plan repair, spec/user decision, or environment diagnostic.
+
+## Tasks Close Quality Evidence
+
+- downstream_execution_guesswork_remaining: []
+`);
+
+  assert.equal(issues.some((issue) => issue.code === 'tasks.review.split_adjudication_missing'), false);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('artifact depth keeps advisory and warning diagnostics out of blocking formatter', () => {
+  const specIssues = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Advisory Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request only.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add the report because the branch scope requires it. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Evidence Target |
+|---|---|---|---|
+| AC-1 | Report returns branch-local rows. | REQ-1 | API test evidence target. |
+
+## Definitions / Rules
+
+Domain rule: branch-local report scope is invariant.
+
+## Open Questions / Ambiguity Ledger
+
+No blocking user decisions. Researchable gaps: none. Safe assumptions: none. Deferred: none.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: []
+`);
+
+  assert.deepEqual(specIssues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['spec.too_thin.problem_reframing_missing', 'advisory']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(specIssues), []);
+});
+
+test('artifact depth treats explicit downstream guesswork as blocker across stages', () => {
+  const specBlockers = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Blocked Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request: change report. Reframed problem: clarify report semantics. Inferred real intent: avoid ambiguity.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add report because branch scope requires it. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Evidence Target |
+|---|---|---|---|
+| AC-1 | Report returns branch-local rows. | REQ-1 | API evidence target. |
+
+## Definitions / Rules
+
+Domain rule: branch-local report scope is invariant.
+
+## Open Questions / Ambiguity Ledger
+
+No blocking user decisions. Researchable gaps: none. Safe assumptions: none. Deferred: none.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: [\"report ownership undecided\"]
+`);
+  const planBlockers = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Blocked Plan
+
+## Current Implementation Map
+
+Observed 'ReportController' and 'ReportMapper.xml'; therefore the design reuses existing ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+Request field 'branchId'; response DTO 'ReportRowVO'; mapper field 'report.branch_id'; status field 'report.status'. No SQL table ownership changes.
+
+## State / Data / Concurrency Design
+
+Runtime reads 'report.branch_id', 'report.status', 'report.created_at', 'report.asset_id', and 'report.amount'; rollback is not applicable because this is read-only.
+
+## Risk Controls
+
+Risk: wrong branch filter. Control: scenario validation checks SQL evidence.
+
+## Validation Strategy
+
+Scenario: query report. Input data: branch rows. Expected SQL result: exact rows. Command evidence: integration test. Proves branch filter. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: [\"SQL grouping undecided\"]
+`);
+
+  assert.equal(specBlockers.find((issue) => issue.code === 'spec.downstream_guesswork.plan_would_rediscover_requirements')?.severity, 'blocker');
+  assert.equal(planBlockers.find((issue) => issue.code === 'plan.downstream_guesswork.tasks_or_execute_would_redesign')?.severity, 'blocker');
+  assert.equal(formatArtifactDepthBlockingIssues(specBlockers).length, 1);
+  assert.equal(formatArtifactDepthBlockingIssues(planBlockers).length, 1);
+});

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, '\\$&');
+}