engsys 1.0.0

package/core/workflows/implement-project-workflow.md

@@ -0,0 +1,190 @@
+# Implement Project Workflow
+
+Walk a tracker ProjectV2 board phase-by-phase, opening one PR per phase, pausing on material review findings. Builds on [agent-implementation-workflow.md](agent-implementation-workflow.md) — that doc still governs the per-phase mechanics (worktree, commits, local review, push, PR). This doc only adds the outer loop that reads the project board and decides what to do next.
+
+Invocation: `/implement-project <number>` (e.g. `/implement-project 21`).
+
+This workflow is the explicit authorization for the routine implementation cycle — see [agent-implementation-workflow.md § Start Command Authorization](agent-implementation-workflow.md).
+
+Board reads/writes (Phase/Priority/Owner/Status) and work-item operations go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) via its contract operations (`query-board`, `set-board-field`, `update-issue`, `comment-issue`, `link-pr`). The skill maps them onto the active backend; the GitHub `gh` / `gh api graphql` commands shown below are what it runs on a GitHub project. PR creation (`gh pr create`) and CI stay on GitHub.
+
+---
+
+## Preconditions
+
+The project **must** have a `Phase` single-select field with `P<n>: <name>` options (e.g. `P0: Foundation`, `P1: Core`). Without it, this command cannot batch.
+
+If the project lacks a `Phase` field, stop and report:
+
+> "Project #<num> has no `Phase` field. Run Jody first to retrofit (see [generate-project.md § 5](generate-project.md)), or implement issues one at a time via `/implement-issue <num>`."
+
+Do not attempt to invent phases on the fly — that's Jody's job and requires the design loop.
+
+---
+
+## Phase 0: Read the Board
+
+Use the issue-tracker skill's **`query-board`** operation to fetch the project's fields + items grouped by Phase. On GitHub the skill runs `gh api graphql` (the `github` MCP doesn't support ProjectV2), querying `projectV2(number:)` for: field definitions (`ProjectV2SingleSelectField { id name options }`) and items (`content { ... on Issue { number title state url } }` plus their `fieldValues`).
+
+```bash
+gh api graphql -f query='
+  query($owner: String!, $num: Int!) {
+    user(login: $owner) {            # or organization(login: $owner)
+      projectV2(number: $num) {
+        id title
+        fields(first: 30) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } }
+        items(first: 100) {
+          nodes {
+            id
+            content { ... on Issue { number title state url repository { nameWithOwner } } }
+            fieldValues(first: 20) {
+              nodes { ... on ProjectV2ItemFieldSingleSelectValue {
+                field { ... on ProjectV2SingleSelectField { name } } name } }
+            }
+          }
+        }
+      }
+    }
+  }' -f owner=<OWNER> -F num=<PROJECT_NUMBER>
+```
+
+Group items by their `Phase` value. Skip items whose `Status` is `Done` or whose underlying issue `state` is `CLOSED`. Within each phase, preserve original board order (use `Priority` as a tiebreaker when present).
+
+Phase order is determined by the numeric prefix in the `P<n>: …` option name. Treat `P-1` as before `P0`. Treat `P1.5` as between `P1` and `P2`.
+
+---
+
+## Phase 1: Pick the Next Batch
+
+The "next batch" is the lowest-numbered phase that still has at least one open issue.
+
+Print the operator a short plan before starting:
+
+```text
+Project #21 "Metrics v2 — KPI Dashboard"
+Next phase: P1: Schema & DTOs (4 issues open, 0 already merged)
+  - #1562 ...
+  - #1563 ...
+After this phase: P2: Settings UI (6 issues), P3: Hardening (2 issues)
+```
+
+Do not pause for operator approval — the slash command itself is the authorization. But if any pre-flight check is failing (auth scope, dirty main, uncommitted local changes), stop and report.
+
+---
+
+## Phase 2: Walk One Phase
+
+For the chosen phase, follow [agent-implementation-workflow.md](agent-implementation-workflow.md) end-to-end:
+
+1. Assign every issue in the phase to `@me` (skill `update-issue`).
+2. Create the worktree + branch: `agent/project-<num>-phase-<n>-<slug>` (e.g. `agent/project-21-phase-1-schema-dtos`), from `origin/main`.
+3. Set the board `Status` to `In Progress` on every item in this phase (skill `set-board-field`; on GitHub GraphQL `updateProjectV2ItemFieldValue`).
+4. Implement issues sequentially — **one commit per issue** with `(#<num>)` in the subject. Match the patterns of nearby code; do not refactor opportunistically.
+5. Run the project's pre-push gate / precheck (build, lint, unit tests, and path-gated checks for E2E, migrations, IaC, containers). See `/pre-push`.
+6. **Run a local code review against `origin/main` before push.** Fix Critical + Warning findings, re-run once to confirm clean, cap at ~2 passes.
+7. Push once, open one **draft** PR via `gh pr create --draft` (PR creation stays on GitHub), linking/closing each work item per the skill's `link-pr` operation (GitHub: `Closes #<num>` on its own line for every issue in the phase), then post the local review findings onto the work item via the skill's `comment-issue` operation (on GitHub, the marked PR comment).
+8. Once the local review is clean and the gate is green, mark **Ready for review** (`gh pr ready <n>`) to trigger any expensive ready-for-review CI matrix.
+
+---
+
+## Phase 3: Triage Review Findings, Then Decide
+
+Triage every finding from the Phase 2 local review (done before push). For each:
+
+- **Material**: a real bug, security risk, missed edge case, broken assumption, or anything that would change shipped behavior. Fix it before push; re-run the review.
+- **Cosmetic**: nit-level (naming, formatting, doc wording). Fix if the change is trivially safe and obviously correct; otherwise note it in the findings comment.
+- **Wrong**: the review misread the code. Note why in the findings comment.
+
+After resolving all findings, classify the _batch outcome_:
+
+| Outcome                                                    | Next action                                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| No material findings (clean or only cosmetic)              | Continue autonomously: jump to Phase 4, then loop back to Phase 1 for the next phase       |
+| ≥1 material finding fixed, review confirms clean on re-run | Continue autonomously                                                                      |
+| Material finding exposes a product/architecture decision   | **Stop**. Note it in the findings comment, report to the operator, do not start the next phase |
+| Review errored / couldn't run                              | **Stop**. Report to the operator with the PR URL and what's missing                        |
+
+"Pause on review findings" means: pause only when a finding is material AND it reveals something the operator should weigh in on. Cosmetic and trivial fixes do not stop the loop. Use judgment; when in doubt, pause.
+
+---
+
+## Phase 3.5: Objective Independent Review (before any merge)
+
+This is the merge gate the `/implement-project` command enforces. Once the phase PR is open and the implementer's local review is clean, the **orchestrator** (not the implementer) launches a *fresh, independent* reviewer subagent — general-purpose on **Opus**, with **no stake in the code**. It must:
+
+- re-run the full pre-push gate from scratch (confirm or refute the author's numbers);
+- verify **each** issue's acceptance criteria against the diff;
+- probe security/correctness;
+- hunt for regressions and reconciliation artifacts (duplicate/dead code, dropped work, stray exports).
+
+It ends with a decisive **`VERDICT: CLEAN`** (no Critical/Warning — safe to merge) or **`VERDICT: FINDINGS`** (severity-tagged, `file:line`). **Never merge a phase PR that has not passed this gate.**
+
+- **CLEAN** → safe to merge; proceed to Phase 4.
+- **FINDINGS** → route back to the implementer to fix + re-review, or **stop** and report if it exposes a product/architecture decision.
+
+---
+
+## Phase 4: Mark Phase Done, Loop
+
+After the PR is opened, the local review resolved, and the objective review returns CLEAN:
+
+1. Update the board `Status` to `Done` on every item in the completed phase (skill `set-board-field`) — **but only after the phase PR has merged** if the board has an "Auto-close issue" workflow enabled (otherwise `Status=Done` can prematurely close the linked issue while its PR is still a draft). If you need an interim state, use `Status: In Review`.
+2. Do **not** wait for the PR to merge before *starting* the next phase (each phase is a separate branch from `main`; rebasing across them after merges is normal) — unless the auto-close caveat above forces you to gate on merge.
+3. Loop to Phase 1 and pick the next unfinished phase.
+
+Stop when every phase has `Status: Done` (or `In Review`) on all its items. Report a one-line summary per phase with PR links.
+
+---
+
+## Stop Conditions (Always Pause)
+
+Stop and report to the operator if any of these fire mid-loop:
+
+- Pre-flight: missing `project` auth scope, dirty main, uncommitted local changes, `gh auth` failed.
+- A phase missing entirely (e.g. an issue in the project has no `Phase` value) — fix the project, don't paper over it.
+- An issue body too vague for safe implementation — file a clarification comment on the issue and stop.
+- The pre-push gate fails and the fix isn't obvious within ~15 min of work.
+- A material review finding requires product/architecture judgment.
+- Any destructive or non-routine action would be needed (force push beyond `--force-with-lease` on the agent branch, `git reset --hard`, removing unrelated files).
+- Three consecutive autonomous phases complete without a manual operator check-in — courtesy pause.
+
+---
+
+## What This Workflow Does Not Do
+
+- Does not merge PRs without a CLEAN objective review. Human-in-the-loop merges every batch (or the orchestrator only with explicit operator authorization).
+- Does not refactor existing code beyond the issues' scope.
+- Does not file new issues for out-of-scope work it discovers — that goes through the deferring-work flow as a Jody hand-off.
+- Does not skip the local review, even when phases are small.
+- Does not retry the same failing pre-push gate more than twice without escalating.
+
+---
+
+## Completion Report
+
+After the final phase (or after stopping), print:
+
+```text
+Project #<num> "<title>" — implementation summary
+
+Phases completed (PRs awaiting merge):
+  P0: <name>  #PR_A  (4 issues, review clean)
+  P1: <name>  #PR_B  (3 issues, 1 review fix applied)
+
+Phases remaining:
+  P2: <name>  (5 issues, not started)
+
+Stopped because: <reason or "all phases complete">
+Next action: <human merges P0/P1, then re-run /implement-project <num> for P2>
+```
+
+When the operator confirms the project's **last** PR has merged (all phases done), run the **Project Closeout Ceremony** — don't treat the completion report as the end. See [project-closeout-ceremony.md](project-closeout-ceremony.md) / `/project-closeout <num>`: verify all PRs merged, clean up this project's worktrees + branches, mine ALL marked review-findings PR comments (+ any static-analysis alerts) across the project for recurring mistake _families_, and memorialize durable lessons (repo `docs/agent-lessons/` for team-wide patterns; the engsys lessons-library for generalizable ones; personal memory for orchestration judgment).
+
+---
+
+## Cross-References
+
+- [agent-implementation-workflow.md](agent-implementation-workflow.md) — per-phase mechanics (worktree, commits, local review, PR)
+- [project-closeout-ceremony.md](project-closeout-ceremony.md) — the mandatory close-out after the last PR merges
+- [generate-project.md § 5](generate-project.md) — how the `Phase` field gets created in the first place
+- `CLAUDE.md` § Pre-push gate, § Git / PR conventions

package/core/workflows/issue-tracking.md

@@ -0,0 +1,89 @@
+# Issue Tracking Workflow
+
+How to investigate, file, and track tracker issues. Covers Bert's investigation + filing role. For implementation, see [agent-implementation-workflow.md](agent-implementation-workflow.md).
+
+This workflow relies on the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) for the actual issue reads/writes. It calls the skill's contract operations by name (`create-issue`, `list-issues`, `get-issue`, `update-issue`, `comment-issue`, `close-issue`, `link-pr`); the skill maps them onto the active backend (GitHub `gh` shown below, or Linear).
+
+---
+
+## Filing an Issue
+
+### 1. Investigate first
+
+Before creating an issue, locate the root cause — don't file on symptoms.
+
+- Search the codebase for the relevant code paths.
+- Read the actual files (don't guess from filenames).
+- Identify affected files with line numbers.
+- Check `docs/architecture/` for context.
+- Formulate the **correct, robust solution** — no workarounds, no "fix later" stubs.
+
+### 2. Create the issue body in tmp/
+
+**Never use HEREDOC or pipes for issue bodies. Always write to `tmp/` first** — this tmp/-file discipline is universal across trackers.
+
+Write the body with the Write tool → `tmp/issue-body-<slug>.md`, then create the issue via the issue-tracker skill's **`create-issue`** operation, passing the body file, title, and `<type>,<area>` label(s). On GitHub the skill runs:
+
+```bash
+# After tmp/issue-body-<slug>.md is written:
+gh issue create \
+  --title "<emoji> <Type>: <description>" \
+  --body-file tmp/issue-body-<slug>.md \
+  --label "<type>,<area>"
+
+rm tmp/issue-body-<slug>.md
+```
+
+### 3. The issue body must include
+
+- **Summary** — what's broken or what's being added.
+- **Root cause** (bugs) or **motivation** (features/enhancements).
+- **Affected files** with line numbers.
+- **Recommended solution** — the correct approach, not a workaround.
+- **Acceptance criteria** — testable, specific.
+- **Dependencies** — what must be done first.
+- **Effort** — S / M / L.
+- **Owner** — which agent persona.
+
+---
+
+## Title Format
+
+| Type           | Format                          |
+| -------------- | ------------------------------- |
+| Bug            | `🐛 Bug: <description>`         |
+| Feature        | `✨ Feature: <description>`     |
+| Enhancement    | `💄 Enhancement: <description>` |
+| Content        | `📄 Content: <description>`     |
+| Infrastructure | `🏗️ Infra: <description>`       |
+| Epic           | `Epic: <description>`           |
+
+---
+
+## Labels
+
+**Type** (pick one): `bug`, `feature`, `enhancement`, `content`, `infrastructure`.
+
+**Area** (pick one): the project's service/module areas (declared in `CLAUDE.md` / the project's label set).
+
+**Implementation-ready signal**: if the issue has clear acceptance criteria and no architectural ambiguity, note it in the body (e.g. "Self-contained, ready for implementation").
+
+---
+
+## Commit Message Format
+
+Reference the issue number in every commit on the implementing branch:
+
+```text
+feat(<scope>): add invite endpoint (#131)
+fix(auth): clean up placeholder user on login (#136)
+refactor(tenant): extract PLAN_LIMITS constant (#133)
+```
+
+---
+
+## When Implementation is Ready
+
+Follow [agent-implementation-workflow.md](agent-implementation-workflow.md) — worktree setup, verify, push, PR.
+
+Link/close the work item per the issue-tracker skill's **`link-pr`** operation. On GitHub, `Closes #<number>` in the PR body auto-closes the issue on merge; batch PRs must use one closing keyword per issue, one per line (a comma-list only closes the first). Other trackers close the work item per the skill. (PR creation itself stays on `gh pr create` — PRs are a code-host concern.)

package/core/workflows/project-closeout-ceremony.md

@@ -0,0 +1,77 @@
+# Project Closeout Ceremony
+
+Run this **every time a project's last PR merges** (the final phase of `/implement-project`, or any multi-PR effort that reaches "all phases merged"). It is the deliberate close-out: clean up the workspace, mine the review feedback for _recurring_ mistakes, and memorialize durable lessons so the next project starts smarter. The per-phase reflection line in `/implement-project` is a stub — this is the full ceremony.
+
+**Trigger:** the project's last open PR is MERGED (operator confirms, or `gh pr view` shows MERGED for every phase + follow-up PR). Also run it after a deliberate project-pause if no more phases are coming soon.
+
+Work-item reads (board status, finding records) and closing the board go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) via `list-issues` / `get-issue` / `query-board` / `close-board`. PR state, PR comments, and CI alerts stay on `gh` / GitHub (PRs are a code-host concern).
+
+**Why it exists:** review comments tend to get addressed inline, one at a time — yet a post-hoc mining pass routinely reveals several were the _same mistake family repeating across PRs_ (e.g. cross-method TOCTOU 4×, missing migration constraints 4×). Fixing inline isn't learning; generalizing the family into the checklist is. This ceremony forces that step instead of leaving it to chance.
+
+---
+
+## Step 1 — Verify everything merged
+
+- `gh pr view <n> --json state` for every project + follow-up PR → confirm all `MERGED` (squash-merge makes `git branch --merged` report 0; trust PR state, not merge-base).
+- Confirm the project board items are all `Done` / `In Review` (skill `query-board`). Any still `In Progress` → the project isn't closed; stop and report what's outstanding.
+
+## Step 2 — Clean up worktrees & branches
+
+- Remove **only this project's** worktrees: `git worktree remove <path> --force` (force handles leftover `node_modules`/`dist`/build output); then `git worktree prune`. Leave unrelated/locked worktrees alone.
+- Delete the merged local branches (`git branch -D <branch>`) and any dangling remote branches (`git push origin --delete <branch>` — UI-merged PRs don't auto-delete the remote branch).
+- `git checkout main && git pull --ff-only origin main` in the main checkout if it was parked on a feature branch.
+
+## Step 3 — Close the project board (when every issue is closed)
+
+Once Step 1 confirms the PRs are merged, close the project board — but **only if every issue on it is closed** — via the installed issue-tracker skill's `close-board` operation. Don't trust the board's own status field for this (on GitHub ProjectV2 the `item-list` `state` field is unreliable, often null/`?`); the skill gates on the **real** issue state, intersecting the board's issue numbers with the still-open issues and requiring the intersection to be empty.
+
+- **Gate:** if _any_ issue is still open, do **not** close the board — the project isn't actually done (same stop-and-report rule as Step 1). Closing a board over a live issue hides work.
+- Draft cards / notes (non-issue board items) do **not** gate the close — only real issues do.
+- Reversible: closing archives the board from the active view (GitHub: `gh project close --undo` reopens it; Linear: set the project state back). It never deletes the project or its items.
+
+The concrete commands live in the tracker skill's `close-board` (GitHub closes the ProjectV2; Linear marks the project Completed) — keep this step backend-agnostic.
+
+## Step 4 — Mine ALL review findings (the core of the ceremony)
+
+Don't rely on memory of what you fixed inline. The durable record is the marked review-findings comment each PR/work item posts after its local review (plus any static-analysis / security-scanning alerts CI still produces). Pull them from **every** work item in the project into one corpus via the skill's `list-issues` / `get-issue` operations. On GitHub the findings live as the marked comment on each PR — pull them directly with `gh`:
+
+```bash
+for pr in <all-project-PR-numbers>; do
+  gh pr view "$pr" --json comments \
+    --jq '.comments[] | select(.body | contains("<!-- local-review-findings -->")) | .body'
+done
+```
+
+(If a PR is missing its findings comment, note the gap — that PR went out without a recorded review, which is itself a process finding worth a lesson.)
+
+Then classify by **mistake family**, not by individual fix. For each family ask:
+
+- How many times did it recur, across how many distinct PRs? (≥2 PRs = a real pattern.)
+- Is it already in `docs/agent-lessons/` (or the engsys lessons-library)? If yes but it still recurred → the lesson exists but wasn't _applied at authoring time_; strengthen the trigger/check, don't just re-file.
+- Was it Critical/Major, or a nitpick? Prioritize the families that produced real bugs.
+
+## Step 5 — Memorialize (team-facing, in the repo)
+
+Automatic behaviors that apply to **anyone** in the repo go in the repo, not personal memory:
+
+- A **new, recurring** failure family → a new `docs/agent-lessons/<slug>.md` (trigger / failure mode / correct behavior / check / source).
+- A family already documented but still recurring → strengthen the existing lesson + add the new variant + a Start-of-PR-check line.
+- A reusable workflow/agent/command gap exposed by the run → update the relevant `.claude/workflows/*.md`, `.claude/agents/*.md`, or `CLAUDE.md`.
+- **Generalizable lessons** (not tied to this project's stack/domain) → also open a PR back to the engsys `lessons-library/` so other projects inherit them.
+- Commit on an `agent/project-<num>-reflection-lessons` branch → one docs PR. (Docs-only; if a local markdown-lint hook can't spawn, `--no-verify` is acceptable — the pre-push local review is the md backstop.)
+
+## Step 6 — Update personal memory (judgment/orchestration that's yours)
+
+Insights about _how you operate_ (orchestration cadence, verification habits, tooling gotchas) go in your memory dir, not the repo. Append to existing feedback files rather than creating duplicates; point them at the strengthened repo checklist rather than copying it.
+
+## Step 7 — Final report
+
+Print: PRs merged + their lesson contributions, worktrees/branches cleaned, **whether the project board was closed (or why not — which issues are still open)**, new/strengthened lessons (with the recurrence count that justified each), personal-memory updates, and any deferred follow-ups or operator-gated work still outstanding.
+
+---
+
+## Cross-References
+
+- [implement-project-workflow.md](implement-project-workflow.md) — the phase loop this closes out
+- [agent-implementation-workflow.md](agent-implementation-workflow.md) — where the marked review-findings comment is posted
+- `CLAUDE.md` § Memory & rules (repo-vs-personal split) and § Post-merge cleanup (worktree removal mechanics)

package/core/workflows/review-workflow.md

@@ -0,0 +1,266 @@
+# Review workflow (`/prep-review` family)
+
+Shared reference for the four slash commands that take a markdown proposal in the repo, get it in front of stakeholders via a shared drive (Docs/Slides) + chat, harvest feedback, and close the loop with an ADR.
+
+The intended audience is stakeholders who have the org's document drive + chat but **no repo access** — this workflow is the bridge. (Tooling: a **document-drive MCP** like Google Drive and a **chat MCP** like Slack. Tool names are project-defined; this doc is tool-agnostic.)
+
+## The four commands
+
+| Phase | Command                                        | What it does                                                                                                      |
+| ----- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| 1     | `/prep-review <path> [--as doc\|slides\|auto]` | Analyze source, pick surface, generate the review package, stage in `docs/reviews/<slug>/`, **gate on operator**. |
+| 2     | `/prep-review-publish <slug> [--channel #x]`   | Upload to the drive as a native Doc/Slides, post a chat announcement, persist IDs in `state.yaml`.                |
+| 3     | `/prep-review-collect <slug>`                  | Pull the current Drive doc body, render `feedback.md`, classify comments, **force operator resolution** on conflicts. |
+| 4     | `/prep-review-finalize <slug>`                 | Draft an ADR matching repo style, post a chat thread summary, promote the final spec to `docs/specs/`.            |
+
+Each command can be run in a fresh session — all state lives in the repo, not the conversation.
+
+## Directory layout
+
+```text
+docs/reviews/<slug>/
+├── state.yaml         # workflow state, IDs, phase — canonical
+├── source.md          # snapshot of the source markdown at /prep-review time
+├── package.md         # rendered version that went to the drive
+├── feedback.md        # comments + body diff, rendered at /prep-review-collect
+└── decisions.md       # operator decisions on each disagreement (challenge phase)
+```
+
+On `/prep-review-finalize`:
+
+- ADR → `docs/architecture/adr/NNN-<slug>.md` (next number in sequence)
+- Final reviewed spec → `docs/specs/<slug>.md`
+- `docs/reviews/<slug>/` stays as the audit trail (do **not** delete)
+
+## `state.yaml` schema
+
+```yaml
+slug: opportunity-led-pivot
+source: docs/specs/opportunity-led-pivot.md
+created_at: 2026-05-26T18:42:00Z
+phase: drafted # drafted | published | feedback-collected | finalized
+surface: doc # doc | slides
+surface_reasoning: |
+  One-paragraph explanation of why this surface was picked. Captured at
+  /prep-review time. Useful for audit and for forcing honesty when --as auto picks wrong.
+review_objective: |
+  Decide between (A) shipping now with stubs, or (B) holding until end-to-end.
+
+drive:
+  shared_drive_id: 0AHj... # the org shared drive
+  folder_id: 1AbCdEf... # the review subfolder
+  file_id: 1XyZ...
+  web_view_link: https://docs.google.com/document/d/1XyZ.../edit
+  uploaded_at: 2026-05-26T19:10:00Z
+
+chat:
+  channel_id: C0123ABCDEF
+  channel_name: content-review
+  message_ts: "1716750600.123456"
+  permalink: https://.../archives/C.../p1716750600123456
+  posted_at: 2026-05-26T19:12:00Z
+
+feedback:
+  collected_at: 2026-05-27T14:00:00Z
+  body_changed: true
+  classification:
+    clarification: 3
+    disagreement: 2
+    plus_one: 4
+    side_discussion: 1
+  unresolved_disagreements: 0 # must be 0 before finalize
+
+adr:
+  number: 21
+  path: docs/architecture/adr/021-opportunity-led-pivot.md
+  drafted_at: 2026-05-27T15:20:00Z
+
+final_spec:
+  path: docs/specs/opportunity-led-pivot.md
+```
+
+Only the fields relevant to the current phase need to be populated. Later commands read what they need.
+
+## Surface selection (`/prep-review` heuristic)
+
+Default `--as auto`. Recommend based on source shape; the operator confirms at the gate.
+
+| Signal in source                                          | Surface                                                       |
+| --------------------------------------------------------- | ------------------------------------------------------------- |
+| > 300 lines, multiple `##` sections, heavy prose          | **Doc**                                                       |
+| Heavy bulleted / outline structure, < 100 lines           | **Slides** (if "deck", "pitch", "presentation" in name or H1) |
+| Decision-focused, prose + 1–2 diagrams                    | **Doc**                                                       |
+| Pitch-shaped (problem → solution → ask, narrative arc)    | **Slides**                                                    |
+| Tied to an existing ADR pattern (spec / proposal / brief) | **Doc**                                                       |
+
+If ambiguous: prefer **Doc**. Suggesting mode + threaded comments beat slides for actual review work.
+
+## Drive folder convention
+
+Review docs land in a dedicated review folder inside the org shared drive — everyone on the team already has access, so no per-doc sharing is needed.
+
+- `/prep-review-publish` first searches the drive for the review folder by name (keep the query simple — some MCPs reject `trashed` / owner query fields). Shared-drive folders generally surface in search despite a misleading `canAddChildren: false` on the result.
+- Persist `drive.folder_id` (and `drive.shared_drive_id` from the parent metadata) to `state.yaml` after the first lookup — subsequent publishes skip the search.
+
+## Upload SOP — operator drag-drop, command picks up via folder polling
+
+`/prep-review-publish` generates the artifact locally with a descriptive filename derived from the source H1 (the drive uses the filename as the artifact's title). The operator drag-drops it into the review folder. The command **polls the folder** to detect the new file — no copy-paste of URLs required.
+
+**About the .docx-in-Docs mode**: the drive does **not** reliably auto-prompt to convert `.docx` → a native Doc (workspace-config dependent). That's fine — Docs supports full `.docx` editing (comments, suggesting, real-time collab). The file stays as `.docx` (mime `application/vnd.openxmlformats-officedocument.wordprocessingml.document`), comments get stored in `word/comments.xml` inside the file, and `/prep-review-collect` benefits because the file downloads as-is without an export step. The only cosmetic trade-off: the title in the drive UI shows the `.docx` extension.
+
+**The mechanics:**
+
+1. Verify the converter is on `PATH` (e.g. `pandoc`; bail with install instructions if missing).
+2. Derive the filename: source H1 with `:` swapped for `—`, plus the extension. Example: `Proposal: Review workflow` → `Proposal — Review workflow.docx`.
+3. Convert: `pandoc -f gfm -t docx docs/reviews/<slug>/package.md -o "docs/reviews/<slug>/<Derived>.docx"`.
+4. Baseline the folder (record existing file IDs).
+5. Print one clear instruction: "Drag `<path>` into `<folder URL>` — I'll detect it automatically."
+6. Poll the folder every ~7s for up to ~3 min, diff against the baseline.
+7. New file detected → fetch metadata for mime/title/web_view_link, persist to `state.yaml`, continue to the chat draft.
+8. Polling timeout → ask the operator to paste the URL as a fallback.
+
+**Why not fully automated** (recorded so we don't re-litigate it):
+
+- Creating the file from `text/markdown` / `text/html` — the drive keeps the source mime type; no native Doc conversion.
+- Creating from `text/plain` — auto-converts to a Doc, but the body shows literal `## heading` / `**bold**` chars. Rejected.
+- Creating a `.docx` via base64 upload — technically works but the base64 string round-trips through LLM context; impractically slow and token-heavy. Hard no.
+- Some chat workspaces gate canvas/upload features behind a paid tier.
+
+**If the MCP ever adds** an "upload from local path" drive tool, a "convert source X to native Doc" parameter, or the chat workspace upgrades — revisit. Until then, drag-drop is SOP.
+
+## Pulling comments back from the drive
+
+The drive stores comments as a **separate resource** from the doc body. The MCP may not expose a direct `list_comments` tool, but the download/export accepts an `exportMimeType` — and several export formats **preserve comments inline**:
+
+| Export MIME type                                                                  | Comments included?                         |
+| --------------------------------------------------------------------------------- | ------------------------------------------ |
+| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (.docx) | **Yes** — as native Word comments in OOXML |
+| `application/vnd.oasis.opendocument.text` (.odt)                                  | **Yes** — as ODF annotations               |
+| `text/html`                                                                       | **Yes** — typically as footnotes / sidebar |
+| `application/pdf`                                                                 | No (export drops them)                     |
+| `text/plain` / `text/markdown`                                                    | No                                         |
+
+**Primary path** (`/prep-review-collect`):
+
+1. Export as `.docx` (the `wordprocessingml.document` export MIME type).
+2. Decode the base64 to `docs/reviews/<slug>/drive-export.docx`.
+3. Parse the `.docx` (it's a zip; `word/comments.xml` holds comment text + author + ids; `word/document.xml` holds the anchors). Use a docx skill or unzip+XML directly.
+4. Extract: comment text, author, anchor selection, resolved state (if present).
+5. Also pull current body text from the .docx for the diff against `package.md`.
+
+**Known caveat — resolved comments**: the drive's `.docx` export typically includes **open** comments but may omit **resolved** ones. If the operator's review pattern resolves comments before collect runs, those are effectively lost to the export. Mitigations: ask reviewers to leave comments open until collect runs (note this in the announcement); for any "I resolved that already" comments, fall back to operator-paste during classification.
+
+**Fallback path** — if export parsing fails or yields nothing useful, ask the operator to paste comment text directly.
+
+## Comment classification (`/prep-review-collect`)
+
+For every comment / suggestion, classify as one of:
+
+- **`clarification`** — reviewer asks a question or requests a tweak; incorporated into the next draft.
+- **`disagreement`** — reviewer pushes back on a decision; **the operator must explicitly choose** accept / reject / explore-3rd-option before finalize. Recorded in `decisions.md`.
+- **`plus_one`** — endorsement / "looks good"; tally only.
+- **`side_discussion`** — adjacent thought, not blocking; surfaces in finalize as a "follow-ups" section.
+
+`unresolved_disagreements > 0` in `state.yaml` **blocks** `/prep-review-finalize`. Run collect again after operator resolution.
+
+## Chat post conventions
+
+Channel default: the project's review channel (override with `--channel`).
+
+First post (publish phase):
+
+```text
+📋 *Review needed:* <title>
+
+<2–4 sentence summary of the proposal — what's being decided>
+
+*Review objective:* <review_objective from state.yaml>
+
+*How to weigh in:* Open the doc and leave inline comments / suggestions. Reactions on this message also count. _Please leave comments open (don't resolve them) until I collect feedback — resolved comments may not survive the export._
+
+📎 <Drive link>
+```
+
+Finalize-thread reply:
+
+```text
+✅ *Decision recorded:* <ADR title>
+
+<2–3 sentences: decision, key consequence>
+
+📄 ADR: `docs/architecture/adr/NNN-<slug>.md` (in repo)
+📄 Final spec: `docs/specs/<slug>.md`
+
+Thanks for the feedback — N comments incorporated, M side-discussions tracked as follow-ups.
+```
+
+Use the draft-message tool for both — let the operator review before it ships.
+
+## Commits
+
+Per `CLAUDE.md` — never auto-commit. Each command **stages files and proposes a commit message**; the operator runs the commit. Suggested messages (add a `(#issue)` suffix if the project requires it):
+
+- After `/prep-review`: `docs(reviews): draft review package for <slug>`
+- After `/prep-review-publish`: `docs(reviews): publish <slug> review package (Drive + chat)`
+- After `/prep-review-collect`: `docs(reviews): collect feedback for <slug>`
+- After `/prep-review-finalize`: `docs(adr): ADR-NNN <title>` + `docs(specs): finalize <slug>`
+
+## Idempotency and re-runs
+
+- All commands check `state.yaml.phase` first. Running out-of-order → bail with the right next step.
+- `/prep-review` on an already-drafted slug → require `--force` (overwrites `source.md`, `package.md`; keeps Drive/chat state if present).
+- `/prep-review-publish` after a successful publish → no-op + report existing links. `--republish` deletes the old Drive file and posts a new chat message (use sparingly; resets comments).
+- `/prep-review-collect` is naturally idempotent — re-running re-renders `feedback.md` from the current Drive state.
+- `/prep-review-finalize` is idempotent on the ADR file (warns if the ADR number was already claimed).
+
+## ADR style (for finalize)
+
+Match the established shape — read 2–3 recent ADRs from `docs/architecture/adr/` first. The pattern:
+
+```markdown
+# ADR-NNN: <title>
+
+|             |                              |
+| ----------- | ---------------------------- |
+| **Status**  | Proposed                     |
+| **Date**    | YYYY-MM-DD                   |
+| **Context** | 1–2 sentences + link to spec |
+| **Related** | links to prior ADRs / issues |
+
+---
+
+## Context
+
+<3–5 bullets of the situation>
+
+## Decision N — <sub-decision title>
+
+<the decision; sometimes a table>
+
+## Consequences
+
+- **Easier:** ...
+- **Harder:** ...
+```
+
+Status defaults to `Accepted` on finalize (by the time finalize runs, the operator has incorporated feedback and resolved disagreements via `decisions.md`). The operator can downgrade to `Proposed` manually to leave the decision open.
+
+## Failure paths
+
+| Failure                               | Action                                                                                            |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Drive auth lapsed                     | Report clearly, instruct the operator to re-auth the MCP; do not write partial state              |
+| Chat post fails after Drive upload    | Persist Drive IDs to `state.yaml` (so we don't re-upload); retry chat via `/prep-review-publish`  |
+| Source markdown missing               | Bail immediately, no state changes                                                                |
+| `docs/reviews/<slug>/` already exists | `/prep-review` requires `--force`; other commands proceed (they expect it)                        |
+
+## Why four commands, not one
+
+Each phase has a natural pause and a different operator decision:
+
+1. **draft → publish**: "Does the package look right? Is this the right surface?"
+2. **publish → collect**: wait for humans to review (hours to days).
+3. **collect → finalize**: "I've thought about the disagreements. Here's my call."
+4. **finalize**: emit the durable artifacts.
+
+Cramming this into one command either skips gates or holds open a long-running session.