@company-semantics/contracts 9.1.0 → 9.2.0

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

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

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

@@ -1,41 +1,41 @@
-import { describe, it, expect } from 'vitest'
-import { REPO_PRECEDENCE } from '../prd.js'
+import { describe, it, expect } from "vitest";
+import { REPO_PRECEDENCE } from "../prd.js";
 
-describe('REPO_PRECEDENCE', () => {
-  it('has contracts first (dependency source)', () => {
-    expect(REPO_PRECEDENCE[0]).toBe('company-semantics-contracts')
-  })
+describe("REPO_PRECEDENCE", () => {
+  it("has contracts first (dependency source)", () => {
+    expect(REPO_PRECEDENCE[0]).toBe("company-semantics-contracts");
+  });
 
-  it('exact values and order are frozen (golden snapshot)', () => {
+  it("exact values and order are frozen (golden snapshot)", () => {
     expect(REPO_PRECEDENCE).toStrictEqual([
-      'company-semantics-contracts',
-      'company-semantics-control',
-      'company-semantics-ci',
-      'company-semantics-backend',
-      'company-semantics-edge',
-      'company-semantics-app',
-      'company-semantics-site',
-    ])
-  })
+      "company-semantics-contracts",
+      "company-semantics-control",
+      "company-semantics-ci",
+      "company-semantics-backend",
+      "company-semantics-edge",
+      "company-semantics-app",
+      "company-semantics-site",
+    ]);
+  });
 
-  it('has exactly 7 entries (all known repos)', () => {
-    expect(REPO_PRECEDENCE).toHaveLength(7)
-  })
+  it("has exactly 7 entries (all known repos)", () => {
+    expect(REPO_PRECEDENCE).toHaveLength(7);
+  });
 
-  it('has no duplicates', () => {
-    expect(new Set(REPO_PRECEDENCE).size).toBe(REPO_PRECEDENCE.length)
-  })
+  it("has no duplicates", () => {
+    expect(new Set(REPO_PRECEDENCE).size).toBe(REPO_PRECEDENCE.length);
+  });
 
-  it('all entries start with company-semantics- prefix', () => {
+  it("all entries start with company-semantics- prefix", () => {
     for (const repo of REPO_PRECEDENCE) {
-      expect(repo).toMatch(/^company-semantics-/)
+      expect(repo).toMatch(/^company-semantics-/);
     }
-  })
+  });
 
-  it('all entries are non-empty strings', () => {
+  it("all entries are non-empty strings", () => {
     for (const repo of REPO_PRECEDENCE) {
-      expect(typeof repo).toBe('string')
-      expect(repo.length).toBeGreaterThan(0)
+      expect(typeof repo).toBe("string");
+      expect(repo.length).toBeGreaterThan(0);
     }
-  })
-})
+  });
+});

package/src/ralph/index.ts

@@ -31,15 +31,10 @@ export type {
   // PRD v2.1 schema extensions
   RalphExecutionPolicy,
   RalphFeatureGroup,
-} from './prd';
+} from "./prd";
 
 // PRD constants (cross-repo support)
-export { REPO_PRECEDENCE } from './prd';
+export { REPO_PRECEDENCE } from "./prd";
 
 // Progress types
-export type {
-  RalphIteration,
-  RalphMode,
-  RalphProgress,
-} from './progress';
-
+export type { RalphIteration, RalphMode, RalphProgress } from "./progress";

package/src/ralph/prd.ts

@@ -24,13 +24,13 @@
  * - Validation of repo graph (no cycles)
  */
 export const REPO_PRECEDENCE = [
-  'company-semantics-contracts',
-  'company-semantics-control',
-  'company-semantics-ci',
-  'company-semantics-backend',
-  'company-semantics-edge',
-  'company-semantics-app',
-  'company-semantics-site',
+  "company-semantics-contracts",
+  "company-semantics-control",
+  "company-semantics-ci",
+  "company-semantics-backend",
+  "company-semantics-edge",
+  "company-semantics-app",
+  "company-semantics-site",
 ] as const;
 
 /**
@@ -48,16 +48,16 @@ export type AllowedRepo = (typeof REPO_PRECEDENCE)[number];
  * Used for prioritization and verification strategy selection.
  */
 export type RalphPRDCategory =
-  | 'functional'
-  | 'architectural'
-  | 'integration'
-  | 'polish'
-  | 'validation';
+  | "functional"
+  | "architectural"
+  | "integration"
+  | "polish"
+  | "validation";
 
 /**
  * Priority level for feature ordering.
  */
