init-state

Initialize a new workflow state file.

Script: ../core/scripts/state-init.sh

Parameters:

• work_id (required): Work item identifier
• run_id (optional): Run identifier (format: org/project/uuid). If provided, state is stored in per-run directory.
• workflow_id (optional): Workflow to use (default: "default")
• state_path (optional): Path to state file (computed from run_id if provided)

Returns:

{
  "status": "success",
  "operation": "init-state",
  "work_id": "123",
  "run_id": "fractary/my-project/a1b2c3d4-...",
  "workflow_id": "default",
  "state_path": ".fractary/plugins/faber/runs/fractary/my-project/a1b2c3d4-.../state.json"
}

Execution:

# With run_id (preferred for new workflows)
../core/scripts/state-init.sh --run-id "$RUN_ID" "$WORK_ID" "$WORKFLOW_ID"

# Legacy (without run_id)
../core/scripts/state-init.sh "$WORK_ID" "$WORKFLOW_ID" "$STATE_PATH"

read-state

Read current workflow state.

Script: ../core/scripts/state-read.sh

Parameters:

• run_id (optional): Run identifier. If provided, reads from per-run directory.
• state_path (optional): Path to state file (computed from run_id if provided)
• query (optional): jq query for specific field (e.g., .current_phase)

Returns:

{
  "status": "success",
  "operation": "read-state",
  "state": { ... full state object ... }
}

Or with query:

{
  "status": "success",
  "operation": "read-state",
  "query": ".current_phase",
  "result": "build"
}

Execution:

# With run_id (preferred)
../core/scripts/state-read.sh --run-id "$RUN_ID" "$QUERY"

# Legacy
../core/scripts/state-read.sh "$STATE_PATH" "$QUERY"

update-phase

Update a phase's status and data.

Script: ../core/scripts/state-update-phase.sh

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• phase (required): Phase name (frame, architect, build, evaluate, release)
• status (required): New status (pending, in_progress, completed, failed, skipped)
• data (optional): Additional phase data as JSON

Returns:

{
  "status": "success",
  "operation": "update-phase",
  "phase": "build",
  "phase_status": "in_progress",
  "current_phase": "build"
}

Execution:

# With run_id (preferred)
../core/scripts/state-update-phase.sh --run-id "$RUN_ID" "$PHASE" "$STATUS" "$DATA_JSON"

# Legacy
../core/scripts/state-update-phase.sh "$PHASE" "$STATUS" "$DATA_JSON"

update-step

Update a step's status within a phase.

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• phase (required): Phase containing the step
• step_id (required): Unique identifier of the step (uses id field, falls back to name for backward compatibility)
• status (required): New status (pending, in_progress, completed, failed, skipped)
• data (optional): Step result data

Returns:

{
  "status": "success",
  "operation": "update-step",
  "phase": "build",
  "step_id": "implement",
  "step_status": "completed"
}

Execution:

1. Compute state path from run_id if provided
2. Read current state
3. Find step in phase.steps array by matching step_id (check id field first, then name for backward compatibility)
4. Update step status and data
5. Write state back

Note: Step identification uses the id field (preferred) or name field (deprecated, backward compatible). This ensures consistent step tracking across logging, state management, and step targeting.

record-artifact

Record an artifact in state (spec, branch, PR, etc.).

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• artifact_type (required): Type of artifact (spec_path, branch_name, pr_url, pr_number, custom)
• artifact_value (required): Value to record

Returns:

{
  "status": "success",
  "operation": "record-artifact",
  "artifact_type": "branch_name",
  "artifact_value": "feat/123-add-feature"
}

Execution:

1. Compute state path from run_id if provided
2. Read current state
3. Set state.artifacts[artifact_type] = artifact_value
4. Update updated_at timestamp
5. Write state back

mark-complete

Mark the workflow as completed or failed.

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• final_status (required): Final status (completed, failed, cancelled)
• summary (optional): Completion summary
• errors (optional): Error details if failed

Returns:

{
  "status": "success",
  "operation": "mark-complete",
  "final_status": "completed",
  "completed_at": "2025-12-03T11:00:00Z"
}

Execution:

1. Compute state path from run_id if provided
2. Read current state
3. Set state.status = final_status
4. Set state.completed_at = now()
5. Add summary/errors if provided
6. Write state back

update-step-progress

Track exact step progress within a phase (for resume support).

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• phase (required): Current phase being executed
• current_step_index (required): Index of the current/next step in the phase
• steps_completed (required): Array of step names/IDs that have been completed

Returns:

{
  "status": "success",
  "operation": "update-step-progress",
  "phase": "build",
  "current_step_index": 2,
  "steps_completed": ["generate-spec", "create-branch"],
  "resumable": true
}

Execution:

1. Compute state path from run_id if provided
2. Read current state
3. Set state.current_phase = phase
4. Set state.current_step_index = current_step_index
5. Set state.steps_completed = steps_completed
6. Update updated_at timestamp
7. Write state back

Purpose: This operation enables exact-step resume by tracking:

• Which phase we're currently in
• Which step index we're at (0-indexed)
• Which steps have already been completed

When resuming with --resume, the executor reads this state and passes it to faber-manager as resume_context, allowing the manager to skip completed steps and continue from the exact position.

increment-retry

Increment the retry counter for the current phase (for Build-Evaluate loop).

Parameters:

• run_id (optional): Run identifier. If provided, updates per-run state.
• phase (optional): Phase to increment retry for (default: current_phase)

Returns:

{
  "status": "success",
  "operation": "increment-retry",
  "phase": "evaluate",
  "retry_count": 2,
  "max_retries": 3,
  "can_retry": true
}

Execution:

1. Compute state path from run_id if provided
2. Read current state
3. Increment state.phases[phase].retry_count
4. Check against max_retries from workflow config
5. Write state back

check-exists

Check if a state file exists for a run or work item.

Parameters:

• run_id (optional): Run identifier. If provided, checks per-run state.
• work_id (optional): Work ID to check (legacy)
• state_path (optional): Specific state file path (computed from run_id if provided)

Returns:

{
  "status": "success",
  "operation": "check-exists",
  "exists": true,
  "run_id": "fractary/my-project/a1b2c3d4-...",
  "state_path": ".fractary/plugins/faber/runs/fractary/my-project/a1b2c3d4-.../state.json",
  "work_id": "123",
  "current_phase": "build"
}

validate-state

Validate state file structure.

Script: ../core/scripts/state-validate.sh

Parameters:

• run_id (optional): Run identifier. If provided, validates per-run state.
• state_path (optional): Path to state file (computed from run_id if provided)

Returns:

{
  "status": "success",
  "operation": "validate-state",
  "valid": true,
  "run_id": "fractary/my-project/a1b2c3d4-..."
}

backup-state

Create a backup of current state.

Script: ../core/scripts/state-backup.sh

Parameters:

• run_id (optional): Run identifier. If provided, backs up per-run state.
• state_path (optional): Path to state file (computed from run_id if provided)

Returns:

{
  "status": "success",
  "operation": "backup-state",
  "backup_path": ".fractary/plugins/faber/runs/fractary/my-project/a1b2c3d4-.../state.json.backup.20251203T110000Z"
}