fix: resolve 5 open bugs and eliminate test flakiness (#1045)

* fix: resolve 5 open bugs and eliminate test flakiness

Bug fixes:
- #1037: static analysis gate now detects project type (Node.js, .NET,
  Go, Rust) and runs appropriate toolchain instead of unconditionally
  requiring package.json
- #1038: event append validates misplaced fields — returns
  VALIDATION_ERROR when event-type-specific fields appear at top level
  instead of inside the data envelope
- #1040: expose checkpoint action in exarchos_workflow composite tool
  (handler already existed but was unreachable)
- #1041: fix wrong phase names in refactor skill — "implement" →
  "polish-implement" in polish-implement.md and polish-validate.md
- #1044: allReviewsPassed guard now enforces required review dimensions
  (spec-compliance, code-quality) for feature workflows, configurable
  via .exarchos.yml required-reviews field

Test infrastructure:
- Switch vitest pool to forks for module-level mock isolation
- Add missing EventStore.initialize() calls in 4 test files
- Eliminates intermittent test failures from PID lock contention

Closes #1037, closes #1038, closes #1040, closes #1041, closes #1044

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review feedback from Seer and CodeRabbit

- Fix go vet skip flag: skipTypecheck → skipLint (Seer)
- Validate repoRoot exists on disk before project detection — return
  error instead of false-positive pass for non-existent paths (CodeRabbit)
- Make _requiredReviews transient — delete from state after guard
  evaluation so it's not persisted to disk (CodeRabbit)
- Update parity test mock to include statSync for new validation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rsalus

documentation/architecture/platform-portability.md

