@company-semantics/contracts 0.41.0 → 0.42.0

package/package.json

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

package/src/ci-envelope/index.ts

@@ -0,0 +1,38 @@
+/**
+ * CI Envelope Types Barrel
+ *
+ * Re-exports all CI execution envelope vocabulary types.
+ * Import from '@company-semantics/contracts/ci-envelope' or '@company-semantics/contracts'.
+ *
+ * Note: This module exports types only (no runtime code per contracts policy).
+ * Builder, validation, and policy logic live in company-semantics-ci/envelope/.
+ *
+ * @see ADR-CONT-033 for contracts boundary rationale
+ */
+
+// Types
+export type {
+  // Actor & Session
+  CIActorInfo,
+  CISessionInfo,
+  // Intent
+  ExecutionIntent,
+  CIIntentDeclaration,
+  // Scope
+  CIChangeKind,
+  CIExecutionScope,
+  // Authority
+  CIAuthorityGrant,
+  // Guard Plan
+  CIGuardPlan,
+  // Status
+  CIEnvelopeStatus,
+  // Outcome
+  CIGuardViolation,
+  CIExecutionOutcome,
+  // Core Envelope
+  CIExecutionEnvelope,
+} from './types';
+
+// Constants (documentation/type-level, not runtime)
+export { ENVELOPE_TRANSITIONS } from './types';

package/src/ci-envelope/types.ts

