@company-semantics/contracts 0.46.0 → 0.47.0

package/package.json

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

package/src/ralph/index.ts

@@ -17,6 +17,17 @@ export type {
   RalphPRDPriority,
   RalphPRDItem,
   RalphPRD,
+  // PRD v2.0 schema extensions
+  RalphAgentContract,
+  RalphFailurePolicy,
+  RalphScope,
+  RalphMeta,
+  RalphAcceptanceCriteria,
+  RalphReferenceImplementation,
+  RalphInteractionFlow,
+  RalphCapabilities,
+  RalphSuccessCriteria,
+  RalphCommitPolicy,
 } from './prd';
 
 // PRD constants (cross-repo support)

package/src/ralph/prd.ts

@@ -29,8 +29,8 @@ export const REPO_PRECEDENCE = [
   'company-semantics-ci',
   'company-semantics-backend',
   'company-semantics-edge',
-  'company-semantics-site',
   'company-semantics-app',
+  'company-semantics-site',
 ] as const;
 
 /**
@@ -84,12 +84,209 @@ export type RalphPRDItem = {
   blockedBy?: string[];
   /** Target repository for this feature (inherits from PRD if omitted) */
   repo?: AllowedRepo;
+  /** Machine-verifiable acceptance criteria (preferred over steps) */
+  acceptance?: RalphAcceptanceCriteria[];
+  /** Code shape guidance for implementation */
+  referenceImplementation?: RalphReferenceImplementation;
 };
 
 // =============================================================================
 // PRD Document Types
 // =============================================================================
 
