@cat-factory/app 0.20.0 → 0.22.0

package/app/types/domain.ts

@@ -59,8 +59,11 @@ export type BlockType =
  *  - `module`  a sub-frame inside a service; created when a task assigned to a
  *              not-yet-existing module is implemented (tasks can also be dragged in)
  *  - `task`    a draggable unit of work living inside a service or a module
+ *  - `epic`    a NON-structural grouping node: it groups tasks (which keep their own
+ *              service/module parent) via their `epicId`, and is drawn linked to them.
+ *              Never a container — nothing is reparented into an epic.
  */
-export type BlockLevel = 'frame' | 'module' | 'task'
+export type BlockLevel = 'frame' | 'module' | 'task' | 'epic'
 
 /**
  * The kind of work a task represents, chosen at creation. Drives the card's badge/icon
@@ -109,6 +112,16 @@ export interface Block {
   level: BlockLevel
   /** parent container: service or module for a task, service for a module. */
   parentId: string | null
+  /**
+   * task-only: membership link to an `epic`-level block, independent of `parentId`.
+   * Set when the task belongs to an epic (drawn linked to it); absent/null otherwise.
+   */
+  epicId?: string | null
+  /**
+   * task-only: when this task merges, automatically start the tasks that depend on it
+   * (and whose other dependencies are also done). Off/absent ⇒ dependents wait.
+   */
+  autoStartDependents?: boolean
   /** task-only: 0..1 confidence produced when the pipeline finishes. */
   confidence?: number
   /** task-only: the task-estimator's triage (complexity/risk/impact); absent until it runs. */
@@ -283,6 +296,10 @@ export type AgentKind =
   // read-only `bug-investigator` container agent enriches it into a prose report.
   | 'clarity-review'
   | 'bug-investigator'
+  // The human-testing gate: spins up an ephemeral environment and PARKS for a person to
+  // validate the change in a live URL, dispatching the Tester's `fixer` (from findings) or
+  // the `conflict-resolver` (on a conflicting pull-main) on demand. Opens its own window.
+  | 'human-test'
 
 /** A draggable agent definition shown in the agent palette. */
 /** Palette grouping for the agent archetypes (collapsible sections in the builder). */

package/app/types/execution.ts

@@ -333,6 +333,12 @@ export interface PipelineStep {
    * on non-gate steps. Mirrors `gateStepStateSchema`.
    */
   gate?: GateStepState | null
+  /**
+   * Live state of a `human-test` gate (ephemeral env + human validation loop): the phase,
+   * the live environment, the fix/pull-main round history, and any degraded-mode reason.
+   * Absent on non-human-test steps. Mirrors `humanTestStepStateSchema`.
+   */
+  humanTest?: HumanTestStepState | null
 }
 
 /** One failing CI check the gate's precheck saw (mirrors `gateFailingCheckSchema`). */
@@ -387,6 +393,53 @@ export interface TesterStepState {
   lastReport?: TestReport | null
 }
 
+/** The lifecycle status of an ephemeral environment (mirrors `environmentStatusSchema`). */
+export type HumanTestEnvironmentStatus =
+  | 'provisioning'
+  | 'ready'
+  | 'failed'
+  | 'expired'
+  | 'tearing_down'
+  | 'torn_down'
+
+/** The compact env view a `human-test` gate carries (mirrors `humanTestEnvironmentSchema`). */
+export interface HumanTestEnvironment {
+  id: string
+  url: string | null
+  status: HumanTestEnvironmentStatus
+  expiresAt?: number | null
+}
+
+/** One fix / pull-main round on a `human-test` gate (mirrors `humanTestRoundSchema`). */
+export interface HumanTestRound {
+  kind: 'fix' | 'pull-main'
+  /** The human's findings (fix), or a one-line note (pull-main). */
+  findings: string
+  /** The helper container kind this round dispatched (`fixer` / `conflict-resolver`). */
+  helperKind: string
+  jobId?: string | null
+  /** How the helper ended once its job settled; absent while in flight. */
+  outcome?: 'completed' | 'failed' | null
+  /** epoch ms the round opened */
+  at: number
+}
+
+/** Live state of a `human-test` gate (mirrors `humanTestStepStateSchema`). */
+export interface HumanTestStepState {
+  phase: 'provisioning' | 'awaiting_human' | 'fixing' | 'resolving_conflicts' | 'passed'
+  /** the live ephemeral environment (null in degraded manual mode / after destroy) */
+  environment?: HumanTestEnvironment | null
+  /** why no env was auto-provisioned (degraded manual mode), for the window to explain */
+  degradedReason?: string | null
+  /** how many helper (fixer / conflict-resolver) attempts have been dispatched so far */
+  attempts: number
+  /** ceiling on helper attempts (from the task's merge preset) */
+  maxAttempts: number
+  headSha?: string | null
+  /** append-only history of fix / pull-main rounds */
+  rounds?: HumanTestRound[]
+}
+
 /** A pipeline instance running against one block. */
 export interface ExecutionInstance {
   id: string

package/app/types/notifications.ts

@@ -14,6 +14,7 @@ export type NotificationType =
   | 'clarity_review'
   | 'release_regression'
   | 'decision_required'
+  | 'human_test_ready'
 export type NotificationStatus = 'open' | 'acted' | 'dismissed'
 
 /** The on-call agent's recommendation on a `release_regression`. */

package/app/utils/catalog.spec.ts

@@ -29,6 +29,7 @@ const AGENT_KINDS: AgentKind[] = [
   'mocker',
   'business-documenter',
   'business-reviewer',
+  'human-test',
 ]
 const BLOCK_TYPES: BlockType[] = [
   'frontend',

package/app/utils/catalog.ts

@@ -131,6 +131,18 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     description:
       "Turns scenarios into runnable tests — Playwright for frontend, the project's own framework for backend; adds only new ones.",
   },
+  {
+    kind: 'human-test',
+    label: 'Human Testing',
+    icon: 'i-lucide-user-check',
+    color: '#f59e0b',
+    category: 'test',
+    description:
+      'Spins up an ephemeral environment and pauses for a person to validate the change in a live URL — request a fix from findings, pull main + redeploy, or recreate/destroy the env — before the pipeline continues.',
+    // Opens the dedicated human-testing window (env URL + confirm / request-fix / pull-main /
+    // recreate / destroy) instead of the generic prose step-detail panel.
+    resultView: 'human-test',
+  },
   {
     kind: 'documenter',
     label: 'Documenter',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",