@cat-factory/app 0.35.0 → 0.37.0

package/app/types/sandbox.ts

@@ -1,147 +1,55 @@
-// Sandbox (the parallel prompt/model testing surface) wire shapes, hand-mirrored from
-// `@cat-factory/contracts` (sandbox.ts) so a backend payload drops straight into the
-// store. Clone a shipped agent prompt into a versioned candidate, run an experiment
-// matrix (prompt versions × models × fixtures) for one agent kind, and grade every cell
-// with a judge model plus (where a fixture supports it) an objective findings score.
-
-export type SandboxPromptOrigin = 'baseline' | 'candidate'
-
-export interface SandboxPromptVersion {
-  id: string
-  lineageId: string
-  agentKind: string
-  name: string
-  origin: SandboxPromptOrigin
-  systemText: string
-  basePromptId: string | null
-  version: number
-  parentId: string | null
-  labels: string[]
-  createdAt: number
-  createdBy: string | null
-  archivedAt: number | null
-}
-
-export type SandboxFixtureKind =
-  | 'requirements'
-  | 'clarity'
-  | 'architecture'
-  | 'code-review'
-  | 'repo-feature'
-  | 'repo-bug'
-
-export interface SandboxExpectation {
-  id: string
-  summary: string
-  detail: string
-  trickiness: number
-  impact: number
-  matchHints: string[]
-}
-
-export type SandboxFixtureObjective =
-  | { kind: 'tests'; testCmd: string }
-  | { kind: 'findings'; expectations: SandboxExpectation[] }
-
-export interface SandboxFixture {
-  id: string
-  kind: SandboxFixtureKind
-  name: string
-  payload: Record<string, unknown> | null
-  repoRef: { owner: string; name: string; seedRef: string } | null
-  objective: SandboxFixtureObjective | null
-  origin: 'builtin' | 'custom'
-  createdAt: number
-}
-
-export type SandboxExperimentStatus = 'draft' | 'running' | 'done' | 'failed'
-
-export interface SandboxMatrix {
-  promptVersionIds: string[]
-  models: string[]
-  fixtureIds: string[]
-}
-
-export interface SandboxExperiment {
-  id: string
-  name: string
-  agentKind: string
-  judgeModel: string
-  repeats: number
-  status: SandboxExperimentStatus
-  matrix: SandboxMatrix
-  budgetTokens: number | null
-  createdAt: number
-  createdBy: string | null
-}
-
-export type SandboxRunStatus = 'queued' | 'running' | 'done' | 'failed'
-
-export interface SandboxTokenUsage {
-  inputTokens: number
-  outputTokens: number
-}
-
-export interface SandboxRun {
-  id: string
-  experimentId: string
-  promptVersionId: string
-  model: string
-  fixtureId: string
-  repeatIndex: number
-  status: SandboxRunStatus
-  outputText: string | null
-  usage: SandboxTokenUsage | null
-  latencyMs: number | null
-  branch: string | null
-  prUrl: string | null
-  diff: string | null
-  error: string | null
-  seedSha: string | null
-  promptLabel: string
-  startedAt: number | null
-  finishedAt: number | null
-}
-
-export interface SandboxGradeDimension {
-  key: string
-  score: number
-  rationale: string
-}
-
-export interface SandboxObjectiveResult {
-  kind: 'tests' | 'findings'
-  pass: boolean
-  detail: string
-  impactRecall: number | null
-  wowBonus: number | null
-  caught: number | null
-  total: number | null
-  missedHighImpact: string[] | null
-}
-
-export interface SandboxGrade {
-  id: string
-  runId: string
-  judgeModel: string
-  scores: SandboxGradeDimension[]
-  weightedTotal: number
-  objective: SandboxObjectiveResult | null
-  createdAt: number
-}
-
-/** The Sandbox catalog entry for a testable agent kind (from the overview). */
+// Sandbox (the parallel prompt/model testing surface) wire shapes. Clone a shipped
+// agent prompt into a versioned candidate, run an experiment matrix (prompt versions ×
+// models × fixtures) for one agent kind, and grade every cell with a judge model plus
+// (where a fixture supports it) an objective findings score.
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+// The overview / agent-kind-meta / experiment-detail composites have no exported
+// contract type (the routes model them inline), so they stay frontend-only below —
+// and follow the contract's looser `string` for `bucket`/`rubric`.
+
+export type {
+  SandboxPromptOrigin,
+  SandboxPromptVersion,
+  SandboxFixtureKind,
+  SandboxExpectation,
+  SandboxFixtureObjective,
+  SandboxFixture,
+  SandboxExperimentStatus,
+  SandboxMatrix,
+  SandboxExperiment,
+  SandboxRunStatus,
+  SandboxTokenUsage,
+  SandboxRun,
+  SandboxGradeDimension,
+  SandboxObjectiveResult,
+  SandboxGrade,
+  CloneSandboxPromptInput,
+  SaveSandboxVersionInput,
+  CreateSandboxExperimentInput,
+} from '@cat-factory/contracts'
+
+import type {
+  SandboxExperiment,
+  SandboxFixture,
+  SandboxFixtureKind,
+  SandboxGrade,
+  SandboxPromptVersion,
+  SandboxRun,
+} from '@cat-factory/contracts'
+
+/** The Sandbox catalog entry for a testable agent kind (from the overview). Frontend-only. */
 export interface SandboxAgentKindMeta {
   agentKind: string
   label: string
-  bucket: 'inline' | 'container'
-  rubric: 'requirement-review' | 'code-review' | 'implementation'
+  bucket: string
+  rubric: string
   /** Fixture kinds this agent is exercised against (the UI filters the library by these). */
   fixtureKinds: SandboxFixtureKind[]
   basePromptId: string | null
 }
 