@@ -0,0 +1,216 @@
+/**
+ * CI Execution Envelope Type Vocabulary (v1.0.0)
+ *
+ * Canonical types for CI execution envelopes — first-class, append-only records
+ * that capture AI intent, scope, and authority before mutations occur.
+ *
+ * Design invariants:
+ * - Types only — no validation logic, no policy mappings (those live in CI repo)
+ * - Envelope is append-only (status transitions, no field deletions)
+ * - Schema version enables future migration
+ *
+ * @see ADR-CONT-033 for design rationale
+ * @see company-semantics-ci/envelope/ for builder and validation logic
+ */
+
+// =============================================================================
+// Actor & Session Types
+// =============================================================================
+
+/**
+ * Actor information for audit trail.
+ * Currently Claude-only, extensible for future actor types.
+ */
+export type CIActorInfo = {
+  kind: 'claude';
+  model: string;
+};
+
+/**
+ * Session context for correlating envelope to conversation.
+ */
+export type CISessionInfo = {
+  conversationId: string;
+  turnId: string;
+};
+
+// =============================================================================
+// Intent Types
+// =============================================================================
+
+/**
+ * Execution intent categories.
+ * Defines the semantic "why" of an execution.
+ *
+ * Note: Policy mappings (intent → required guards) live in CI repo,
+ * not here. This type defines vocabulary only.
+ */
+export type ExecutionIntent =
+  | 'feature_extension'
+  | 'bug_fix'
+  | 'refactor_structural'
+  | 'guard_update'
+  | 'policy_update'
+  | 'schema_change'
+  | 'doc_update'
+  | 'cleanup'
+  | 'experimental';
+
+/**
+ * Intent declaration with optional ADR references.
+ */
+export type CIIntentDeclaration = {
+  primary: ExecutionIntent;
+  secondary?: ExecutionIntent[];
+  description: string;
+  adrRefs?: string[];
+};
+
+// =============================================================================
+// Scope Types
+// =============================================================================
+
+/**
+ * Change kind for scope declarations.
+ */
+export type CIChangeKind = 'add' | 'modify' | 'delete';
+
+/**
+ * Execution scope defining affected repos and paths.
+ */
+export type CIExecutionScope = {
+  repos: string[];
+  /** Glob patterns for affected paths */
+  paths: string[];
+  changeKinds: CIChangeKind[];
+};
+
+// =============================================================================
+// Authority Types
+// =============================================================================
+
+/**
+ * Authority grant documenting permission basis.
+ */
+export type CIAuthorityGrant = {
+  /** References to CLAUDE.md / AI_AUTONOMY.md sections */
+  allowedBy: string[];
+  requiresConfirmation: boolean;
+};
+
+// =============================================================================
+// Guard Plan Types
+// =============================================================================
+
+/**
+ * Guard execution plan resolved from intent + scope.
+ * Populated by guard plan resolver in CI repo.
+ */
+export type CIGuardPlan = {
+  /** Guard IDs that MUST pass */
+  required: string[];
+  /** Guard IDs allowed to warn (advisory) */
+  advisory: string[];
+};
+
+// =============================================================================
+// Status Types
+// =============================================================================
+
+/**
+ * Envelope lifecycle status.
+ *
+ * State machine:
+ * - proposed → validated | blocked
+ * - validated → executing | blocked
+ * - executing → finalized | blocked
+ * - blocked → (terminal)
+ * - finalized → (terminal)
+ *
+ * Note: Transition validation logic lives in CI repo, not here.
+ */
+export type CIEnvelopeStatus =
+  | 'proposed'
+  | 'validated'
+  | 'blocked'
+  | 'executing'
+  | 'finalized';
+
+// =============================================================================
+// Outcome Types
+// =============================================================================
+
+/**
+ * A single guard violation for post-execution audit.
+ */
+export type CIGuardViolation = {
+  guardId: string;
+  severity: 'error' | 'warning';
+  message: string;
+  file?: string;
+  line?: number;
+};
+
+/**
+ * Execution outcome populated on finalization.
+ */
+export type CIExecutionOutcome = {
+  filesChanged: number;
+  commits: string[];
+  violations?: CIGuardViolation[];
+};
+
+// =============================================================================
+// Core Envelope Type
+// =============================================================================
+
+/**
+ * CI Execution Envelope — the atomic unit of governed execution.
+ *
+ * Created before mutations, finalized after. Enables:
+ * - Pre-execution gating (intent/scope/authority check)
+ * - Post-hoc audit (what was planned vs what happened)
+ * - Deterministic explanation (no LLM guesswork)
+ */
+export type CIExecutionEnvelope = {
+  /** Schema version for migration (bump on breaking changes) */
+  envelopeVersion: 1;
+  /** Unique identifier (UUID v7 recommended) */
+  executionId: string;
+  /** ISO 8601 timestamp */
+  createdAt: string;
+  actor: CIActorInfo;
+  session: CISessionInfo;
+  intent: CIIntentDeclaration;
+  scope: CIExecutionScope;
+  authority: CIAuthorityGrant;
+  guardPlan: CIGuardPlan;
+  status: CIEnvelopeStatus;
+  /** Structured reason when status='blocked' */
+  blockedReason?: string;
+  /** Populated on finalization */
+  outcome?: CIExecutionOutcome;
+};
+
+// =============================================================================
+// Transition Graph (Documentation Only)
+// =============================================================================
+
+/**
+ * Valid status transitions (documentation only).
+ *
+ * This const documents the state machine for reference.
+ * Actual transition validation logic lives in CI repo.
+ *
+ * Terminal states: blocked, finalized (empty transition arrays)
+ */
+export const ENVELOPE_TRANSITIONS: Record<
+  CIEnvelopeStatus,
+  readonly CIEnvelopeStatus[]
+> = {
+  proposed: ['validated', 'blocked'],
+  validated: ['executing', 'blocked'],
+  blocked: [],
+  executing: ['finalized', 'blocked'],
+  finalized: [],
+} as const;

package/src/identity/avatar.ts

@@ -8,7 +8,6 @@
  */
 
 import type { UserIdentity } from './types';
-import { extractFirstWord } from './display-name';
 
 // =============================================================================
 // Types

package/src/index.ts

@@ -260,3 +260,30 @@ export {
   getExecutionKindDefinition,
   isValidExecutionKind,
 } from './execution/index'
+
+// CI Execution Envelope types
+// @see ADR-CONT-033 for contracts boundary rationale
+export type {
+  // Actor & Session
+  CIActorInfo,
+  CISessionInfo,
+  // Intent
+  ExecutionIntent,
+  CIIntentDeclaration,
+  // Scope
+  CIChangeKind,
+  CIExecutionScope,
+  // Authority
+  CIAuthorityGrant,
+  // Guard Plan
+  CIGuardPlan,
+  // Status
+  CIEnvelopeStatus,
+  // Outcome
+  CIGuardViolation,
+  CIExecutionOutcome,
+  // Core Envelope
+  CIExecutionEnvelope,
+} from './ci-envelope/index'
+
+export { ENVELOPE_TRANSITIONS } from './ci-envelope/index'