# Engine functions reference.

A protocol step’s behaviour isn’t hardcoded — every side effect is a named function listed in the step’s `pre_funcs` or `post_funcs`. The engine ships 45 of them across eight families; this page is the catalogue. The list is authoritative and re-callable in any session via `protocol_available_funcs()`.

## pre_funcs vs post_funcs

`pre_funcs` run when a step is entered — detecting the task, loading a baseline, injecting a reminder, or resolving which AI providers to launch. `post_funcs` run when a step tries to advance — creating files, committing, syncing issues, or enforcing a gate.

A `post_func` only becomes a hard wall when its step sets `post_funcs_stop_on_failure: true` — that’s what turns `require_spec_review_passed`, `check_completion_evidence`, and `verify_tests_pass` from advisory reminders into structural gates. (Placement in `pre_funcs` is cosmetic for gating — the advance only checks `post_funcs`.)

## Eight families

| Family                    | Count  | What it covers                                                                   |
| ------------------------- | ------ | -------------------------------------------------------------------------------- |
| Task lifecycle & state    | 5      | Detect, create, and track the task and its state file.                           |
| Git & branches            | 5      | Branch, commit, merge, push, and open the merge request.                         |
| Gates & verification      | 5      | The structural walls — wire as stop-on-failure post_funcs to actually gate.     |
| Issue tracking            | 2      | Mirror task state to the configured provider.                                    |
| Completion & cleanup      | 7      | Wrap the task up — dispatch the finish flow, archive, and reset state.           |
| Refactoring test baseline | 3      | Capture a green test baseline as the refactoring safety net.                     |
| Optimize loop             | 11     | The metric-driven autoresearch family — measure, experiment, and gate on gaming. |
| Knowledge & AI providers  | 7      | Wiki upkeep and the per-phase parallel-provider launch instructions.             |
| **total**                 | **45** | across eight families                                                            |

## Complete function reference

Every function, by family. _When_ is where it typically wires — `pre` (on step entry) or `post` (on advance).

| Task lifecycle & state           | When | What it does                                                               |
| -------------------------------- | ---- | -------------------------------------------------------------------------- |
| `auto_detect_task`               | pre  | Detect the active task from the current git branch.                        |
| `verify_branch_and_task`         | pre  | Check the branch matches task state and the task file exists (warns only). |
| `create_task_file`               | post | Write the task markdown from AI-provided content, validating frontmatter.  |
| `set_task_state`                 | post | Set current_task.json and rename the pending protocol log to the task.    |
| `update_task_status_in_progress` | post | Flip the task file's status frontmatter to in-progress.                    |

| Git & branches         | When | What it does                                                                |
| ---------------------- | ---- | --------------------------------------------------------------------------- |
| `git_setup_branch`     | post | Create and check out the task branch; can carry uncommitted changes across. |
| `git_commit`           | post | Stage and commit the working tree with a task-derived message.              |
| `git_merge_main`       | post | Fetch and merge the default branch, reporting any conflicts.                |
| `git_push`             | post | Push the current branch to the remote with upstream tracking.               |
| `create_merge_request` | post | Open an MR / PR linked to the task's provider issue.                        |

| Gates & verification                     | When       | What it does                                                                              |
| ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `require_spec_review_passed`             | pre / post | Require a SPEC_REVIEW: PASSED note in the log before leaving code-review.                |
| `check_completion_evidence`              | post       | Block the advance unless the summary carries verification evidence (or the escape hatch). |
| `verify_tests_pass`                      | post       | Run the configured test command; a non-zero exit blocks the advance.                      |
| `validate_code_review_in_worklog`        | post       | Confirm the code-review results were appended to the work log.                            |
| `validate_no_critical_issues_in_worklog` | post       | Fail if the latest review block reports any critical issues.                              |

| Issue tracking            | When | What it does                                            |
| ------------------------- | ---- | ------------------------------------------------------- |
| `create_issue_if_enabled` | post | Create a provider issue when issue tracking is enabled. |
| `update_issue_status`     | post | Move the linked issue to completed / closed.            |

| Completion & cleanup           | When | What it does                                                                       |
| ------------------------------ | ---- | ---------------------------------------------------------------------------------- |
| `present_completion_options`   | pre  | With no issue provider set, offer the merge-local / push-PR / keep / discard menu. |
| `completion_dispatch`          | post | Run the completion chain: archive, commit, merge, push, status, cleanup, checkout. |
| `require_discard_confirmation` | post | Two-step typed confirmation before a discard force-deletes the branch.             |
| `archive_task`                 | post | Move the finished task file into tasks/done/.                                      |
| `cleanup_task_scoped_state`    | post | Remove the task-scoped state directory.                                            |
| `clear_task_state`             | post | Reset current_task.json to the empty state.                                       |
| `checkout_default_branch`      | post | Switch back to main / master after completion.                                     |

| Refactoring test baseline | When | What it does                                            |
| ------------------------- | ---- | ------------------------------------------------------- |
| `capture_test_baseline`   | post | Snapshot the test command and result before any change. |
| `load_test_baseline`      | pre  | Load the saved baseline for regression comparison.      |
| `cleanup_test_baseline`   | post | Remove the baseline file once refactoring completes.    |

| Optimize loop             | When       | What it does                                                                         |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------ |
| `validate_optimize_setup` | post       | Validate optimize settings before any durable side effects are created.              |
| `write_optimize_setup`    | post       | Persist the validated optimize settings to state.                                    |
| `capture_metric_baseline` | post       | Run the metric once on HEAD and record the baseline.                                 |
| `validate_metric_script`  | post       | Pre-flight the metric script — run twice, check the parser and stability.            |
| `run_metric`              | pre / post | Run the metric command N times under a filtered env and aggregate.                   |
| `log_experiment_result`   | post       | Measure HEAD and append an experiment row — the engine, not the LLM, owns the value. |
| `check_cost_estimate`     | post       | Project the wall-clock cost of the run before experimentation starts.                |
| `check_termination`       | post       | After each iteration, test the four stop conditions and end when one matches.        |
| `update_best_commit`      | post       | Record the best commit + metric in the task frontmatter when a run improves.         |
| `batch_checkpoint`        | post       | Pause at each batch boundary for user approval (interactive optimize).               |
| `policy_compliance_audit` | post       | Heuristic scan for metric-gaming; flags feed the review prompt (never blocks).       |

| Knowledge & AI providers                        | When | What it does                                                                  |
| ----------------------------------------------- | ---- | ----------------------------------------------------------------------------- |
| `wiki_update_reminder`                          | pre  | During documentation, remind Claude to update the LLM wiki (if enabled).      |
| `resolve_ai_providers`                          | pre  | Return the parallel AI-provider launch instructions for the code-review gate. |
| `resolve_ai_providers_for_investigation`        | pre  | …for the task investigation phase.                                            |
| `resolve_ai_providers_for_implementation`       | pre  | …for the implementation planning phase.                                       |
| `resolve_ai_providers_for_brainstorm`           | pre  | …for the brainstorm analysis phase.                                           |
| `resolve_ai_providers_for_exploration`          | pre  | …for the research exploration phase.                                          |
| `resolve_ai_providers_for_refactoring_planning` | pre  | …for the refactoring planning phase.                                          |

## Discoverable, not hardcoded

Because behaviour lives in these named functions, adding to a step is a JSON edit, not an engine change — wire a function into a step’s `pre_funcs` / `post_funcs` and it runs. To build your own workflow, fork a protocol (see [customization](https://team.management/docs/customization.md)) and compose these engine functions; for the tools that drive the engine itself, see the [MCP reference](https://team.management/docs/mcp.md).