-/** The composite the management surface loads on open (`GET /sandbox/overview`). */
+/** The composite the management surface loads on open (`GET /sandbox/overview`). Frontend-only. */
 export interface SandboxOverview {
   agentKinds: SandboxAgentKindMeta[]
   prompts: SandboxPromptVersion[]
@@ -151,33 +59,9 @@ export interface SandboxOverview {
   maxCells: number
 }
 
-/** An experiment with its result grid (`GET /sandbox/experiments/:id`, also from launch). */
+/** An experiment with its result grid (`GET /sandbox/experiments/:id`, also from launch). Frontend-only. */
 export interface SandboxExperimentDetail {
   experiment: SandboxExperiment
   runs: SandboxRun[]
   grades: SandboxGrade[]
 }
-
-// ---- request bodies --------------------------------------------------------
-
-export interface CloneSandboxPromptInput {
-  agentKind: string
-  basePromptId: string | null
-  name?: string
-  labels?: string[]
-}
-
-export interface SaveSandboxVersionInput {
-  parentId: string
-  systemText: string
-  labels?: string[]
-}
-
-export interface CreateSandboxExperimentInput {
-  name: string
-  agentKind: string
-  matrix: SandboxMatrix
-  judgeModel?: string
-  repeats?: number
-  budgetTokens?: number | null
-}

package/app/types/services.ts

@@ -2,26 +2,7 @@
 // a `Service` is the account-owned unit of work (a service frame + its subtree + repo),
 // shared across the workspaces that *mount* it; a `WorkspaceMount` places a service onto a
 // workspace board with that board's own frame layout override.
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
 
-export interface Service {
-  id: string
-  accountId: string | null
-  frameBlockId: string
-  installationId: number | null
-  repoGithubId: number | null
-  /** Subdirectory within the linked monorepo this service lives in (null = whole repo). */
-  directory?: string | null
-  createdAt: number
-  /** How many boards mount this service. Set only on the org catalog (for the "Shared" badge). */
-  mountCount?: number
-}
-
-export interface WorkspaceMount {
-  workspaceId: string
-  serviceId: string
-  /** This board's frame position override. */
-  position: { x: number; y: number }
-  /** This board's dragged frame size; null/absent = auto-size. */
-  size?: { w: number; h: number } | null
-  createdAt: number
-}
+export type { Service, WorkspaceMount } from '@cat-factory/contracts'

package/app/types/slack.ts

@@ -7,51 +7,14 @@
 // Two scopes: the connection (+ bot token, never sent here) is per-account; the
 // notification routing is per-workspace; the @-mention member map is per-account.
 // ---------------------------------------------------------------------------
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
 
-import type { NotificationType } from './notifications'
-
-/** An account's Slack connection, as exposed to clients — safe metadata only. */
-export interface SlackConnection {
-  teamId: string
-  teamName: string
-  teamIconUrl?: string | null
-  botUserId?: string | null
-  scopes?: string[]
-  connectedAt: number
-}
-
-/** Routing for a single notification type: whether it posts, and where. */
-export interface SlackRoute {
-  enabled: boolean
-  /** A channel id (`C0123…`) or name (`#general`); empty = unrouted. */
-  channel: string
-}
-
-/** A workspace's Slack notification routing. */
-export interface SlackNotificationSettings {
-  routes: Partial<Record<NotificationType, SlackRoute>>
-  mentionsEnabled: boolean
-  updatedAt: number
-}
-
-/** One internal user id → Slack member id mapping entry. */
-export type SlackMemberRole = 'product' | 'engineering'
-
-export interface SlackMemberMappingEntry {
-  /** Internal user id (`usr_*`) — the same id the member roster shows. */
-  userId: string
-  slackUserId: string
-  /**
-   * Notification role: `product` people are @-mentioned on requirement-review
-   * findings; everyone else (`engineering`) only when they created the task.
-   * Absent means `engineering`.
-   */
-  role?: SlackMemberRole
-}
-
-/** A Slack channel option for the routing picker. */
-export interface SlackChannel {
-  id: string
-  name: string
-  isPrivate: boolean
-}
+export type {
+  SlackConnection,
+  SlackRoute,
+  SlackNotificationSettings,
+  SlackMemberRole,
+  SlackMemberMappingEntry,
+  SlackChannel,
+} from '@cat-factory/contracts'

package/app/types/spec.ts

@@ -4,71 +4,18 @@
 // sharded in the service repo under `spec/`; the backend reassembles it from the repo's
 // default branch and serves it as `ServiceSpecView` for the inspector's "View
 // Requirements" window.
-
-export type RequirementPriority = 'must' | 'should' | 'could'
-export type RequirementKind = 'functional' | 'nonfunctional' | 'constraint'
-
-/** One acceptance criterion in Given/When/Then form — the seed for a Gherkin scenario. */
-export interface AcceptanceCriterion {
-  id: string
-  given: string
-  when: string
-  /** The Gherkin "Then" clause (named `outcome` so the object is never thenable). */
-  outcome: string
-}
-
-/** A single prescriptive requirement, traceable to the board task(s) it came from. */
-export interface RequirementItem {
-  id: string
-  title: string
-  statement: string
-  kind: RequirementKind
-  priority: RequirementPriority
-  sourceBlockIds?: string[]
-  acceptance?: AcceptanceCriterion[]
-}
-
-/** A domain rule / invariant scoped to the feature group it governs. */
-export interface DomainRule {
-  id: string
-  rule: string
-  rationale?: string
-  sourceBlockIds?: string[]
-}
-
-/** A feature / logical group: related requirements plus the domain rules scoped to them. */
-export interface RequirementGroup {
-  name: string
-  summary?: string
-  requirements?: RequirementItem[]
-  rules?: DomainRule[]
-}
-
-/** A module (domain) — the top level of the taxonomy, holding feature groups. */
-export interface SpecModule {
-  name: string
-  summary?: string
-  groups?: RequirementGroup[]
-}
-
-/** The unified prescriptive specification document for one service. */
-export interface SpecDoc {
-  service: string
-  summary?: string
-  modules?: SpecModule[]
-}
-
-/** A rendered Gherkin feature file read back from the repo. */
-export interface SpecFeatureFile {
-  module: string
-  group: string
-  path: string
-  content: string
-}
-
-/** The service-spec view: the reassembled tree + its Gherkin files (empty when none). */
-export interface ServiceSpecView {
-  present: boolean
-  spec: SpecDoc | null
-  features: SpecFeatureFile[]
-}
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  RequirementPriority,
+  RequirementKind,
+  AcceptanceCriterion,
+  RequirementItem,
+  DomainRule,
+  RequirementGroup,
+  SpecModule,
+  SpecDoc,
+  SpecFeatureFile,
+  ServiceSpecView,
+} from '@cat-factory/contracts'

