agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/application/services/bootstrap-manifest-generator-service.ts

@@ -0,0 +1,251 @@
+import { nowIso, stableHash } from '../../core/fs.js';
+import type {
+  BootstrapManifest,
+  IntakeAmbiguity,
+  ManifestConfidence,
+  ManifestObligation,
+  ManifestObligationKind,
+  ManifestSourceRef,
+  ManifestVerificationHint,
+} from '../../core/intake-artifacts.js';
+
+interface CandidateObligationInput {
+  name: string;
+  description: string;
+  kind: ManifestObligationKind;
+  confidence: ManifestConfidence;
+  verificationHint: ManifestVerificationHint;
+  sourceRefs: ManifestSourceRef[];
+}
+
+const GENERIC_HEADINGS = new Set([
+  'problem statement',
+  'goals',
+  'non-goals',
+  'scope',
+  'out of scope',
+  'acceptance criteria',
+  'testing plan',
+  'risks',
+  'implementation plan',
+  'background',
+  'overview',
+  'summary',
+]);
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function clipDescription(value: string): string {
+  const normalized = normalizeWhitespace(value);
+  return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
+}
+
+function inferKind(text: string): ManifestObligationKind {
+  const normalized = text.toLowerCase();
+  if (/(endpoint|route|api|http|graphql)/.test(normalized)) {
+    return 'endpoint';
+  }
+  if (/(workflow|journey|flow|sequence)/.test(normalized)) {
+    return 'workflow';
+  }
+  if (/(integration|webhook|connector|provider|adapter)/.test(normalized)) {
+    return 'integration';
+  }
+  if (/(contract|schema|manifest|trace|payload)/.test(normalized)) {
+    return 'contract';
+  }
+  if (/(test|verify|verification|validate|assert|coverage)/.test(normalized)) {
+    return 'verification';
+  }
+  if (/(screen|view|panel|card|command|artifact|file|report)/.test(normalized)) {
+    return 'artifact';
+  }
+  return 'behavior';
+}
+
+function inferVerificationHint(text: string): ManifestVerificationHint {
+  return /(test|verify|verification|validate|must|required|shall)/i.test(text)
+    ? 'required'
+    : 'optional';
+}
+
+function inferConfidence(text: string, name: string): ManifestConfidence {
+  if (/`[^`]+`/.test(text) || /[A-Z][A-Za-z0-9]+(?:[A-Z][A-Za-z0-9]+)+/.test(name)) {
+    return 'high';
+  }
+  if (/^\d+\./.test(text) || /^[-*]\s/.test(text)) {
+    return 'medium';
+  }
+  return 'low';
+}
+
+function extractInlineCodeNames(text: string): string[] {
+  return Array.from(text.matchAll(/`([^`]+)`/g), (match) =>
+    normalizeWhitespace(match[1] ?? ''),
+  ).filter((value) => value.length > 0);
+}
+
+function inferName(text: string): string {
+  const inlineNames = extractInlineCodeNames(text);
+  if (inlineNames.length > 0) {
+    return inlineNames[0] ?? 'Unnamed obligation';
+  }
+
+  const colonIndex = text.indexOf(':');
+  if (colonIndex > 0) {
+    const leading = normalizeWhitespace(text.slice(0, colonIndex));
+    if (leading.length >= 3 && leading.length <= 80) {
+      return leading;
+    }
+  }
+
+  const titledToken = text.match(/\b([A-Z][A-Za-z0-9]+(?:[A-Z][A-Za-z0-9]+)+)\b/);
+  if (titledToken?.[1]) {
+    return titledToken[1];
+  }
+
+  const normalized = normalizeWhitespace(text);
+  return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
+}
+
+function buildObligation(
+  featureId: string,
+  index: number,
+  input: CandidateObligationInput,
+): ManifestObligation {
+  return {
+    obligation_id: `OBL-${String(index + 1).padStart(3, '0')}`,
+    kind: input.kind,
+    name: input.name,
+    description: clipDescription(input.description),
+    source_refs: input.sourceRefs,
+    verification_hint: input.verificationHint,
+    confidence: input.confidence,
+  };
+}
+
+function shouldPromoteHeading(heading: string): boolean {
+  const normalized = heading.toLowerCase();
+  if (normalized.length < 4) {
+    return false;
+  }
+  if (GENERIC_HEADINGS.has(normalized)) {
+    return false;
+  }
+  return (
+    /`[^`]+`/.test(heading) ||
+    /(endpoint|route|api|workflow|flow|screen|view|panel|card|command|contract|schema)/i.test(
+      heading,
+    )
+  );
+}
+
+function maybeCreateAmbiguity(
+  line: string,
+  lineNumber: number,
+  obligationIds: string[],
+): IntakeAmbiguity | null {
+  if (!/\b(?:optional|maybe|either|or|unclear)\b|if applicable|if needed/i.test(line)) {
+    return null;
+  }
+  return {
+    id: `AMB-${String(lineNumber).padStart(3, '0')}`,
+    summary: clipDescription(line),
+    status: 'open',
+    obligation_ids: obligationIds.length > 0 ? obligationIds : undefined,
+  };
+}
+
+export class BootstrapManifestGeneratorService {
+  generate(featureId: string, specText: string): BootstrapManifest {
+    const lines = specText.replace(/\r\n/g, '\n').split('\n');
+    const candidates: CandidateObligationInput[] = [];
+    const ambiguities: IntakeAmbiguity[] = [];
+    let currentHeading: string | null = null;
+
+    for (const [index, rawLine] of lines.entries()) {
+      const lineNumber = index + 1;
+      const line = rawLine.trim();
+      if (line.length === 0) {
+        continue;
+      }
+
+      const headingMatch = line.match(/^#{1,6}\s+(.*)$/);
+      if (headingMatch) {
+        currentHeading = normalizeWhitespace(headingMatch[1] ?? '');
+        if (currentHeading && shouldPromoteHeading(currentHeading)) {
+          candidates.push({
+            name: inferName(currentHeading),
+            description: currentHeading,
+            kind: inferKind(currentHeading),
+            confidence: inferConfidence(currentHeading, currentHeading),
+            verificationHint: inferVerificationHint(currentHeading),
+            sourceRefs: [{ line_start: lineNumber, line_end: lineNumber, heading: currentHeading }],
+          });
+        }
+        continue;
+      }
+
+      const bulletText = line.replace(/^[-*+]\s+/, '').replace(/^\d+\.\s+/, '');
+      const isBullet = bulletText !== line;
+      const hasSignal =
+        isBullet ||
+        /`[^`]+`/.test(line) ||
+        /(must|should|shall|required|support|display|render|expose|track|record|verify)/i.test(
+          line,
+        );
+
+      if (!hasSignal) {
+        continue;
+      }
+
+      const obligationName = inferName(bulletText);
+      candidates.push({
+        name: obligationName,
+        description: bulletText,
+        kind: inferKind(bulletText),
+        confidence: inferConfidence(line, obligationName),
+        verificationHint: inferVerificationHint(bulletText),
+        sourceRefs: [{ line_start: lineNumber, line_end: lineNumber, heading: currentHeading }],
+      });
+    }
+
+    const obligations = candidates.map((candidate, index) =>
+      buildObligation(featureId, index, candidate),
+    );
+    const obligationsByLine = new Map<number, string[]>();
+    for (const obligation of obligations) {
+      for (const ref of obligation.source_refs) {
+        const existing = obligationsByLine.get(ref.line_start) ?? [];
+        existing.push(obligation.obligation_id);
+        obligationsByLine.set(ref.line_start, existing);
+      }
+    }
+
+    for (const [index, rawLine] of lines.entries()) {
+      const lineNumber = index + 1;
+      const line = rawLine.trim();
+      const ambiguity = maybeCreateAmbiguity(
+        line,
+        lineNumber,
+        obligationsByLine.get(lineNumber) ?? [],
+      );
+      if (ambiguity) {
+        ambiguities.push(ambiguity);
+      }
+    }
+
+    return {
+      feature_id: featureId,
+      manifest_version: 1,
+      artifact_type: 'bootstrap',
+      generation_mode: 'bootstrap',
+      generated_at: nowIso(),
+      source_hash: stableHash(specText),
+      obligations,
+      ambiguities,
+    };
+  }
+}