+// =============================================================================
+// PRD v2.0 Schema Extensions
+// =============================================================================
+
+/**
+ * Agent behavioral constraints for execution.
+ *
+ * Defines what the agent is allowed to do during execution.
+ * When omitted, agent uses trust-level defaults.
+ */
+export type RalphAgentContract = {
+  /** Execution mode (inferred from invocation if omitted) */
+  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';
+  /** Enforcement: hard = block on violation, soft = warn + log */
+  enforcement?: 'hard' | 'soft';
+};
+
+/**
+ * Recovery semantics for failures.
+ *
+ * Determines how the agent handles repeated failures.
+ * Default: { maxRetries: 0, onRepeatedFailure: 'halt_and_report', retryScope: 'current_feature_only' }
+ */
+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';
+  /** Scope for retry attempts */
+  retryScope: 'current_feature_only' | 'full_prd';
+  /** Target for escalation (for future HITL workflows) */
+  escalationTarget?: 'human' | 'issue' | 'log_only';
+};
+
+/**
+ * Path boundaries for file operations.
+ *
+ * Constrains where the agent can read/write files.
+ * When omitted, entire repo is allowed with no restrictions.
+ */
+export type RalphScope = {
+  /** Glob patterns for allowed paths */
+  allowedPaths: string[];
+  /** Glob patterns for forbidden paths */
+  forbiddenPaths: string[];
+  /** Whether refactoring (beyond feature scope) is allowed */
+  refactoringAllowed: boolean;
+};
+
+/**
+ * Normalized metadata for PRD tracking.
+ *
+ * Generated at runtime if omitted.
+ */
+export type RalphMeta = {
+  /** Schema version (e.g., "2.0") */
+  schemaVersion: string;
+  /** ISO timestamp when PRD was created */
+  createdAt: string;
+  /** ISO timestamp when PRD was completed (required if status === "completed") */
+  completedAt?: string;
+  /** Owner identifier (user or system) */
+  owner: string;
+};
+
+/**
+ * Machine-verifiable acceptance criteria.
+ *
+ * Discriminated union of verification check types.
+ * All criteria must pass for feature to be marked passes: true.
+ */
+export type RalphAcceptanceCriteria =
+  | { type: 'file_contains'; path: string; pattern: string }
+  | {
+      type: 'command_exit';
+      command: string;
+      expectedExitCode: number;
+    }
+  | {
+      type: 'ci_status';
+      workflow?: string;
+      status: 'success' | 'failure';
+      scope?: 'current_sha' | 'branch';
+    }
+  | { type: 'test_passes'; pattern?: string };
+
+/**
+ * Code shape guidance for feature implementation.
+ *
+ * Provides structural hints without being prescriptive.
+ */
+export type RalphReferenceImplementation = {
+  /** How authoritative is this reference */
+  status: 'authoritative' | 'guidance' | 'partial' | 'anti-pattern';
+  /** Programming language */
+  language: string;
+  /** Location: 'inline' for embedded code, or file path */
+  location: 'inline' | string;
+  /** Inline code (when location is 'inline') */
+  code?: string;
+  /** Policy for deviations from reference */
+  deviationPolicy?: 'must_log' | 'allowed';
+  /** Scoping for where this reference applies */
+  appliesTo?: {
+    /** File paths where this applies */
+    files?: string[];
+    /** Function names where this applies */
+    functions?: string[];
+  };
+};
+
+/**
+ * Temporal behavior expectations.
+ *
+ * Describes expected interaction patterns without UI coupling.
+ */
+export type RalphInteractionFlow = {
+  /** Unique identifier within PRD */
+  id: string;
+  /** Human-readable description */
+  description: string;
+  /** Required behaviors (must be non-empty) */
+  must: string[];
+  /** Forbidden behaviors */
+  mustNot?: string[];
+};
+
+/**
+ * Feature-scoped capability declarations.
+ *
+ * Declares what capabilities the feature requires.
+ * When omitted, all standard capabilities assumed available.
+ */
+export type RalphCapabilities = {
+  /** Whether streaming responses are needed */
+  streaming?: boolean;
+  /** Artifact types produced (e.g., ["code", "text", "diagram"]) */
+  artifacts?: string[];
+  /** Whether multi-modal input/output is needed */
+  multiModal?: boolean;
+  /** Whether regeneration of outputs is allowed */
+  regeneration?: boolean;
+  /** Extensible for future capabilities */
+  [key: string]: boolean | string[] | undefined;
+};
+
+/**
+ * PRD-level success criteria (multi-dimensional).
+ *
+ * Defines what "success" means across functional, operational, and quality dimensions.
+ */
+export type RalphSuccessCriteria = {
+  /** What must work (at least one required) */
+  functional: string[];
+  /** Runtime/safety constraints */
+  operational: string[];
+  /** Code/artifact quality requirements */
+  quality: string[];
+};
+
+/**
+ * Rollback and commit semantics.
+ *
+ * Separate from failurePolicy: failure policy decides WHEN to stop,
+ * commit policy decides WHAT HAPPENS TO CODE.
+ *
+ * Default: {
+ *   strategy: 'per_feature',
+ *   commitOn: 'acceptance_pass',
+ *   rollbackOnFailure: 'uncommitted_only',
+ *   onHalt: 'leave_committed',
+ *   logRollback: true
+ * }
+ */
+export type RalphCommitPolicy = {
+  /** When commits are created */
+  strategy: 'per_feature' | 'manual';
+  /** Gate for allowing commits */
+  commitOn: 'acceptance_pass' | 'manual';
+  /** What to do with code on failure */
+  rollbackOnFailure: 'none' | 'uncommitted_only' | 'current_feature';
+  /** What to do with completed work on halt/escalation */
+  onHalt: 'leave_committed' | 'rollback_uncommitted';
+  /** Whether to log all rollback actions (must be true if rollbackOnFailure !== 'none') */
+  logRollback: boolean;
+};
+
 /**
  * A complete Ralph PRD document.
  *
@@ -105,4 +302,22 @@ export type RalphPRD = {
   features: RalphPRDItem[];
   /** Explicit "done" definition (e.g., "All features pass") */
   stopCondition: string;
+  /** Agent behavioral constraints */
+  agentContract?: RalphAgentContract;
+  /** Recovery semantics for failures */
+  failurePolicy?: RalphFailurePolicy;
+  /** Path boundaries for file operations */
+  scope?: RalphScope;
+  /** Normalized metadata */
+  meta?: RalphMeta;
+  /** Temporal behavior expectations */
+  interactionFlows?: RalphInteractionFlow[];
+  /** Feature-scoped capability declarations */
+  capabilities?: RalphCapabilities;
+  /** PRD-level success criteria */
+  successCriteria?: RalphSuccessCriteria;
+  /** Explicit exclusions to prevent agent overreach */
+  nonGoals?: string[];
+  /** Rollback and commit semantics */
+  commitPolicy?: RalphCommitPolicy;
 };