@company-semantics/contracts 0.97.0 → 0.98.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/ralph/__tests__/prd-groups.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect } from 'vitest'
+import type {
+  RalphPRD,
+  RalphFeatureGroup,
+  RalphExecutionPolicy,
+} from '../index.js'
+
+describe('RalphFeatureGroup and RalphExecutionPolicy types', () => {
+  describe('RalphPRD with groups field', () => {
+    it('typechecks with groups containing RalphFeatureGroup entries', () => {
+      const prd = {
+        version: '2.1',
+        repo: 'company-semantics-backend',
+        features: [],
+        stopCondition: 'All features pass',
+        groups: [
+          {
+            id: 'auth-group',
+            description: 'Authentication features',
+            features: ['auth/login', 'auth/logout'],
+          },
+        ],
+      } satisfies RalphPRD
+
+      expect(prd.groups).toHaveLength(1)
+      expect(prd.groups![0].id).toBe('auth-group')
+      expect(prd.groups![0].features).toEqual(['auth/login', 'auth/logout'])
+    })
+
+    it('typechecks with multiple groups', () => {
+      const prd = {
+        version: '2.1',
+        repo: 'company-semantics-backend',
+        features: [],
+        stopCondition: 'All features pass',
+        groups: [
+          {
+            id: 'group-a',
+            description: 'First group',
+            features: ['feat-1'],
+          },
+          {
+            id: 'group-b',
+            description: 'Second group',
+            features: ['feat-2', 'feat-3'],
+            sharedContext: 'Shared context for group B',
+          },
+        ],
+      } satisfies RalphPRD
+
+      expect(prd.groups).toHaveLength(2)
+    })
+  })
+
+  describe('backward compatibility — PRD without groups field', () => {
+    it('typechecks without groups field (existing PRD shape)', () => {
+      const prd = {
+        version: '2.0',
+        repo: 'company-semantics-contracts',
+        features: [
+          {
+            id: 'test/feature',
+            category: 'functional' as const,
+            description: 'A test feature',
+            steps: ['Step 1'],
+            passes: false,
+            priority: 'high' as const,
+          },
+        ],
+        stopCondition: 'All features pass',
+      } satisfies RalphPRD
+
+      expect(prd.groups).toBeUndefined()
+      expect(prd.features).toHaveLength(1)
+    })
+
+    it('typechecks with all v2.0 optional fields but no groups', () => {
+      const prd = {
+        version: '2.0',
+        repo: 'company-semantics-backend',
+        features: [],
+        stopCondition: 'Done',
+        agentContract: {
+          mode: 'afk' as const,
+          allowedActions: ['Edit'],
+          forbiddenActions: [],
+          autonomyLevel: 'bounded' as const,
+        },
+        failurePolicy: {
+          maxRetries: 2,
+          onRepeatedFailure: 'halt_and_report' as const,
+          retryScope: 'current_feature_only' as const,
+        },
+        scope: {
+          allowedPaths: ['src/**'],
+          forbiddenPaths: ['node_modules/**'],
+          refactoringAllowed: true,
+        },
+        commitPolicy: {
+          strategy: 'per_feature' as const,
+          commitOn: 'acceptance_pass' as const,
+          rollbackOnFailure: 'uncommitted_only' as const,
+          onHalt: 'leave_committed' as const,
+          logRollback: true,
+        },
+      } satisfies RalphPRD
+
+      expect(prd.groups).toBeUndefined()
+      expect(prd.agentContract).toBeDefined()
+    })
+  })
+
+  describe('RalphExecutionPolicy defaults', () => {
+    it('accepts all required fields', () => {
+      const policy = {
+        parallelism: 1,
+        preferredExecutor: 'same',
+        serializeFiles: [],
+      } satisfies RalphExecutionPolicy
+
+      expect(policy.parallelism).toBe(1)
+      expect(policy.preferredExecutor).toBe('same')
+      expect(policy.serializeFiles).toEqual([])
+    })
+
+    it('accepts preferredExecutor: any', () => {
+      const policy = {
+        parallelism: 4,
+        preferredExecutor: 'any',
+        serializeFiles: ['src/config.ts'],
+      } satisfies RalphExecutionPolicy
+
+      expect(policy.preferredExecutor).toBe('any')
+      expect(policy.serializeFiles).toEqual(['src/config.ts'])
+    })
+
+    it('accepts high parallelism with multiple serialized files', () => {
+      const policy = {
+        parallelism: 10,
+        preferredExecutor: 'any',
+        serializeFiles: ['package.json', 'pnpm-lock.yaml', 'src/index.ts'],
+      } satisfies RalphExecutionPolicy
+
+      expect(policy.parallelism).toBe(10)
+      expect(policy.serializeFiles).toHaveLength(3)
+    })
+  })
+
+  describe('RalphFeatureGroup optional fields', () => {
+    it('typechecks with no optional fields', () => {
+      const group = {
+        id: 'minimal-group',
+        description: 'Minimal group with required fields only',
+        features: ['feat/one'],
+      } satisfies RalphFeatureGroup
+
+      expect(group.id).toBe('minimal-group')
+      expect(group.sharedContext).toBeUndefined()
+      expect(group.completionCriteria).toBeUndefined()
+      expect(group.executionPolicy).toBeUndefined()
+    })
+
+    it('typechecks with sharedContext only', () => {
+      const group = {
+        id: 'shared-ctx-group',
+        description: 'Group with shared context',
+        features: ['feat/a', 'feat/b'],
+        sharedContext: 'All features share the auth domain',
+      } satisfies RalphFeatureGroup
+
+      expect(group.sharedContext).toBe('All features share the auth domain')
+    })
+
+    it('typechecks with completionCriteria only', () => {
+      const group = {
+        id: 'completion-group',
+        description: 'Group with completion criteria',
+        features: ['feat/x'],
+        completionCriteria: 'Integration test suite passes end-to-end',
+      } satisfies RalphFeatureGroup
+
+      expect(group.completionCriteria).toBe(
+        'Integration test suite passes end-to-end',
+      )
+    })
+
+    it('typechecks with executionPolicy only', () => {
+      const group = {
+        id: 'policy-group',
+        description: 'Group with execution policy',
+        features: ['feat/p', 'feat/q'],
+        executionPolicy: {
+          parallelism: 2,
+          preferredExecutor: 'any',
+          serializeFiles: ['shared.ts'],
+        },
+      } satisfies RalphFeatureGroup
+
+      expect(group.executionPolicy).toBeDefined()
+      expect(group.executionPolicy!.parallelism).toBe(2)
+    })
+
+    it('typechecks with all optional fields present', () => {
+      const group = {
+        id: 'full-group',
+        description: 'Group with all optional fields',
+        features: ['feat/1', 'feat/2', 'feat/3'],
+        sharedContext: 'All features modify the database schema',
+        completionCriteria: 'Migration runs cleanly and all tests pass',
+        executionPolicy: {
+          parallelism: 1,
+          preferredExecutor: 'same',
+          serializeFiles: ['drizzle/schema.ts'],
+        },
+      } satisfies RalphFeatureGroup
+
+      expect(group.sharedContext).toBeDefined()
+      expect(group.completionCriteria).toBeDefined()
+      expect(group.executionPolicy).toBeDefined()
+      expect(group.executionPolicy!.preferredExecutor).toBe('same')
+    })
+  })
+
+  describe('RalphPRD groups integration', () => {
+    it('groups field references RalphFeatureGroup type correctly', () => {
+      const group: RalphFeatureGroup = {
+        id: 'test-group',
+        description: 'Test group',
+        features: ['a', 'b'],
+        executionPolicy: {
+          parallelism: 3,
+          preferredExecutor: 'any',
+          serializeFiles: [],
+        },
+      }
+
+      const prd: RalphPRD = {
+        version: '2.1',
+        repo: 'company-semantics-app',
+        features: [],
+        stopCondition: 'Done',
+        groups: [group],
+      }
+
+      expect(prd.groups).toHaveLength(1)
+      expect(prd.groups![0]).toBe(group)
+    })
+  })
+})

