feat(engine): optional-stage drop + closing brief tool + provider OAuth + feedback-branch reconciliation

CLAUDE.md

@@ -101,11 +101,14 @@ When modifying any component, check if other components need corresponding updat
 | Hard Gates | Execution phase | exit code enforcement in quality-gate.sh | orchestrator.ts |
 | Persistence | Context Preservation | Environment-detected via `isGitRepo()` (git or filesystem) | state-tools.ts, git-worktree.ts |
 | Providers | Memory Providers section | `plugin/schemas/providers/*.json`, `plugin/providers/*.md` | config.sh |
+| Provider OAuth (auth + token store) | N/A — implementation | Git-provider (github/gitlab) auth brokered through **haikumethod.ai** (NOT .com) — the Cloud Function in `deploy/auth-proxy/` runs a brokered authorization-code handshake (NOT the provider's native RFC-8628 device flow): `/cli/start` mints a **`session_id`** + `verification_url`, the browse-site callback POSTs the exchanged token to `/cli/complete`, the CLI polls `/cli/poll { session_id }` and reads the token bundle **spread at top level** of the `ready` response (matches `deploy/auth-proxy/src/cli.ts`). Token stored client-only in `~/.haiku/settings.json`. **Auth-when-needed (NOT auth-first):** `ensureProviderToken(provider)` (in `haiku_auth_login.ts`) returns a usable stored token or runs the handshake INLINE — the engine never tells the agent to "call haiku_auth_login first." Provider is the repo's (origin host). Tools: `haiku_auth_login` (explicit login), `haiku_auth_status`, `haiku_auth_logout`, `haiku_upload_proof` (upload proof to the delivery PR/MR over REST — auto-auths via `ensureProviderToken`; `proof_upload_auth_unavailable` only when auth genuinely can't be obtained). Token shape (`access_token`/`refresh_token`/`expires_at`/`scopes`/`account`/`host`) + read/write/clear live in `global-settings.ts`; provider detection (`parseGitRemote`/`providerFromHost`/`providerFromOrigin`/`readOriginRemoteUrl`) in `git-worktree.ts` | global-settings.ts, state/schemas/global-settings.ts, tools/orchestrator/haiku_auth_*.ts + haiku_upload_proof.ts, deploy/auth-proxy/ |
+| PR/MR ops via stored token (Phase 4) | N/A — implementation | The engine drives PR/MR **create** + **mark-ready** over the provider REST API (`provider-rest.ts`, injectable fetch), **authenticating when needed**: `resolvePrRestContextEnsuringAuth` (origin host → provider → `ensureProviderToken`) obtains a token inline if none is stored — no "auth first." Any REST miss (incl. auth that couldn't be obtained — broker down / declined / headless) falls back to the `gh`/`glab` CLI (`openPullRequestCli`). The pre-open guard skips only when there's no CLI AND no recognized provider remote (`providerFromOrigin`). NO merge over REST — the human's merge is the approval signal (merge stays CLI/human-only). The two synchronous handler entry points (intent-main draft open in `haiku_intent_create`, repair PR in `haiku_repair`) stay CLI-only — a sync handler can't await REST/auth. REST contracts are doc-derived + mock-validated; CLI is the integration-proven path | provider-rest.ts, git-worktree.ts (`openPullRequest`/`markPullRequestReady` async + `resolvePrRestContextEnsuringAuth`), orchestrator/workflow/side-effects.ts |
+| Closing brief (BRIEF.md) | Quality Enforcement | Per-stage user-facing `BRIEF.md` written twice via the engine-owned `haiku_write_brief { body }` tool — `pre` (the plan) on first write, `post` (what shipped) on the closing rewrite at stage finish. The tool takes ONLY the body; the engine resolves intent (from branch), stage (from cursor), and the `phase:` frontmatter (file absent → pre, present → post — the same signal `stageOwesClosingBrief` gates on, so frontmatter can't drift from the cursor). Frontmatter via gray-matter. The `write_brief` cursor action fires from `stageOwesBrief` (pre, BRIEF absent) and `stageOwesClosingBrief` (post, BRIEF exists + `phase != post`); two reachable surfaces (non-autopilot user-gate, autopilot/merge in `haiku_run_next`). Opt out with `brief: false` on intent FM | tools/orchestrator/haiku_write_brief.ts, orchestrator/workflow/cursor.ts (`stageOwesBrief`/`stageOwesClosingBrief`), prompts/stage/review/write_brief/ |
 | Harness | N/A (implementation detail) | `--harness <name>` MCP arg or `HAIKU_HARNESS` env var; capability registry in `harness.ts`, instruction adaptation in `harness-instructions.ts` | harness.ts, harness-instructions.ts, orchestrator.ts, server.ts |
 | Architecture (canonical) | N/A — implementation reference | `plugin/studios/ARCHITECTURE.md` — boundaries, lifecycle, hat patterns, FB-as-unit fix-loop semantics. Read before any structural change to studios, stages, hats, or workflow tools | ARCHITECTURE.md |
 | Workflow-managed file boundary | Quality Enforcement | PreToolUse hook denies generic Read/Write/Edit on `units/*.md`, `feedback/*.md`, `intent.md`, `stages/*/state.json`. Agents go through MCP tools only; redirect messages name the right tool | hooks/guard-workflow-fields.ts |
 | Unit CRUDL (MCP) | N/A — implementation | `haiku_unit_write` (create/rewrite, FM validators, DAG cycle detection, pending-only lifecycle), `haiku_unit_read` (body+title only — no FM exposed), `haiku_unit_get` (read ONE agent-authorable/corrective FM field — `quality_gates`/`outputs`/`inputs`/`depends_on`/`model`/`closes`/`title`; refuses FSM-driven fields with `unit_field_engine_only`; the read half of the corrective exemption so a gate-command fix is read→modify-one→write-back, not a whole-array clobber), `haiku_unit_set` (FM field update, lifecycle-enforced; `outputs`/`quality_gates` stay editable after a unit goes active — corrective exemption), `haiku_unit_delete` (pending only), `haiku_unit_list` | state-tools.ts |
-| Feedback CRUDL (MCP) | N/A — implementation | `haiku_feedback_write` (body update, lifecycle-enforced), `haiku_feedback_read` (body+title only), `haiku_feedback` (create), `haiku_feedback_update` (status transitions, terminal-state-protected), `haiku_feedback_reject` (mark invalid), `haiku_feedback_delete`, `haiku_feedback_list`, `haiku_feedback_set_targets` / `haiku_feedback_set_severity` (classifier-hat backfill — write-once) | state-tools.ts |
+| Feedback CRUDL (MCP) | N/A — implementation | `haiku_feedback_write` (body update, lifecycle-enforced), `haiku_feedback_read` (body+title only), `haiku_feedback` (create), `haiku_feedback_reject` (mark invalid/stale — stamps `rejected_at` so the open-feedback walk treats it as terminal; the v4 `haiku_feedback_update` status-transition tool was REMOVED — closure runs through the fix-loop's terminal hat `haiku_feedback_advance_hat`, and a stale `haiku_feedback_update` call returns `feedback_update_removed_in_v4`), `haiku_feedback_delete`, `haiku_feedback_list`, `haiku_feedback_set_targets` / `haiku_feedback_set_severity` (classifier-hat backfill — write-once) | state-tools.ts |
 | Feedback severity | Quality Enforcement | `severity:` on feedback frontmatter — `blocker` \| `high` \| `medium` \| `low` (`FEEDBACK_SEVERITIES` in `state/schemas/feedback.ts`). **Required** on the agent-facing `haiku_feedback` create tool (review agents classify as they file). User/SPA findings land severity-less (the `writeFeedbackFile` HTTP path omits it) and the `classifier` fix-hat backfills via `haiku_feedback_set_severity` (write-once, `severity_already_set` on re-call). The fix-loop dispatches highest-severity-first: `feedbackSeverityRank` orders the initial pool in `collectFeedbackDispatches` (cursor.ts) AND the slot-replenishment pick in `pickUndispatchedFbBlock` (state-tools.ts) — unclassified ranks as `medium`. Engine-authored FBs set explicit severity at write time (gate-blockers → `blocker`, drift → `high`). Surfaced on the wire (`FeedbackSeveritySchema`) + SPA badge (`FeedbackItem.tsx`) | state/schemas/feedback.ts (`FEEDBACK_SEVERITIES`, `feedbackSeverityRank`), state-tools.ts (`haiku_feedback_set_severity`, `pickUndispatchedFbBlock`), orchestrator/workflow/cursor.ts (`collectFeedbackDispatches`) |
 | Severity-gated fix-loop activation | Quality Enforcement | A finding is **blocking** (triggers a fix wave AND holds the stage gate) iff it's unclassified (null severity — the classifier must run) OR `feedbackSeverityRank(severity) <= fixSeverityThresholdRank()`. Threshold defaults to `high` (blocker+high block; medium+low ride along), overridable via **`HAIKU_FIX_SEVERITY_THRESHOLD`** env var (read at call time). `collectFeedbackDispatches` returns null (no wave) unless some open FB is `inFlight` OR blocking — so a lone reviewer nit never spins a worktree; the stage just advances and the nit stays open + advisory. Once a blocker DOES open a wave, the whole open set dispatches together (severity-ordered), sweeping the ridealong lows in the same pass. Agent findings carry severity at creation, so a reviewer's stream of `low`s is non-blocking from tick 1 | state/schemas/feedback.ts (`fixSeverityThresholdRank`, `isFixBlockingSeverity`), orchestrator/workflow/cursor.ts (`collectFeedbackDispatches` wave-active gate) |
 | Feedback anti-churn (re-review) | Quality Enforcement | Two LIVE, reword-resistant mechanisms keep reviewers from re-litigating settled findings. **Preventive:** `buildExistingFeedbackBlock` hands every review/approval/intent-review subagent ALL prior findings on scope — incl. closed/rejected — now with `severity`, the closure_reply (`resolved: …`) and reject reason (`dismissed: …`), and tells it to audit the delta / respect the dismissal, not re-file. **Detective:** `detectSettledDuplicate` (create-time, Jaccard token-overlap ≥ 0.6 on same target_unit) returns a `duplicate_warning` on the `haiku_feedback` response when a finding restates an already-closed/rejected one — advisory (a bad fix can legitimately re-raise), pointing the agent at the prior resolution + `haiku_feedback_reject`. The dispatch_approval prompt also tells the reviewer its units came back because the WORK changed (only changed units re-sent — cursor filters `!approvals[role]`), so audit the fix delta. NOTE: the old `computeFeedbackSignature` stage-iteration loop detector is dormant in v4 (`appendStageIteration` never gets `feedbackTitles`); the per-FB bolt cap remains the hard backstop | _helpers.ts (`buildExistingFeedbackBlock`), state-tools.ts (`detectSettledDuplicate`, `findingSimilarity`), prompts/stage/approve/dispatch_approval/subagent.eta.md |

deploy/auth-proxy/README.md

@@ -0,0 +1,96 @@
+# auth-proxy
+
+Node 22 GCP Cloud Function (entry `authProxy`) live at `auth.haikumethod.ai`.
+Brokers GitHub/GitLab OAuth so neither the browse site nor the CLI ever holds the
+OAuth client secret. The secret lives only in Secret Manager and is read by this
+function.
+
+Two surfaces share one provider exchange (`src/providers.ts`):
+
+| Surface | Endpoints |
+| --- | --- |
+| Browse site (Phase 1) | `POST /github/token`, `POST /gitlab/token` — code→token exchange |
+| CLI device flow (Phase 2) | `POST /cli/start`, `POST /cli/complete`, `POST /cli/poll`, `POST /cli/refresh` |
+
+Phase 2 (`src/cli.ts`, `src/sessions.ts`) is wired into the same `authProxy`
+entry: `index.ts` calls `handleCliRoute(req, res)` first; it owns any `/cli/*`
+path and falls through to the existing browse-site routes otherwise.
+
+## CLI device flow
+
+```
+CLI                         auth-proxy                   browse site / provider
+ |  POST /cli/start ----------->|                                  |
+ |  <- { session_id,            | store PENDING (Firestore,        |
+ |       verification_url }     |   keyed by session_id + state)   |
+ |                              |                                  |
+ |  (open verification_url) --------------------------------------> human approves
+ |                              |        provider callback ----->  | /{provider}/callback
+ |                              | <- POST /cli/complete            |   exchanges code→token
+ |                              |    { state, access_token, ... }  |   then POSTs token here
+ |                              | flip session -> READY            |
+ |  POST /cli/poll ------------>|                                  |
+ |  <- { status: ready,         | release ONCE, mark consumed      |
+ |       access_token, ... }    |                                  |
+```
+
+### Endpoint contracts
+
+**`POST /cli/start` `{ provider, host? }`** → `{ session_id, verification_url, expires_in }`.
+Mints a 10-minute session + state, stores a PENDING record in Firestore keyed by
+`session_id`, and returns the `verification_url` the human opens. The URL targets
+the browse site's CLI authorize entry (`/oauth/cli/authorize`) carrying
+`provider`, `host`, `state`, and `authorize_via` (the resolved provider authorize
+endpoint). The browse site sends the human through the provider, and the existing
+`/{provider}/callback` completes the exchange. Host-aware for enterprise GitHub /
+self-managed GitLab.
+
+**`POST /cli/complete` `{ state, access_token, refresh_token?, expires_at?, scopes?, account?, host? }`** → `{ status: "ready" }`.
+**This is the single server endpoint the browse-site callback must POST to.** After
+the existing `/{provider}/callback` exchanges the authorization code for a token,
+it POSTs the captured token bundle here keyed by `state`. The session flips to
+`ready`. `scopes` accepts a string (space/comma separated) or an array. An
+enterprise `host` echoed here overrides the one captured at start.
+
+> If the browse callback is purely client-side and cannot exchange the code
+> server-side, it should instead POST the raw `code` to `/{provider}/token`
+> (Phase 1) to get the bundle, then POST that bundle to `/cli/complete`.
+
+**`POST /cli/poll` `{ session_id }`** →
+- `{ status: "pending" }` while awaiting approval,
+- `{ status: "ready", access_token, refresh_token?, expires_at?, scopes?, account, provider, host }` **exactly once**,
+- `{ status: "consumed" }` / `{ status: "expired" }` thereafter.
+
+The token is released a single time; the record is marked `consumed` and deleted
+so it can never be replayed.
+
+**`POST /cli/refresh` `{ provider, host?, refresh_token }`** → a fresh token bundle.
+Re-runs the provider exchange with `grant_type=refresh_token` using the held
+client secret. Persists nothing. Host-aware.
+
+## Session store
+
+Firestore collection `cli_sessions`. Every record carries `expires_at` (epoch
+seconds). Reads opportunistically delete expired records; a Firestore TTL policy
+on `expires_at` (see `deploy/terraform/modules/auth-proxy/firestore.tf`) is the
+backstop sweep.
+
+## Secrets / env
+
+| Env var | Source |
+| --- | --- |
+| `HAIKU_GITHUB_OAUTH_CLIENT_ID` / `HAIKU_GITHUB_OAUTH_CLIENT_SECRET` | Secret Manager (Phase 1) |
+| `HAIKU_GITLAB_OAUTH_CLIENT_ID` / `HAIKU_GITLAB_OAUTH_CLIENT_SECRET` | Secret Manager (Phase 1) |
+| `HAIKU_<PROVIDER>_OAUTH_CLIENT_ID__<HOST>` / ... | optional per-enterprise-host overrides |
+| `ALLOWED_ORIGIN` | CORS allowlist (Phase 1); first entry is the default browse origin |
+| `BROWSE_ORIGIN` | optional override for the `verification_url` origin |
+
+## Develop / test
+
+```sh
+npm install
+npm test       # tsc -> dist/ then node --test test/
+```
+
+Tests inject an in-memory session store and a fake `fetch`
+(`setSessionStore`, `setFetchImpl`), so no GCP credentials or network are needed.