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/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.
+```