package/apps/control-plane/src/application/services/checkpoint-service.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { atomicWriteJson, ensureDir, nowIso, readJson } from '../../core/fs.js';
 import { runGit } from '../../core/git.js';
 import { parseUnifiedDiff } from '../../core/patch.js';
+import { hashWorktreeDiff, readMaterializedWorktreeDiff } from '../../core/worktree-diff.js';
 import type { PatchValidationResult } from './patch-service.js';
 import type { WorktreeWatchdogService } from './worktree-watchdog-service.js';
 
@@ -34,6 +35,11 @@ export interface CheckpointRecord {
   violations: string[];
   severity?: ViolationSeverity;
   diff_snapshot: string;
+  diff_hash?: string;
+  head_sha?: string;
+  workspace_fingerprint?: string;
+  duplicate_of_checkpoint_id?: string;
+  net_new_worktree_change?: boolean;
 }
 
 interface InteractiveCheckpointMetric {
@@ -111,6 +117,38 @@ function readStringArray(value: unknown): string[] {
     .filter((item) => item.length > 0);
 }
 
+function readOptionalString(value: unknown): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+async function readHeadSha(repoRoot: string, worktreePath: string): Promise<string | null> {
+  const result = await runGit(repoRoot, ['rev-parse', 'HEAD'], { cwd: worktreePath });
+  if (result.code !== 0) {
+    return null;
+  }
+  const trimmed = result.stdout.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function buildWorkspaceFingerprint(
+  headSha: string | null,
+  diffHash: string | undefined,
+): string | null {
+  if (!headSha && !diffHash) {
+    return null;
+  }
+  const normalizedHead = headSha ?? 'head:unknown';
+  const normalizedDiff = diffHash ?? 'diff:unknown';
+  return crypto
+    .createHash('sha256')
+    .update(`${normalizedHead}\n${normalizedDiff}`, 'utf8')
+    .digest('hex');
+}
+
 function extractViolationMessages(error: unknown): string[] {
   const envelope =
     error && typeof error === 'object'
@@ -146,21 +184,6 @@ function extractViolationMessages(error: unknown): string[] {
   return rendered.length > 0 ? rendered : ['Checkpoint validation failed'];
 }
 
-function severityRank(severity: ViolationSeverity): number {
-  switch (severity) {
-    case 'info':
-      return 0;
-    case 'warning':
-      return 1;
-    case 'error':
-      return 2;
-    case 'critical':
-      return 3;
-    default:
-      return 1;
-  }
-}
-
 function clampHistory(values: number[]): number[] {
   if (values.length <= INTERACTIVE_METRICS_HISTORY_LIMIT) {
     return values;
@@ -237,14 +260,31 @@ export class CheckpointService {
     return await this.withFeatureLock(input.featureId, async () => {
       const checkpointStartedAt = Date.now();
       const worktreePath = this.worktreePathResolver(input.featureId);
-      const filesChanged = await this.watchdog.getChangedFiles(input.featureId);
+      const priorState = await this.readState(input.featureId);
+      const priorCheckpoints = this.readCheckpoints(priorState.frontMatter);
+      const previousCheckpoint = priorCheckpoints.at(-1) ?? null;
+      const changeSummary = await this.watchdog.getChangeSummary(input.featureId);
+      const filesChanged = changeSummary.changedFiles;
 
       const diffCaptureStartedAt = Date.now();
-      const diffResult = await runGit(this.repoRoot, ['diff', '--no-ext-diff', '--binary'], {
-        cwd: worktreePath,
-      });
-      const diffText = diffResult.code === 0 ? diffResult.stdout : '';
+      const diffText = await readMaterializedWorktreeDiff(this.repoRoot, worktreePath);
       const diffCaptureLatencyMs = Date.now() - diffCaptureStartedAt;
+      const diffHash = hashWorktreeDiff(diffText);
+      const headSha = await readHeadSha(this.repoRoot, worktreePath);
+      const netNewWorktreeChange =
+        diffText.trim().length > 0 &&
+        (changeSummary.hasNetNewChanges ||
+          (previousCheckpoint?.diff_hash != null && previousCheckpoint.diff_hash !== diffHash));
+      const workspaceFingerprint =
+        !netNewWorktreeChange && previousCheckpoint?.workspace_fingerprint
+          ? previousCheckpoint.workspace_fingerprint
+          : buildWorkspaceFingerprint(headSha, diffHash);
+      const duplicateOfCheckpointId =
+        !netNewWorktreeChange &&
+        diffText.trim().length > 0 &&
+        previousCheckpoint?.diff_hash === diffHash
+          ? previousCheckpoint.checkpoint_id
+          : undefined;
 
       const checkpointId = `checkpoint-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
       const checkpointDir = path.join(this.featurePathResolver(input.featureId), 'checkpoints');
@@ -259,7 +299,11 @@ export class CheckpointService {
       let validationResult: PatchValidationResult | null = null;
       let validationLatencyMs = 0;
 
-      if (this.config.validationOnCheckpoint && diffText.trim().length > 0) {
+      if (
+        this.config.validationOnCheckpoint &&
+        diffText.trim().length > 0 &&
+        netNewWorktreeChange
+      ) {
         const validationStartedAt = Date.now();
         try {
           const parsedDiff = parseUnifiedDiff(diffText);
@@ -294,6 +338,11 @@ export class CheckpointService {
         diff_snapshot: path
           .join('.aop', 'features', input.featureId, 'checkpoints', checkpointFile)
           .replaceAll('\\\\', '/'),
+        diff_hash: diffHash,
+        head_sha: headSha ?? undefined,
+        workspace_fingerprint: workspaceFingerprint ?? undefined,
+        duplicate_of_checkpoint_id: duplicateOfCheckpointId,
+        net_new_worktree_change: netNewWorktreeChange,
       };
 
       await this.recordCheckpoint(input.featureId, checkpointRecord);
@@ -312,15 +361,10 @@ export class CheckpointService {
         files_changed: filesChanged.length,
       });
 
-      const blockMerge =
-        validationStatus === 'invalid' &&
-        severity !== undefined &&
-        severityRank(severity) >= severityRank('error');
-
       return {
         checkpoint: checkpointRecord,
         valid: validationResult?.valid ?? validationStatus !== 'invalid',
-        blockMerge,
+        blockMerge: validationStatus === 'invalid',
       };
     });
   }
@@ -403,6 +447,17 @@ export class CheckpointService {
         record['severity'] === 'critical'
           ? (record['severity'] as ViolationSeverity)
           : undefined;
+      const diffHash = typeof record['diff_hash'] === 'string' ? record['diff_hash'] : undefined;
+      const headSha = readOptionalString(record['head_sha']);
+      const workspaceFingerprint = readOptionalString(record['workspace_fingerprint']);
+      const duplicateOfCheckpointId =
+        typeof record['duplicate_of_checkpoint_id'] === 'string'
+          ? record['duplicate_of_checkpoint_id']
+          : undefined;
+      const netNewWorktreeChange =
+        typeof record['net_new_worktree_change'] === 'boolean'
+          ? record['net_new_worktree_change']
+          : undefined;
       normalized.push({
         checkpoint_id: checkpointId,
         timestamp,
@@ -411,6 +466,11 @@ export class CheckpointService {
         violations: readStringArray(record['violations']),
         severity: severityValue,
         diff_snapshot: diffSnapshot,
+        diff_hash: diffHash,
+        head_sha: headSha,
+        workspace_fingerprint: workspaceFingerprint,
+        duplicate_of_checkpoint_id: duplicateOfCheckpointId,
+        net_new_worktree_change: netNewWorktreeChange,
       });
     }
     return normalized;