package/src/ralph/index.ts

@@ -28,6 +28,9 @@ export type {
   RalphCapabilities,
   RalphSuccessCriteria,
   RalphCommitPolicy,
+  // PRD v2.1 schema extensions
+  RalphExecutionPolicy,
+  RalphFeatureGroup,
 } from './prd';
 
 // PRD constants (cross-repo support)

package/src/ralph/prd.ts

@@ -288,6 +288,45 @@ export type RalphCommitPolicy = {
   logRollback: boolean;
 };
 
+// =============================================================================
+// PRD v2.1 Schema Extensions
+// =============================================================================
+
+/**
+ * Controls how features within a group are distributed and executed.
+ *
+ * @see company-semantics-control/scripts/ralph/src/group/types.ts for runtime equivalent
+ */
+export type RalphExecutionPolicy = {
+  /** Max concurrent executors for this group (default 1) */
+  parallelism: number;
+  /** 'same' prefers all features on one executor, 'any' allows distribution */
+  preferredExecutor: 'same' | 'any';
+  /** Files that must not be modified concurrently (hard constraint) */
+  serializeFiles: string[];
+};
+
+/**
+ * A named group of related PRD features that share research context
+ * and have coordinated execution and completion semantics.
+ *
+ * @see company-semantics-control/scripts/ralph/src/group/types.ts for runtime equivalent (TaskGroup)
+ */
+export type RalphFeatureGroup = {
+  /** Unique identifier for this group within the PRD */
+  id: string;
+  /** Human-readable description of the group's purpose */
+  description: string;
+  /** Feature IDs that belong to this group */
+  features: string[];
+  /** Optional shared context for all features in the group */
+  sharedContext?: string;
+  /** Optional criteria for group-level completion beyond individual feature completion */
+  completionCriteria?: string;
+  /** Optional execution policy controlling parallelism and serialization */
+  executionPolicy?: RalphExecutionPolicy;
+};
+
 /**
  * A complete Ralph PRD document.
  *
@@ -321,4 +360,6 @@ export type RalphPRD = {
   nonGoals?: string[];
   /** Rollback and commit semantics */
   commitPolicy?: RalphCommitPolicy;
+  /** Task groups with shared research, execution policies, and completion tracking (v2.1) */
+  groups?: RalphFeatureGroup[];
 };