package/app/types/tasks.ts

@@ -5,114 +5,18 @@
 // source-agnostic, keyed by `source`. Unlike document sources there is no
 // plan/spawn — an issue is linked for context, never expanded into structure.
 // ---------------------------------------------------------------------------
-
-import type { CredentialField } from './documents'
-
-/** The external task trackers cat-factory can link to. */
-export type TaskSourceKind = 'jira' | 'github'
-
-export type { CredentialField }
-
-/** A source's self-description: drives the generic connect + import UI. */
-export interface TaskSourceDescriptor {
-  source: TaskSourceKind
-  label: string
-  /** Lucide icon name for the source. */
-  icon: string
-  credentialFields: CredentialField[]
-  refLabel: string
-  refPlaceholder: string
-  /** Whether the source supports searching its catalogue by title/content. */
-  searchable?: boolean
-}
-
-/**
- * A source's descriptor plus the workspace's live state: whether it's usable now
- * (`available` — a credentialed source is connected; GitHub Issues' App is
- * installed) and whether the workspace offers it (`enabled`, the per-workspace
- * toggle, default true). `available && enabled` is what makes a source offered.
- */
-export interface TaskSourceState extends TaskSourceDescriptor {
-  available: boolean
-  enabled: boolean
-}
-
-/**
- * The verdict of a live "check setup" probe against a source (mirrors
- * `@cat-factory/contracts`). Unlike `available` (a passive row-exists flag) this
- * is the result of actually authenticating + reading, so it distinguishes a
- * configured-but-broken source from a working one.
- */
-export type TaskSourceDiagnosticStatus =
-  | 'ready'
-  | 'not_installed'
-  | 'not_connected'
-  | 'auth_failed'
-  | 'forbidden'
-  | 'unreachable'
-  | 'error'
-
-export interface TaskSourceDiagnostic {
-  source: TaskSourceKind
-  ok: boolean
-  status: TaskSourceDiagnosticStatus
-  /** A one-line, actionable explanation shown verbatim in the panel. */
-  message: string
-  /** Optional extra context (account login, repo count, signed-in user). */
-  detail?: string | null
-}
-
-/** A workspace's connection to a task source (never carries credentials). */
-export interface TaskConnection {
-  source: TaskSourceKind
-  /** Human-friendly label for what we're connected to (site URL). */
-  label: string
-  /** When the connection was established (epoch ms). */
-  connectedAt: number
-}
-
-/** A single comment on an issue, with its body as lightweight Markdown. */
-export interface TaskComment {
-  author: string
-  createdAt: string
-  body: string
-}
-
-/** An issue imported from a source into the workspace, as a structured record. */
-export interface SourceTask {
-  source: TaskSourceKind
-  /** The source's canonical key for the issue (e.g. `PROJ-123`). */
-  externalId: string
-  title: string
-  url: string
-  /** Workflow status name, e.g. `In Progress`. */
-  status: string
-  /** Issue type name, e.g. `Bug`. */
-  type: string
-  /** Assignee display name, or null when unassigned. */
-  assignee: string | null
-  /** Priority name, or null when none. */
-  priority: string | null
-  labels: string[]
-  /** Issue description as lightweight Markdown. */
-  description: string
-  comments: TaskComment[]
-  /** Short plain-text preview of the issue. */
-  excerpt: string
-  /** The board block this issue is attached to as context, if any. */
-  linkedBlockId: string | null
-  syncedAt: number
-}
-
-/** A lean hit from searching a tracker's issues (not yet imported). */
-export interface TaskSearchResult {
-  source: TaskSourceKind
-  /** The source's canonical key for the issue (re-usable as an import ref). */
-  externalId: string
-  title: string
-  url: string
-  /** Workflow status name, e.g. `In Progress` (may be empty). */
-  status: string
-  /** Short plain-text preview (may be empty). */
-  excerpt: string
-}
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  TaskSourceKind,
+  TaskSourceDescriptor,
+  TaskSourceState,
+  TaskSourceDiagnosticStatus,
+  TaskSourceDiagnostic,
+  TaskConnection,
+  TaskComment,
+  SourceTask,
+  TaskSearchResult,
+  CredentialField,
+} from '@cat-factory/contracts'

