@company-semantics/contracts 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -36,6 +36,10 @@
       "types": "./src/email/index.ts",
       "default": "./src/email/index.ts"
     },
+    "./ralph": {
+      "types": "./src/ralph/index.ts",
+      "default": "./src/ralph/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/index.ts

@@ -307,3 +307,27 @@ export type {
 } from './ci-envelope/index'
 
 export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'
+
+// Ralph autonomous coding loop types
+// @see company-semantics-control/docs/ralph.md for usage
+export type {
+  // PRD types
+  RalphPRDCategory,
+  RalphPRDPriority,
+  RalphPRDItem,
+  RalphPRD,
+  // Progress types
+  RalphIteration,
+  RalphMode,
+  RalphProgress,
+  // Trust types
+  RalphTrustLevel,
+  RalphRunResult,
+  RalphCIStatus,
+  RalphTrustLog,
+  RalphTL1Policy,
+  RalphTL2Policy,
+  RalphTL3Policy,
+  RalphTrustPolicy,
+  RalphDemotionReason,
+} from './ralph/index'

package/src/ralph/README.md

@@ -0,0 +1,42 @@
+# ralph/
+
+## Purpose
+
+TypeScript types for Ralph, an autonomous AI coding loop with graduated trust levels.
+
+## Invariants
+
+- Types only; no runtime code (contracts policy)
+- No external dependencies (contracts policy)
+- `RalphTrustLevel` is limited to values 0-3
+- PRD `passes` field is the only field Ralph should modify during execution
+- Orchestration, prompts, and trust logic live in company-semantics-control, not here
+
+## Public API
+
+### PRD Types
+
+- `RalphPRDCategory` — Category of feature item (`functional`, `architectural`, `integration`, `polish`)
+- `RalphPRDPriority` — Priority level (`high`, `medium`, `low`)
+- `RalphPRDItem` — Single feature item in a PRD
+- `RalphPRD` — Complete PRD document
+
+### Progress Types
+
+- `RalphIteration` — Record of a single iteration
+- `RalphMode` — Operation mode (`hitl`, `afk`)
+- `RalphProgress` — Complete session progress state
+
+### Trust Types
+
+- `RalphTrustLevel` — Trust level (0-3)
+- `RalphRunResult` — Run outcome (`success`, `failure`)
+- `RalphCIStatus` — CI status (`green`, `red`, `skipped`)
+- `RalphTrustLog` — Run outcome record for audit
+- `RalphTrustPolicy` — Trust policy configuration
+- `RalphDemotionReason` — Reasons for automatic demotion
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics-control

package/src/ralph/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Ralph Types Barrel
+ *
+ * Re-exports all Ralph autonomous coding loop vocabulary types.
+ * Import from '@company-semantics/contracts/ralph' or '@company-semantics/contracts'.
+ *
+ * Note: This module exports types only (no runtime code per contracts policy).
+ * Orchestration, prompts, and trust logic live in company-semantics-control.
+ *
+ * @see company-semantics-control/docs/ralph.md for usage
+ */
+
+// PRD types
+export type {
+  RalphPRDCategory,
+  RalphPRDPriority,
+  RalphPRDItem,
+  RalphPRD,
+} from './prd';
+
+// Progress types
+export type {
+  RalphIteration,
+  RalphMode,
+  RalphProgress,
+} from './progress';
+
+// Trust types
+export type {
+  RalphTrustLevel,
+  RalphRunResult,
+  RalphCIStatus,
+  RalphTrustLog,
+  RalphTL1Policy,
+  RalphTL2Policy,
+  RalphTL3Policy,
+  RalphTrustPolicy,
+  RalphDemotionReason,
+} from './trust';

package/src/ralph/prd.ts

@@ -0,0 +1,77 @@
+/**
+ * Ralph PRD (Product Requirements Document) Types
+ *
+ * Defines the structure for Ralph's feature tracking, aligned with
+ * Anthropic's feature list pattern for autonomous coding loops.
+ *
+ * Key invariant: The `passes` field is the only field Ralph should modify
+ * during execution — it flips from false to true when verified.
+ *
+ * @see company-semantics-control/docs/ralph.md for usage
+ */
+
+// =============================================================================
+// PRD Item Types
+// =============================================================================
+
+/**
+ * Category of PRD feature item.
+ * Used for prioritization and verification strategy selection.
+ */
+export type RalphPRDCategory =
+  | 'functional'
+  | 'architectural'
+  | 'integration'
+  | 'polish';
+
+/**
+ * Priority level for feature ordering.
+ */
+export type RalphPRDPriority = 'high' | 'medium' | 'low';
+
+/**
+ * A single feature item in a Ralph PRD.
+ *
+ * Design invariants:
+ * - `id` is unique within the PRD (typically "repo/feature-name")
+ * - `passes` starts false and flips to true when verified
+ * - `blockedBy` references other item IDs (dependency ordering)
+ * - `steps` describe verification from user perspective
+ */
+export type RalphPRDItem = {
+  /** Unique identifier, e.g., "contracts/add-ralph-types" */
+  id: string;
+  /** Category for prioritization */
+  category: RalphPRDCategory;
+  /** Human-readable goal description */
+  description: string;
+  /** Verification steps (as a user would test) */
+  steps: string[];
+  /** Whether this feature has been completed and verified */
+  passes: boolean;
+  /** Priority level */
+  priority: RalphPRDPriority;
+  /** IDs of features that must complete before this one */
+  blockedBy?: string[];
+};
+
+// =============================================================================
+// PRD Document Types
+// =============================================================================
+
+/**
+ * A complete Ralph PRD document.
+ *
+ * Contains all features for a Ralph session and defines
+ * the explicit stop condition for completion.
+ */
+export type RalphPRD = {
+  /** Schema version for migration */
+  version: string;
+  /** Target repository name */
+  repo: string;
+  /** Feature items to implement */
+  features: RalphPRDItem[];
+  /** Explicit "done" definition (e.g., "All features pass") */
+  stopCondition: string;
+};

package/src/ralph/progress.ts

@@ -0,0 +1,73 @@
+/**
+ * Ralph Progress Tracking Types
+ *
+ * Types for tracking Ralph session progress. Progress files are
+ * committed to repos after each iteration to enable state rehydration
+ * across context windows.
+ *
+ * Key insight: Each `claude -p` invocation is a FRESH context window.
+ * Progress persists via git-committed state files, not memory.
+ *
+ * @see company-semantics-control/docs/ralph.md for usage
+ */
+
+import type { RalphTrustLevel } from './trust';
+
+// =============================================================================
+// Iteration Types
+// =============================================================================
+
+/**
+ * Record of a single Ralph iteration.
+ *
+ * Written to progress file after each feature completion.
+ * Enables next iteration to understand prior work.
+ */
+export type RalphIteration = {
+  /** Iteration number (1-indexed) */
+  iteration: number;
+  /** ISO 8601 timestamp of iteration completion */
+  timestamp: string;
+  /** PRD feature ID that was worked on */
+  featureId: string;
+  /** Relative paths of files changed */
+  filesChanged: string[];
+  /** Git commit SHA for this iteration */
+  commitSha: string;
+  /** Whether all guards passed */
+  guardsPassed: boolean;
+  /** Concise notes (sacrifice grammar for brevity) */
+  notes: string;
+};
+
+// =============================================================================
+// Session Progress Types
+// =============================================================================
+
+/**
+ * Ralph operation mode.
+ */
+export type RalphMode = 'hitl' | 'afk';
+
+/**
+ * Complete progress state for a Ralph session.
+ *
+ * Stored in `.ralph/progress.txt` (human-readable) or
+ * `.ralph/progress.json` (machine-readable).
+ */
+export type RalphProgress = {
+  /** Unique session identifier (ISO timestamp or UUID) */
+  sessionId: string;
+  /** Target repository name */
+  repo: string;
+  /** Current trust level (0-3) */
+  trustLevel: RalphTrustLevel;
+  /** Operation mode (HITL or AFK) */
+  mode: RalphMode;
+  /** Completed iterations */
+  iterations: RalphIteration[];
+  /** PRD feature IDs that have been completed */
+  completedFeatureIds: string[];
+  /** PRD feature IDs that are blocked (dependencies not met) */
+  blockedFeatureIds: string[];
+};

package/src/ralph/trust.ts

@@ -0,0 +1,125 @@
+/**
+ * Ralph Trust Level Types
+ *
+ * Defines the Trust Promotion framework for graduated AI autonomy.
+ * Ralph earns trust through repeated, measurable compliance — not intent.
+ *
+ * Trust Level Summary:
+ * - TL0 (Sandbox): Default, no network, single repo
+ * - TL1 (Verified): Earned after 8+ consecutive clean runs
+ * - TL2 (Limited Network): Requires human approval, npm/GitHub access
+ * - TL3 (Full AFK): Rare, mechanical tasks only, full network
+ *
+ * @see company-semantics-control/docs/ralph.md for usage
+ */
+
+// =============================================================================
+// Trust Level Types
+// =============================================================================
+
+/**
+ * Trust level numeric value.
+ *
+ * - 0: Sandbox (default)
+ * - 1: Verified AFK
+ * - 2: Limited Network
+ * - 3: Full AFK
+ */
+export type RalphTrustLevel = 0 | 1 | 2 | 3;
+
+/**
+ * Result of a Ralph run.
+ */
+export type RalphRunResult = 'success' | 'failure';
+
+/**
+ * CI status after a Ralph run.
+ */
+export type RalphCIStatus = 'green' | 'red' | 'skipped';
+
+// =============================================================================
+// Trust Log Types
+// =============================================================================
+
+/**
+ * Record of a single Ralph run outcome.
+ *
+ * Stored in `.ralph/trust-log.json` for audit and promotion decisions.
+ */
+export type RalphTrustLog = {
+  /** Run identifier (ISO timestamp) */
+  runId: string;
+  /** Repository where run occurred */
+  repo: string;
+  /** Trust level at time of run */
+  trustLevel: RalphTrustLevel;
+  /** Overall run result */
+  result: RalphRunResult;
+  /** CI status after run */
+  ciStatus: RalphCIStatus;
+  /** Whether human fixes were required post-run */
+  humanFixesRequired: boolean;
+  /** Reason for demotion if applicable */
+  demotionReason?: string;
+  /** Number of iterations completed */
+  iterationsCompleted?: number;
+  /** Number of features completed */
+  featuresCompleted?: number;
+};
+
+// =============================================================================
+// Trust Policy Types
+// =============================================================================
+
+/**
+ * Promotion criteria for TL1 (Verified AFK).
+ */
+export type RalphTL1Policy = {
+  requiredConsecutiveRuns: number;
+  allowNetwork: false;
+};
+
+/**
+ * Promotion criteria for TL2 (Limited Network).
+ */
+export type RalphTL2Policy = {
+  requiresHumanApproval: true;
+  /** Domains allowed for network access */
+  networkAllowlist: string[];
+};
+
+/**
+ * Promotion criteria for TL3 (Full AFK).
+ */
+export type RalphTL3Policy = {
+  requiresExplicitPromotion: true;
+  /** Glob patterns for allowed repos */
+  allowedRepoPatterns: string[];
+};
+
+/**
+ * Complete trust policy configuration.
+ *
+ * Note: Policy logic lives in control repo, not here.
+ * This type defines vocabulary only.
+ */
+export type RalphTrustPolicy = {
+  trustLevel1: RalphTL1Policy;
+  trustLevel2: RalphTL2Policy;
+  trustLevel3: RalphTL3Policy;
+};
+
+// =============================================================================
+// Demotion Types
+// =============================================================================
+
+/**
+ * Reasons for automatic demotion to TL0.
+ */
+export type RalphDemotionReason =
+  | 'ci_failed'
+  | 'guard_violation'
+  | 'manual_patch_required'
+  | 'scope_violation'
+  | 'network_abuse'
+  | 'prd_marked_complete_incorrectly';