@@ -99,7 +99,7 @@ Point any MCP client at the stdio server:
 ```
 
 You get all four composite tools:
-- `exarchos_workflow` -- init, get, set, cancel, cleanup, reconcile
+- `exarchos_workflow` -- init, get, set, cancel, cleanup, reconcile, checkpoint
 - `exarchos_event` -- append, query, batch
 - `exarchos_orchestrate` -- convergence gates, runbooks, agent specs, script execution
 - `exarchos_view` -- pipeline, tasks, telemetry, convergence status

servers/exarchos-mcp/src/__tests__/workflow/integration.test.ts

@@ -202,11 +202,14 @@ describe('Integration', () => {
       expect(toReview.success).toBe(true);
       expect((toReview.data as Record<string, unknown>).phase).toBe('review');
 
-      // review -> synthesize: requires all reviews passed (reviews is z.record -- schema field)
+      // review -> synthesize: requires all reviews passed with required dimensions
       await handleSet(
         {
           featureId: 'full-saga',
-          updates: { 'reviews.quality': { passed: true, reviewer: 'bot' } },
+          updates: {
+            'reviews.spec-compliance': { status: 'pass', reviewer: 'bot' },
+            'reviews.code-quality': { status: 'pass', reviewer: 'bot' },
+          },
         },
         stateDir,
         eventStore,

servers/exarchos-mcp/src/adapters/mcp.test.ts

@@ -22,6 +22,7 @@ describe('createMcpServer', () => {
   beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-adapter-test-'));
     const eventStore = new EventStore(tmpDir);
+    await eventStore.initialize();
     ctx = { stateDir: tmpDir, eventStore, enableTelemetry: false };
   });
 

servers/exarchos-mcp/src/config/resolve.ts

@@ -29,6 +29,7 @@ export interface ResolvedProjectConfig {
   readonly workflow: {
     readonly skipPhases: readonly string[];
     readonly maxFixCycles: number;
+    readonly requiredReviews: readonly string[];
     readonly phases: Readonly<Record<string, { readonly humanCheckpoint: boolean }>>;
   };
   readonly tools: {
@@ -80,6 +81,7 @@ export const DEFAULTS: ResolvedProjectConfig = deepFreeze({
   workflow: {
     skipPhases: [],
     maxFixCycles: 3,
+    requiredReviews: [],
     phases: {},
   },
   tools: {
@@ -198,6 +200,7 @@ export function resolveConfig(project: ProjectConfig): ResolvedProjectConfig {
   // ── Workflow ──
   const skipPhases = [...(project.workflow?.['skip-phases'] ?? DEFAULTS.workflow.skipPhases)];
   const maxFixCycles = project.workflow?.['max-fix-cycles'] ?? DEFAULTS.workflow.maxFixCycles;
+  const requiredReviews = [...(project.workflow?.['required-reviews'] ?? DEFAULTS.workflow.requiredReviews)];
   const phases: Record<string, { readonly humanCheckpoint: boolean }> = {};
   if (project.workflow?.phases) {
     for (const [name, phaseConfig] of Object.entries(project.workflow.phases)) {
@@ -229,7 +232,7 @@ export function resolveConfig(project: ProjectConfig): ResolvedProjectConfig {
       routing: { coderabbitThreshold, riskWeights },
     },
     vcs: { provider: vcsProvider, settings: vcsSettings },
-    workflow: { skipPhases, maxFixCycles, phases },
+    workflow: { skipPhases, maxFixCycles, requiredReviews, phases },
     tools: { defaultBranch, commitStyle, prTemplate, autoMerge, prStrategy },
     hooks: { on: hooksOn },
   };

servers/exarchos-mcp/src/config/yaml-schema.ts

@@ -66,6 +66,7 @@ const PhaseConfig = z.object({
 const WorkflowConfig = z.object({
   'skip-phases': z.array(z.string()).optional(),
   'max-fix-cycles': z.number().int().min(1).max(10).optional(),
+  'required-reviews': z.array(z.string().min(1)).optional(),
   phases: z.record(z.string(), PhaseConfig).optional(),
 }).strict();
 

servers/exarchos-mcp/src/core/dispatch.test.ts

@@ -20,6 +20,7 @@ describe('dispatch', () => {
   beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'dispatch-test-'));
     eventStore = new EventStore(tmpDir);
+    await eventStore.initialize();
   });
 
   afterEach(async () => {

servers/exarchos-mcp/src/event-store/tools.test.ts

@@ -64,6 +64,92 @@ describe('handleEventAppend data validation', () => {
   });
 });
 
+// ─── Misplaced Event Fields Detection ────────────────────────────────────────
+
+describe('handleEventAppend misplaced fields', () => {
+  it('rejects event with type-specific fields at top level', async () => {
+    const result = await handleEventAppend(
+      {
+        stream: 'misplaced-test',
+        event: {
+          type: 'gate.executed',
+          gateName: 'static-analysis',
+          layer: 'D2',
+          passed: true,
+          details: { reason: 'builds clean' },
+        },
+      },
+      tempDir,
+      eventStore,
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBeDefined();
+    expect(result.error!.code).toBe('VALIDATION_ERROR');
+    expect(result.error!.message).toContain('should be inside "data"');
+    expect(result.error!.message).toContain('gateName');
+  });
+
+  it('accepts event with fields correctly inside data envelope', async () => {
+    const result = await handleEventAppend(
+      {
+        stream: 'correct-test',
+        event: {
+          type: 'gate.executed',
+          data: {
+            gateName: 'static-analysis',
+            layer: 'D2',
+            passed: true,
+            details: { reason: 'builds clean' },
+          },
+        },
+      },
+      tempDir,
+      eventStore,
+    );
+
+    expect(result.success).toBe(true);
+  });
+
+  it('allows unknown top-level fields for events without data schema', async () => {
+    const result = await handleEventAppend(
+      {
+        stream: 'unknown-test',
+        event: {
+          type: 'workflow.started',
+          data: { featureId: 'test', workflowType: 'feature' },
+          correlationId: 'corr-123',
+        },
+      },
+      tempDir,
+      eventStore,
+    );
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('handleBatchAppend misplaced fields', () => {
+  it('rejects batch with misplaced fields in any event', async () => {
+    const result = await handleBatchAppend(
+      {
+        stream: 'batch-misplaced',
+        events: [
+          { type: 'task.assigned', data: { taskId: 't1' } },
+          { type: 'gate.executed', gateName: 'lint', layer: 'D2', passed: true },
+        ],
+      },
+      tempDir,
+      eventStore,
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.error!.code).toBe('VALIDATION_ERROR');
+    expect(result.error!.message).toContain('events[1]');
+    expect(result.error!.message).toContain('gateName');
+  });
+});
+
 // ─── Prototype Pollution Prevention ─────────────────────────────────────────
 
 describe('handleEventQuery field projection', () => {

servers/exarchos-mcp/src/event-store/tools.ts

@@ -2,10 +2,47 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z, ZodError } from 'zod';
 import { coercedStringArray } from '../coerce.js';
 import { EventStore, SequenceConflictError } from './store.js';
-import type { EventType } from './schemas.js';
+import { EVENT_DATA_SCHEMAS, type EventType } from './schemas.js';
 import { formatResult, pickFields, toEventAck, type ToolResult } from '../format.js';
 import { buildValidatedEvent } from './event-factory.js';
 
+// ─── Misplaced Field Detection ──────────────────────────────────────────────
+
+/** Known envelope fields that belong at the top level of an event. */
+const ENVELOPE_FIELDS = new Set([
+  'type', 'data', 'correlationId', 'causationId', 'agentId', 'agentRole',
+  'tenantId', 'organizationId', 'source', 'timestamp', 'idempotencyKey',
+  'schemaVersion',
+]);
+
+/**
+ * Detect event-type-specific fields that were placed at the top level
+ * instead of inside the `data` envelope. Returns misplaced field names
+ * or an empty array if none are found.
+ */
+function detectMisplacedFields(event: Record<string, unknown>): string[] {
+  const eventType = event.type as EventType | undefined;
+  if (!eventType) return [];
+
+  const dataSchema = EVENT_DATA_SCHEMAS[eventType];
+  if (!dataSchema) return [];
+
+  // Extract known field names from the Zod schema
+  const schemaShape = (dataSchema as z.ZodObject<z.ZodRawShape>).shape;
+  if (!schemaShape || typeof schemaShape !== 'object') return [];
+
+  const dataFieldNames = new Set(Object.keys(schemaShape));
+  const misplaced: string[] = [];
+
+  for (const key of Object.keys(event)) {
+    if (!ENVELOPE_FIELDS.has(key) && dataFieldNames.has(key)) {
+      misplaced.push(key);
+    }
+  }
+
+  return misplaced;
+}
+
 // ─── Module-Level EventStore (removed — now threaded via DispatchContext) ─────
 
 // ─── Event Append Handler ───────────────────────────────────────────────────
@@ -38,6 +75,18 @@ export async function handleEventAppend(
 
   const store = eventStore;
 
+  // Detect fields that should be inside data but were placed at the top level
+  const misplaced = detectMisplacedFields(args.event);
+  if (misplaced.length > 0) {
+    return {
+      success: false,
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: `Event fields placed at wrong level — ${misplaced.map(f => `"${f}"`).join(', ')} should be inside "data", not at the top level. Wrap them: { type: "${eventType}", data: { ${misplaced.join(', ')}: ... } }`,
+      },
+    };
+  }
+
   try {
     // Validate at the system boundary (MCP tool handler = untrusted input)
     // Sequence 1 is a placeholder — appendValidated overwrites it with the real sequence
@@ -121,7 +170,7 @@ export async function handleBatchAppend(
     };
   }
 
-  // Validate all events have a type before passing to store
+  // Validate all events have a type and no misplaced fields
   for (let i = 0; i < args.events.length; i++) {
     const eventType = args.events[i]?.type as EventType | undefined;
     if (!eventType) {
@@ -130,6 +179,17 @@ export async function handleBatchAppend(
         error: { code: 'INVALID_INPUT', message: `events[${i}].type is required` },
       };
     }
+
+    const misplaced = detectMisplacedFields(args.events[i]);
+    if (misplaced.length > 0) {
+      return {
+        success: false,
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: `events[${i}]: fields placed at wrong level — ${misplaced.map(f => `"${f}"`).join(', ')} should be inside "data", not at the top level. Wrap them: { type: "${eventType}", data: { ${misplaced.join(', ')}: ... } }`,
+        },
+      };
+    }
   }
 
   const store = eventStore;

servers/exarchos-mcp/src/orchestrate/check-event-emissions.test.ts

@@ -270,9 +270,11 @@ describe('handleOrchestrate integration', () => {
     const isolatedDir = mkdtempSync(join(tmpdir(), 'check-event-emissions-route-'));
     try {
       const { EventStore } = await import('../event-store/store.js');
+      const eventStore = new EventStore(isolatedDir);
+      await eventStore.initialize();
       const result = await handleOrchestrate(
         { action: 'check_event_emissions', featureId: 'test' },
-        { stateDir: isolatedDir, eventStore: new EventStore(isolatedDir), enableTelemetry: false },
+        { stateDir: isolatedDir, eventStore, enableTelemetry: false },
       );
 
       // Should NOT return UNKNOWN_ACTION — meaning the handler is registered

servers/exarchos-mcp/src/orchestrate/pure/static-analysis.parity.test.ts

@@ -23,6 +23,7 @@ vi.mock('node:fs', () => ({
     })
   ),
   existsSync: vi.fn(() => true),
+  statSync: vi.fn(() => ({ isDirectory: () => true })),
 }));
 
 function makePassRunner(): RunCommandFn {
@@ -52,6 +53,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
         '## Static Analysis Report',
         '',
         '**Repository:** `/fake/repo`',
+        '**Project type:** Node.js',
         '',
         '- **PASS**: Lint',
         '- **PASS**: Typecheck',
@@ -63,6 +65,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
       ].join('\n'),
       passCount: 2,
       failCount: 0,
+      projectType: 'Node.js',
     });
   });
 
@@ -76,6 +79,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
         '## Static Analysis Report',
         '',
         '**Repository:** `/fake/repo`',
+        '**Project type:** Node.js',
         '',
         '- **FAIL**: Lint — Lint errors found',
         '- **PASS**: Typecheck',
@@ -87,6 +91,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
       ].join('\n'),
       passCount: 1,
       failCount: 1,
+      projectType: 'Node.js',
     });
   });
 
@@ -101,6 +106,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
         '## Static Analysis Report',
         '',
         '**Repository:** `/fake/repo`',
+        '**Project type:** Node.js',
         '',
         '- **SKIP**: Lint — --skip-lint',
         '- **PASS**: Typecheck',
@@ -112,6 +118,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
       ].join('\n'),
       passCount: 1,
       failCount: 0,
+      projectType: 'Node.js',
     });
   });
 
@@ -126,6 +133,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
         '## Static Analysis Report',
         '',
         '**Repository:** `/fake/repo`',
+        '**Project type:** Node.js',
         '',
         '- **PASS**: Lint',
         '- **SKIP**: Typecheck — --skip-typecheck',
@@ -137,6 +145,7 @@ describe('behavioral parity with static-analysis-gate.sh', () => {
       ].join('\n'),
       passCount: 1,
       failCount: 0,
+      projectType: 'Node.js',
     });
   });
 
@@ -177,6 +186,7 @@ describe('quality-check path', () => {
         '## Static Analysis Report',
         '',
         '**Repository:** `/fake/repo`',
+        '**Project type:** Node.js',
         '',
         '- **PASS**: Lint',
         '- **PASS**: Typecheck',
@@ -188,6 +198,7 @@ describe('quality-check path', () => {
       ].join('\n'),
       passCount: 3,
       failCount: 0,
+      projectType: 'Node.js',
     });
   });
 });