package/app/types/tracker.ts

@@ -1,27 +1,12 @@
 // Issue-tracker selection shapes, mirroring `@cat-factory/contracts` (tracker.ts).
 // A workspace designates one tracker — GitHub Issues or Jira — where the tech-debt
 // recurring pipeline files its ticket before implementation starts.
-
-export type TrackerKind = 'github' | 'jira'
-
-export interface TrackerSettings {
-  /** The selected tracker, or null when none is configured. */
-  tracker: TrackerKind | null
-  /** Jira project key new tickets are filed under (e.g. 'ENG'); null unless Jira. */
-  jiraProjectKey: string | null
-  /** Writeback: comment on a task's linked issue when its PR opens. Per-task overridable. */
-  writebackCommentOnPrOpen: boolean
-  /** Writeback: comment + close a task's linked issue as resolved when its PR merges. */
-  writebackResolveOnMerge: boolean
-  updatedAt: number
-}
-
-export interface PutTrackerSettingsInput {
-  tracker: TrackerKind | null
-  jiraProjectKey?: string | null
-  writebackCommentOnPrOpen?: boolean
-  writebackResolveOnMerge?: boolean
-}
-
-/** Per-task writeback override; absent ⇒ inherit the workspace setting. */
-export type WritebackOverride = 'on' | 'off'
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  TrackerKind,
+  TrackerSettings,
+  PutTrackerSettingsInput,
+  WritebackOverride,
+} from '@cat-factory/contracts'

