chore(ai-workflow): tighten agent workflow and worktree tooling (#1107)

* chore(ai-workflow): tighten agent workflow and worktree tooling

* fix(ai-workflow): address review feedback

* fix(ai-workflow): make format hook portable

docs/agent-playbooks/hooks-setup.md

@@ -6,9 +6,10 @@ If your AI coding assistant supports lifecycle hooks, configure these for this r
 
 | Hook | Command | Purpose |
 |---|---|---|
-| `afterFileEdit` | `npx oxfmt <file>` | Auto-format files after AI edits |
-| `afterFileEdit` | `.cursor/hooks/yarn-install.sh` | Run `yarn install` when `package.json` changes |
-| `stop` | `yarn build && yarn lint && yarn type-check && (yarn audit || true)` | Build, lint, type-check, and security audit at end |
+| `afterFileEdit` | `scripts/agent-hooks/format.sh` | Auto-format files after AI edits |
+| `afterFileEdit` | `scripts/agent-hooks/yarn-install.sh` | Run `yarn install` when `package.json` changes |
+| `stop` | `scripts/agent-hooks/sync-git-branches.sh` | Prune stale refs and delete integrated temporary task branches |
+| `stop` | `scripts/agent-hooks/verify.sh` | Hard-gate build, lint, and type-check; keep `yarn audit` informational |
 
 ## Why
 
@@ -16,6 +17,8 @@ If your AI coding assistant supports lifecycle hooks, configure these for this r
 - Lockfile stays in sync
 - Build/lint/type issues caught early
 - Security visibility via `yarn audit`
+- One shared hook implementation for both Codex and Cursor
+- Temporary task branches stay aligned with the repo's worktree workflow
 
 ## Example Hook Scripts
 
@@ -42,13 +45,16 @@ exit 0
 # Run build, lint, type-check, and security audit when agent finishes
 
 cat > /dev/null  # consume stdin
-echo "=== yarn build ===" && yarn build
-echo "=== yarn lint ===" && yarn lint
-echo "=== yarn type-check ===" && yarn type-check
+status=0
+yarn build || status=1
+yarn lint || status=1
+yarn type-check || status=1
 echo "=== yarn audit ===" && (yarn audit || true)  # informational
-exit 0
+exit $status
 ```
 
+By default, `scripts/agent-hooks/verify.sh` exits non-zero when `yarn build`, `yarn lint`, or `yarn type-check` fails. Set `AGENT_VERIFY_MODE=advisory` only when you intentionally need signal from a broken tree without blocking the hook.
+
 ### Yarn Install Hook
 
 ```bash
@@ -73,3 +79,5 @@ exit 0
 ```
 
 Configure hook wiring according to your agent tool docs (`hooks.json`, equivalent, etc.).
+
+In this repo, `.codex/hooks/*.sh` and `.cursor/hooks/*.sh` should stay as thin wrappers that delegate to the shared implementations under `scripts/agent-hooks/`.

docs/agent-playbooks/long-running-agent-workflow.md

@@ -0,0 +1,67 @@
+# Long-Running Agent Workflow
+
+Use this playbook when a task is likely to span multiple sessions, handoffs, or spawned agents.
+
+## Goals
+
+- Give each fresh session a fast way to regain context
+- Keep work incremental instead of one-shotting a large change
+- Catch a broken local baseline before adding more code
+- Leave durable artifacts that the next session can trust
+
+## Where to Keep State
+
+- Use `docs/agent-runs/<slug>/` when humans, review bots, or multiple toolchains need the same task state.
+- Use a tool-local directory such as `.codex/runs/<slug>/` only when the task state is intentionally local to one workstation or one toolchain.
+- Do not hide multi-session shared state in a private scratch file if another contributor or agent will need it later.
+
+## Required Files
+
+Create these files at the start of the long-running task:
+
+- `feature-list.json`
+- `progress.md`
+
+Use the templates in `docs/agent-playbooks/templates/feature-list.template.json` and `docs/agent-playbooks/templates/progress.template.md`.
+
+Prefer JSON for the feature list so agents can update a small number of fields without rewriting the whole document.
+
+## Session Start Checklist
+
+1. Run `pwd`.
+2. Read `progress.md`.
+3. Read `feature-list.json`.
+4. Run `git log --oneline -20`.
+5. Run `./scripts/agent-init.sh --smoke`.
+6. Choose exactly one highest-priority item that is still `pending`, `in_progress`, or `blocked`.
+
+If the smoke step fails, fix the broken baseline before implementing a new feature slice.
+
+## Session Rules
+
+- Work on one feature or task slice at a time.
+- Keep the feature list machine-readable and stable. Update status, notes, files, and verification fields instead of rewriting unrelated items.
+- Only mark an item verified after running the command or user flow listed in that item.
+- Use spawned agents for bounded slices, not for overall task-state ownership.
+- When a child agent owns one item, give it the exact item id, acceptance criteria, and files it may touch.
+
+## Session End Checklist
+
+1. Append a short progress entry to `progress.md`.
+2. Update the touched item in `feature-list.json`.
+3. Record the exact commands run for verification.
+4. Capture blockers, follow-ups, and the next best item to resume.
+
+## Recommended Progress Entry Shape
+
+Use a short structure like:
+
+```markdown
+## 2026-03-17 14:30
+
+- Item: F003
+- Summary: Updated the browser-check flow to use the shared init/bootstrap path.
+- Files: `.cursor/agents/browser-check.md`, `.codex/agents/browser-check.toml`
+- Verification: `yarn build`, `yarn lint`, `yarn type-check`
+- Next: Run the smoke flow and update the task-board status.
+```

docs/agent-playbooks/templates/feature-list.template.json

@@ -0,0 +1,17 @@
+{
+  "task": "replace-with-task-slug",
+  "last_updated": "YYYY-MM-DD",
+  "items": [
+    {
+      "id": "F001",
+      "priority": 1,
+      "status": "pending",
+      "description": "Describe one end-to-end feature or one reviewable task slice.",
+      "verification": [
+        "List the command or user-visible check that proves this item works."
+      ],
+      "files": [],
+      "notes": ""
+    }
+  ]
+}

docs/agent-playbooks/templates/progress.template.md

@@ -0,0 +1,12 @@
+# Progress Log
+
+Append one entry per session.
+
+## YYYY-MM-DD HH:MM
+
+- Item: F001
+- Summary: Replace this with the session summary.
+- Files: `path/to/file`
+- Verification: `yarn build`, `yarn lint`, `yarn type-check`
+- Blockers: none
+- Next: Replace this with the next best follow-up.