docs: add hook points documentation and config template

.archeflow/config.yaml

@@ -30,3 +30,26 @@ memory:
 progress:
   enabled: true
   file: .archeflow/progress.md
+
+# Hooks — commands to run at orchestration lifecycle events.
+# Uncomment and customize as needed.
+#
+# hooks:
+#   run-start:
+#     command: "echo 'ArcheFlow run starting'"
+#     fail_action: warn        # warn | abort
+#   phase-complete:
+#     command: "./scripts/on-phase-complete.sh"
+#     fail_action: warn
+#   agent-complete:
+#     command: "./scripts/on-agent-complete.sh"
+#     fail_action: warn
+#   pre-merge:
+#     command: "./scripts/pre-merge-checks.sh"
+#     fail_action: abort       # abort recommended — blocks bad merges
+#   post-merge:
+#     command: "./scripts/post-merge-notify.sh"
+#     fail_action: warn
+#   run-complete:
+#     command: "./scripts/on-run-complete.sh"
+#     fail_action: warn

docs/hooks.md

@@ -0,0 +1,88 @@
+# ArcheFlow Hook Points
+
+Hooks let you run custom commands at key points during an ArcheFlow orchestration run. Use them for notifications, custom validation, CI integration, or project-specific checks.
+
+## Available Hooks
+
+| Hook | When | Env Vars | Default `fail_action` |
+|------|------|----------|----------------------|
+| `run-start` | After initialization, before Plan phase begins | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_WORKFLOW`, `ARCHEFLOW_TASK` | `warn` |
+| `phase-complete` | After each PDCA phase finishes | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_PHASE`, `ARCHEFLOW_CYCLE` | `warn` |
+| `agent-complete` | After each agent returns | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_AGENT`, `ARCHEFLOW_PHASE`, `ARCHEFLOW_DURATION_MS` | `warn` |
+| `pre-merge` | After all reviewers approve, before merging to target branch | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_BRANCH`, `ARCHEFLOW_TARGET` | `abort` |
+| `post-merge` | After successful merge to target branch | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_BRANCH`, `ARCHEFLOW_MERGE_COMMIT` | `warn` |
+| `run-complete` | After the run finishes (success or failure) | `ARCHEFLOW_RUN_ID`, `ARCHEFLOW_STATUS`, `ARCHEFLOW_CYCLES`, `ARCHEFLOW_DURATION_S` | `warn` |
+
+## Configuration
+
+Add a `hooks:` section to your project's `.archeflow/config.yaml`:
+
+```yaml
+hooks:
+  run-start:
+    command: "echo 'Run starting: $ARCHEFLOW_RUN_ID'"
+    fail_action: warn
+  pre-merge:
+    command: "./scripts/lint-check.sh"
+    fail_action: abort
+  run-complete:
+    command: "curl -X POST https://slack.example.com/webhook -d '{\"text\": \"ArcheFlow run $ARCHEFLOW_STATUS\"}'"
+    fail_action: warn
+```
+
+Each hook entry has two fields:
+
+- **`command`** -- shell command to execute. Env vars are available. Runs with `bash -c`.
+- **`fail_action`** -- what happens if the command exits non-zero:
+  - `warn` -- log a warning, continue the run
+  - `abort` -- stop the run immediately, report the failure
+
+## `fail_action` Semantics
+
+| `fail_action` | On command exit 0 | On command exit non-zero |
+|---------------|-------------------|------------------------|
+| `warn` | Continue silently | Log warning, continue |
+| `abort` | Continue silently | Emit `decision` event with `"chosen":"hook_abort"`, halt run, report to user |
+
+**Recommended settings:**
+- Use `abort` for `pre-merge` -- a failing pre-merge check should block the merge
+- Use `warn` for informational hooks (`run-start`, `run-complete`, `post-merge`)
+- Use `warn` for `agent-complete` and `phase-complete` unless you have strict SLA requirements
+
+## Examples
+
+### Slack notification on run complete
+
+```yaml
+hooks:
+  run-complete:
+    command: >
+      curl -s -X POST "$SLACK_WEBHOOK_URL"
+        -H 'Content-Type: application/json'
+        -d '{"text":"ArcheFlow run '"$ARCHEFLOW_RUN_ID"' '"$ARCHEFLOW_STATUS"' ('"$ARCHEFLOW_CYCLES"' cycles, '"$ARCHEFLOW_DURATION_S"'s)"}'
+    fail_action: warn
+```
+
+### Pre-merge lint gate
+
+```yaml
+hooks:
+  pre-merge:
+    command: "npm run lint && npm run typecheck"
+    fail_action: abort
+```
+
+### Log phase timing
+
+```yaml
+hooks:
+  phase-complete:
+    command: "echo \"$(date -u +%H:%M:%S) phase=$ARCHEFLOW_PHASE cycle=$ARCHEFLOW_CYCLE run=$ARCHEFLOW_RUN_ID\" >> .archeflow/phase-timing.log"
+    fail_action: warn
+```
+
+## Hook Execution
+
+Hooks are executed by the `archeflow:run` skill at the corresponding lifecycle point. The command runs in the project root directory with `bash -c`. A 30-second timeout applies to each hook -- if a hook exceeds this, it is killed and treated as a failure (subject to `fail_action`).
+
+Hooks are optional. If no `hooks:` section exists in config, no hooks run. If a specific hook event is not configured, it is silently skipped.