docs: describe work items, plan approval and merge policy

README.md

@@ -121,7 +121,8 @@ own improvements. See [docs/decisions/0001-name.md](docs/decisions/0001-name.md)
   (manual, every 15 minutes to every 30 days), enabled flag and last status.
   The interval is the minimum gap between runs; it does not cap the number of
   PRs or issues the repository can produce.
-- **Job lifecycle**: `queued → running → succeeded | failed | quota_exhausted`.
+- **Job lifecycle**: `queued → running → succeeded | failed | cancelled | paused | quota_exhausted`.
+- **Work items and gates**: triage-to-merge work items linked to issues, PRs and jobs; optional plan-first approval with allowed/forbidden paths; per-job pause/resume/cancel; target-branch preflight and active-work-item dedupe.
 - **Per-repository FlyBot**: each repository gets a separate container, a
   private bridge/model proxy and a team (Chief, Lead, Product, Test, Security,
   Reviewer, two Devs). The shared operator FlyBot is never used for user jobs.

README.zh.md

@@ -108,7 +108,8 @@ Fledge 是幼鸟长齐飞羽、离巢试飞的那一刻——不是因为被推
 
 - **一个账号多个仓库**：每个仓库有独立目标、节奏（手动，15 分钟到 30 天）、
   启用状态和上次状态。间隔是最小运行间隔，不是 PR/issue 数量上限。
-- **任务状态**：`queued → running → succeeded | failed | quota_exhausted`。
+- **任务状态**：`queued → running → succeeded | failed | cancelled | paused | quota_exhausted`。
+- **工作项与门禁**：工作项覆盖 triage 到 merge，关联 issue/PR/job；可选“先出计划、批准后执行”并限制允许/禁止路径；任务支持暂停/恢复/取消；任务创建前检查目标分支，有活跃工作项时跳过定时任务。
 - **每仓库 FlyBot**：每个仓库一个独立容器、独立 bridge/模型代理和团队
   （Chief、Lead、Product、Test、Security、Reviewer、2 个 Dev）。共享的运营方
   FlyBot 永远不接用户任务。

docs/api.md

@@ -31,7 +31,10 @@ All browser routes are HTML. Machine routes are JSON. Errors use:
 | POST | `/repos` | approved + CSRF | Add an upstream repository; Fledge checks or creates the user's fork |
 | GET | `/repos/:id` | owner | Repo detail, including the selected role and allowed roles |
 | GET | `/readyz` | public | Database and per-repository instance readiness summary |
-| POST | `/repos/:id/run` | owner + CSRF | Enqueue a manual iterate job |
+| POST | `/repos/:id/run` | owner + CSRF | Enqueue a manual iterate job; plan-first repositories enqueue a plan |
+| POST | `/repos/:id/work` | owner + CSRF | Create a work item |
+| POST | `/repos/:id/work/:workItemId/state` | owner + CSRF | Move a work item through the triage/assignment/review state machine |
+| POST | `/repos/:id/work/:workItemId/run` | owner + CSRF | Start a plan or iterate job for a work item |
 | POST | `/repos/:id/role` | owner + CSRF | Select `maintainer` or `developer` for this user-repository connection |
 | POST | `/repos/:id/plan` | owner + CSRF | Enqueue a plan-only job (no code, branch or PR) |
 | POST | `/repos/:id/instance` | owner + CSRF | Start the per-repository FlyBot instance |
@@ -40,7 +43,12 @@ All browser routes are HTML. Machine routes are JSON. Errors use:
 | POST | `/repos/:id/review` | owner + CSRF | Enqueue a manual review job |
 | GET | `/repos/:id/jobs/:jobId` | owner | Job detail: evidence, cost, attribution, retry |
 | POST | `/repos/:id/jobs/:jobId/retry` | owner + CSRF | Retry a failed job, including its checkpoint |
-| POST | `/repos/:id/jobs/:jobId/execute` | owner + CSRF | Execute a completed plan as an iterate job |
+| POST | `/repos/:id/jobs/:jobId/approve-plan` | maintainer + CSRF | Approve a completed plan with allowed/forbidden paths |
+| POST | `/repos/:id/jobs/:jobId/reject-plan` | maintainer + CSRF | Reject a completed plan |
+| POST | `/repos/:id/jobs/:jobId/execute` | maintainer + CSRF | Execute an approved plan as an iterate job |
+| POST | `/repos/:id/jobs/:jobId/cancel` | owner + CSRF | Cancel a queued or running job |
+| POST | `/repos/:id/jobs/:jobId/pause` | owner + CSRF | Pause a queued or running job |
+| POST | `/repos/:id/jobs/:jobId/resume` | owner + CSRF | Resume a paused job from its checkpoint |
 | GET | `/repos/:id/workspace` | admin | Fledge-branded agent workspace shell |
 | `*` | `/repos/:id/workspace/app/*` | admin | Authenticated reverse proxy to the per-repo DSH UI |
 | GET | `/repos/:id/team` | admin | Team console |
@@ -52,7 +60,7 @@ All browser routes are HTML. Machine routes are JSON. Errors use:
 | GET | `/api/repos/:id/chief/events` | owner | Server-Sent Events for new Chief messages |
 | POST | `/api/repos/:id/team/answer` | admin + CSRF | Answer a team question |
 | POST | `/api/repos/:id/team/stop` | admin + CSRF | Stop the active roles (hard when possible, otherwise a stop request) |
-| POST | `/repos/:id/settings` | owner + CSRF | Goal, target branch, role, auto-merge switch, cadence, enabled, reviewer interval |
+| POST | `/repos/:id/settings` | owner + CSRF | Goal, target branch, role, plan-first, path constraints, merge method/protection, auto-merge, cadence, enabled, reviewer interval |
 | POST | `/repos/:id/delete` | owner + CSRF | Delete repo and jobs |
 | GET | `/settings` | approved | Account, model, API tokens |
 | POST | `/settings/model` | approved + CSRF | Save/clear own model |

docs/architecture.md

@@ -93,10 +93,20 @@
   upstream can enable a scheduled reviewer. Review jobs list every open upstream
   PR, score each one, and post a COMMENT review; they never merge or modify
   code. A developer cannot run review jobs even when GitHub grants write access.
+- **Work items and gates**: each repository has work items with a
+  triage-to-merge state machine (`proposed → triaged → assigned → in_progress →
+  pr_ready → in_review → changes_requested → approved → merged/closed`). Jobs
+  link to a work item, and issue/PR/review webhooks keep state and PR outcome in
+  sync. A repository can require a plan before code; a maintainer approves or
+  rejects it with allowed/forbidden path constraints, and execution is blocked
+  until approval. Iterate jobs preflight the target branch, record the base SHA,
+  warn when the fork is behind, and scheduled work is skipped while an active
+  work item is open.
 - **Auto-merge switch**: off by default. Only a maintainer can enable it. When
   it is on, Fledge (not the agent) verifies the PR is open and mergeable, every
   check run is green, the combined commit status is not failing, and no current
-  review requests changes before it performs a squash merge. The agent prompt
+  review requests changes, and the branch protection rule confirms the required
+  checks and approvals before it performs a squash merge. The agent prompt
   always forbids merging. The switch is stored on the repository and included
   in the job payload for reporting. A stale or downgraded role blocks the merge.