package/app/types/userSecrets.ts

@@ -1,49 +1,14 @@
 // Frontend mirrors of the per-user secret + provider-config wire contracts
 // (`@cat-factory/contracts` user-secret.ts + provider-config.ts).
-
-export type UserSecretKind = 'github_pat'
-
-/** One config value a kind needs, rendered as a single form field. */
-export interface ProviderConfigField {
-  key: string
-  label: string
-  help?: string
-  placeholder?: string
-  secret?: boolean
-  required?: boolean
-  type?: 'text' | 'password' | 'select'
-  options?: { value: string; label: string }[]
-}
-
-/** Read-only status of one stored per-user secret — never the secret value. */
-export interface UserSecretStatus {
-  kind: UserSecretKind
-  label: string
-  hasSecret: boolean
-  metadata?: Record<string, string>
-  connectedAt: number
-}
-
-/** A kind's self-description for the generic connect form. */
-export interface UserSecretDescriptor {
-  kind: UserSecretKind
-  label: string
-  configFields: ProviderConfigField[]
-  supportsTest: boolean
-}
-
-export interface StoreUserSecretInput {
-  label?: string
-  secret: string
-  metadata?: Record<string, string>
-}
-
-export interface TestUserSecretInput {
-  secret: string
-  metadata?: Record<string, string>
-}
-
-export interface ConnectionTestResult {
-  ok: boolean
-  message?: string
-}
+//
+// All wire shapes are sourced from @cat-factory/contracts (single source of truth).
+
+export type {
+  UserSecretKind,
+  ProviderConfigField,
+  UserSecretStatus,
+  UserSecretDescriptor,
+  StoreUserSecretInput,
+  TestUserSecretInput,
+  ConnectionTestResult,
+} from '@cat-factory/contracts'

package/app/utils/catalog.ts

@@ -352,6 +352,18 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     color: '#a3e635',
     description: 'Scores the PR and auto-merges within the task thresholds, or asks for review.',
   },
+  'human-review': {
+    kind: 'human-review',
+    label: 'Human Review Gate',
+    icon: 'i-lucide-users',
+    color: '#c084fc',
+    category: 'gates',
+    description:
+      'Waits for a human code review on the PR, looping the fixer to address comments; advances once approved with no unresolved threads.',
+    // Opens the dedicated gate window (approval progress, the feedback being fixed, and a
+    // freeform "request a fix" box) like the other gates.
+    resultView: 'gate',
+  },
   // The Kaizen agent grades agent steps AFTER a run completes (continuous improvement).
   // It is NOT a pipeline step (never in the palette — no `category`), but it runs an LLM,
   // so it needs display metadata here and a per-workspace model in Model Configuration.