agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/test/gate-freshness.spec.ts

@@ -0,0 +1,590 @@
+import { describe, expect, it } from 'vitest';
+import {
+  assessGateFreshness,
+  EMPTY_WORKTREE_DIFF_HASH,
+  hasMaterialWorktreeDiffHash,
+  parseGateEvidence,
+  readGateEvidenceByMode,
+  readLatestCheckpoint,
+} from '../src/core/gate-freshness.js';
+
+describe('gate-freshness helpers', () => {
+  it('reads the latest checkpoint summary when checkpoint metadata is present', () => {
+    const checkpoint = readLatestCheckpoint({
+      checkpoints: [
+        {
+          checkpoint_id: 'checkpoint-1',
+          timestamp: '2026-03-12T16:00:00.000Z',
+          validation_status: 'valid',
+          diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+          diff_hash: 'diff-1',
+          net_new_worktree_change: true,
+          violations: ['none'],
+        },
+      ],
+    });
+
+    expect(checkpoint).toMatchObject({
+      checkpointId: 'checkpoint-1',
+      validationStatus: 'valid',
+      diffHash: 'diff-1',
+      netNewWorktreeChange: true,
+    });
+  });
+
+  it('returns null when the latest checkpoint shape is incomplete', () => {
+    expect(readLatestCheckpoint({ checkpoints: [{}] })).toBeNull();
+    expect(readLatestCheckpoint({})).toBeNull();
+  });
+
+  it('identifies the empty checkpoint diff hash as non-material work', () => {
+    expect(hasMaterialWorktreeDiffHash(EMPTY_WORKTREE_DIFF_HASH)).toBe(false);
+    expect(hasMaterialWorktreeDiffHash('diff-1')).toBe(true);
+    expect(hasMaterialWorktreeDiffHash(null)).toBe(false);
+  });
+
+  it('returns missing checkpoint validity when no valid checkpoint metadata exists', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {},
+      mode: 'fast',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.checkpoint).toBeNull();
+    expect(assessment.checkpointValidity).toBe('missing');
+    expect(assessment.shouldRerunGate).toBe(false);
+    expect(assessment.reasons).toContain('checkpoint_missing');
+  });
+
+  it('requests a rerun when the latest checkpoint was skipped and gate evidence is missing', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('checkpoint_skipped');
+    expect(assessment.reasons).toContain('gate_evidence_missing:full');
+  });
+
+  it('does not request a rerun when the checkpoint is skipped and no diff hash is available', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            // no diff_hash
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.shouldRerunGate).toBe(false);
+  });
+
+  it('requests a rerun when checkpoint is skipped and existing evidence has no inputDiffHash', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {
+        full: {
+          mode: 'full',
+          overall: 'pass',
+          inputDiffHash: null,
+          inputCheckpointId: null,
+          inputWorktreeValidity: 'unknown',
+          finishedAt: '2026-03-12T16:00:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.freshness).toBe('stale');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('gate_evidence_unscoped:full');
+  });
+
+  it('requests a rerun when checkpoint is skipped and evidence diff hash is stale', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-2',
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {
+        full: {
+          mode: 'full',
+          overall: 'pass',
+          inputDiffHash: 'diff-1',
+          inputCheckpointId: 'checkpoint-old',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T15:00:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.freshness).toBe('stale');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('gate_evidence_stale:full');
+  });
+
+  it('uses the most recent effective valid checkpoint when newer duplicate checkpoints were skipped', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-valid',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-valid.diff',
+            diff_hash: 'diff-1',
+          },
+          {
+            checkpoint_id: 'checkpoint-skipped',
+            timestamp: '2026-03-12T16:05:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-skipped.diff',
+            diff_hash: 'diff-1',
+            duplicate_of_checkpoint_id: 'checkpoint-valid',
+            net_new_worktree_change: false,
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {
+        fast: {
+          mode: 'fast',
+          overall: 'fail',
+          inputDiffHash: 'diff-old',
+          inputCheckpointId: 'checkpoint-old',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T15:55:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.checkpointValidity).toBe('valid');
+    expect(assessment.currentDiffHash).toBe('diff-1');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('checkpoint_effective_valid');
+    expect(assessment.reasons).toContain('gate_evidence_stale:fast');
+  });
+
+  it('treats warning-severity invalid checkpoints as rerunnable when evidence is missing', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-warning',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'invalid',
+            severity: 'warning',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-warning.diff',
+            diff_hash: 'diff-1',
+            violations: ['outside_allowed_areas'],
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('checkpoint_invalid_nonblocking');
+    expect(assessment.reasons).toContain('gate_evidence_missing:fast');
+  });
+
+  it('keeps duplicate skipped checkpoints effective when the prior invalid checkpoint is warning-only', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-warning',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'invalid',
+            severity: 'warning',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-warning.diff',
+            diff_hash: 'diff-1',
+            violations: ['outside_allowed_areas'],
+          },
+          {
+            checkpoint_id: 'checkpoint-skipped',
+            timestamp: '2026-03-12T16:05:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-skipped.diff',
+            diff_hash: 'diff-1',
+            duplicate_of_checkpoint_id: 'checkpoint-warning',
+            net_new_worktree_change: false,
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {
+        full: {
+          mode: 'full',
+          overall: 'pass',
+          inputDiffHash: 'diff-old',
+          inputCheckpointId: 'checkpoint-old',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T15:55:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('checkpoint_skipped');
+    expect(assessment.reasons).toContain('gate_evidence_stale:full');
+    expect(assessment.reasons).not.toContain('checkpoint_invalid');
+  });
+
+  it('reports missing evidence as rerun-needed when the latest checkpoint is valid', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.freshness).toBe('missing');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('gate_evidence_missing:fast');
+  });
+
+  it('reports current evidence when the evidence diff hash matches the checkpoint diff hash', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {
+        fast: {
+          mode: 'fast',
+          overall: 'pass',
+          inputDiffHash: 'diff-1',
+          inputCheckpointId: 'checkpoint-1',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T16:05:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.freshness).toBe('current');
+    expect(assessment.shouldRerunGate).toBe(false);
+    expect(assessment.latestGateOverall).toBe('pass');
+  });
+
+  it('keeps evidence current when idle checkpoints carry forward the same workspace fingerprint', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-material',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-material.diff',
+            diff_hash: 'diff-material',
+            workspace_fingerprint: 'workspace-1',
+            net_new_worktree_change: true,
+          },
+          {
+            checkpoint_id: 'checkpoint-idle',
+            timestamp: '2026-03-12T16:05:00.000Z',
+            validation_status: 'skipped',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-idle.diff',
+            diff_hash: EMPTY_WORKTREE_DIFF_HASH,
+            workspace_fingerprint: 'workspace-1',
+            net_new_worktree_change: false,
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {
+        fast: {
+          mode: 'fast',
+          overall: 'pass',
+          inputDiffHash: 'diff-material',
+          inputCheckpointId: 'checkpoint-material',
+          inputHeadSha: 'head-1',
+          inputWorkspaceFingerprint: 'workspace-1',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T16:06:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.freshness).toBe('current');
+    expect(assessment.shouldRerunGate).toBe(false);
+    expect(assessment.currentDiffHash).toBe('diff-material');
+  });
+
+  it('reports stale evidence when the evidence diff hash differs from the checkpoint diff hash', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {
+        full: {
+          mode: 'full',
+          overall: 'fail',
+          inputDiffHash: 'diff-old',
+          inputCheckpointId: 'checkpoint-old',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T16:05:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.freshness).toBe('stale');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('gate_evidence_stale:full');
+  });
+
+  it('treats unscoped legacy evidence as stale when it lacks input_diff_hash', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {
+        fast: {
+          mode: 'fast',
+          overall: 'pass',
+          inputDiffHash: null,
+          inputCheckpointId: null,
+          inputWorktreeValidity: 'unknown',
+          finishedAt: '2026-03-12T16:05:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.freshness).toBe('stale');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('gate_evidence_unscoped:fast');
+  });
+
+  it('treats invalid checkpoints as nonblocking warnings for rerun assessment', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'invalid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+            violations: ['outside_allowed_areas'],
+          },
+        ],
+      },
+      mode: 'fast',
+      gateEvidenceByMode: {},
+    });
+
+    expect(assessment.checkpointValidity).toBe('skipped');
+    expect(assessment.shouldRerunGate).toBe(true);
+    expect(assessment.reasons).toContain('checkpoint_invalid_nonblocking');
+    expect(assessment.reasons).toContain('gate_evidence_missing:fast');
+  });
+
+  it('falls back to latest_evidence when gate_evidence_by_mode is absent and mode matches', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'fast',
+      latestEvidence: {
+        mode: 'fast',
+        overall: 'pass',
+        input_diff_hash: 'diff-1',
+        input_checkpoint_id: 'checkpoint-1',
+        input_worktree_validity: 'valid',
+        finished_at: '2026-03-12T16:05:00.000Z',
+      },
+    });
+
+    expect(assessment.freshness).toBe('current');
+    expect(assessment.latestGateOverall).toBe('pass');
+  });
+
+  it('ignores latest_evidence when its mode does not match the requested mode', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+            diff_hash: 'diff-1',
+          },
+        ],
+      },
+      mode: 'fast',
+      latestEvidence: {
+        mode: 'full',
+        overall: 'pass',
+        input_diff_hash: 'diff-1',
+        input_checkpoint_id: 'checkpoint-1',
+        input_worktree_validity: 'valid',
+        finished_at: '2026-03-12T16:05:00.000Z',
+      },
+    });
+
+    expect(assessment.gateEvidence).toBeNull();
+    expect(assessment.freshness).toBe('missing');
+    expect(assessment.shouldRerunGate).toBe(true);
+  });
+
+  it('returns unknown freshness when the checkpoint is valid but missing diff_hash', () => {
+    const assessment = assessGateFreshness({
+      frontMatter: {
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-1',
+            timestamp: '2026-03-12T16:00:00.000Z',
+            validation_status: 'valid',
+            diff_snapshot: '.aop/features/feature-a/checkpoints/checkpoint-1.diff',
+          },
+        ],
+      },
+      mode: 'full',
+      gateEvidenceByMode: {
+        full: {
+          mode: 'full',
+          overall: 'pass',
+          inputDiffHash: 'diff-1',
+          inputCheckpointId: 'checkpoint-1',
+          inputWorktreeValidity: 'valid',
+          finishedAt: '2026-03-12T16:05:00.000Z',
+        },
+      },
+    });
+
+    expect(assessment.freshness).toBe('unknown');
+    expect(assessment.shouldRerunGate).toBe(false);
+    expect(assessment.reasons).toContain('checkpoint_diff_hash_missing');
+  });
+
+  it('normalizes empty or malformed evidence maps to an empty mode lookup', () => {
+    expect(readGateEvidenceByMode(null)).toEqual({});
+    expect(readGateEvidenceByMode({ latest_evidence: {} })).toEqual({});
+  });
+
+  it('normalizes explicit gate evidence by mode from context payloads', () => {
+    const byMode = readGateEvidenceByMode({
+      gate_evidence_by_mode: {
+        fast: {
+          mode: 'fast',
+          overall: 'fail',
+          input_diff_hash: 'diff-1',
+          input_checkpoint_id: 'checkpoint-1',
+          input_worktree_validity: 'valid',
+          finished_at: '2026-03-12T16:05:00.000Z',
+        },
+      },
+    });
+
+    expect(byMode.fast).toMatchObject({
+      mode: 'fast',
+      overall: 'fail',
+      inputDiffHash: 'diff-1',
+      inputCheckpointId: 'checkpoint-1',
+      inputWorktreeValidity: 'valid',
+    });
+  });
+
+  it('normalizes malformed gate evidence fields to null and unknown validity', () => {
+    expect(parseGateEvidence(null)).toBeNull();
+
+    const parsed = parseGateEvidence({
+      mode: 'fast',
+      overall: 'pass',
+      input_diff_hash: 'diff-1',
+      input_checkpoint_id: 'checkpoint-1',
+      input_worktree_validity: 'stale',
+      finished_at: '2026-03-12T16:05:00.000Z',
+    });
+
+    expect(parsed?.inputWorktreeValidity).toBe('unknown');
+  });
+});