-export type RalphPRDPriority = 'high' | 'medium' | 'low';
+export type RalphPRDPriority = "high" | "medium" | "low";
 
 /**
  * A single feature item in a Ralph PRD.
@@ -107,15 +107,15 @@ export type RalphPRDItem = {
  */
 export type RalphAgentContract = {
   /** Execution mode (inferred from invocation if omitted) */
-  mode: 'afk' | 'hitl';
+  mode: "afk" | "hitl";
   /** Actions explicitly allowed (empty = all allowed per trust level) */
   allowedActions: string[];
   /** Actions explicitly forbidden */
   forbiddenActions: string[];
   /** Autonomy level: bounded = conservative, full = aggressive */
-  autonomyLevel: 'bounded' | 'full';
+  autonomyLevel: "bounded" | "full";
   /** Enforcement: hard = block on violation, soft = warn + log */
-  enforcement?: 'hard' | 'soft';
+  enforcement?: "hard" | "soft";
 };
 
 /**
@@ -128,11 +128,11 @@ export type RalphFailurePolicy = {
   /** Number of retries before triggering onRepeatedFailure (0 = no retries) */
   maxRetries: number;
   /** Action on repeated failure */
-  onRepeatedFailure: 'halt_and_report' | 'continue_next_feature' | 'escalate';
+  onRepeatedFailure: "halt_and_report" | "continue_next_feature" | "escalate";
   /** Scope for retry attempts */
-  retryScope: 'current_feature_only' | 'full_prd';
+  retryScope: "current_feature_only" | "full_prd";
   /** Target for escalation (for future HITL workflows) */
-  escalationTarget?: 'human' | 'issue' | 'log_only';
+  escalationTarget?: "human" | "issue" | "log_only";
 };
 
 /**
@@ -173,19 +173,19 @@ export type RalphMeta = {
  * All criteria must pass for feature to be marked passes: true.
  */
 export type RalphAcceptanceCriteria =
-  | { type: 'file_contains'; path: string; pattern: string }
+  | { type: "file_contains"; path: string; pattern: string }
   | {
-      type: 'command_exit';
+      type: "command_exit";
       command: string;
       expectedExitCode: number;
     }
   | {
-      type: 'ci_status';
+      type: "ci_status";
       workflow?: string;
-      status: 'success' | 'failure';
-      scope?: 'current_sha' | 'branch';
+      status: "success" | "failure";
+      scope?: "current_sha" | "branch";
     }
-  | { type: 'test_passes'; pattern?: string };
+  | { type: "test_passes"; pattern?: string };
 
 /**
  * Code shape guidance for feature implementation.
@@ -194,15 +194,15 @@ export type RalphAcceptanceCriteria =
  */
 export type RalphReferenceImplementation = {
   /** How authoritative is this reference */
-  status: 'authoritative' | 'guidance' | 'partial' | 'anti-pattern';
+  status: "authoritative" | "guidance" | "partial" | "anti-pattern";
   /** Programming language */
   language: string;
   /** Location: 'inline' for embedded code, or file path */
-  location: 'inline' | string;
+  location: "inline" | string;
   /** Inline code (when location is 'inline') */
   code?: string;
   /** Policy for deviations from reference */
-  deviationPolicy?: 'must_log' | 'allowed';
+  deviationPolicy?: "must_log" | "allowed";
   /** Scoping for where this reference applies */
   appliesTo?: {
     /** File paths where this applies */
@@ -277,13 +277,13 @@ export type RalphSuccessCriteria = {
  */
 export type RalphCommitPolicy = {
   /** When commits are created */
-  strategy: 'per_feature' | 'manual';
+  strategy: "per_feature" | "manual";
   /** Gate for allowing commits */
-  commitOn: 'acceptance_pass' | 'manual';
+  commitOn: "acceptance_pass" | "manual";
   /** What to do with code on failure */
-  rollbackOnFailure: 'none' | 'uncommitted_only' | 'current_feature';
+  rollbackOnFailure: "none" | "uncommitted_only" | "current_feature";
   /** What to do with completed work on halt/escalation */
-  onHalt: 'leave_committed' | 'rollback_uncommitted';
+  onHalt: "leave_committed" | "rollback_uncommitted";
   /** Whether to log all rollback actions (must be true if rollbackOnFailure !== 'none') */
   logRollback: boolean;
 };
@@ -301,7 +301,7 @@ 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';
+  preferredExecutor: "same" | "any";
   /** Files that must not be modified concurrently (hard constraint) */
   serializeFiles: string[];
 };