# Plan 6 Deferred Parity Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.

**Goal:** Complete Plan 5 deferred parity: PR/MR review write actions (summary/inline comments, approve, merge), `my-pull-request batch-review`, and `report generate` (AI via host-agent turns).

**Architecture:** Port CLI modules by hand into host-agent (no shared package). Reuse `src/pullRequest/http.ts`. After a successful review turn, call `applyPullRequestReviewActions` (ported gate + write APIs). Batch-review reuses list + serial orchestrator + the same review+actions path with turn/`needs_host_agent` resume. Report ports local reporting; AI path uses `HostAgentClient.complete` with `purpose: "report"`.

**Tech Stack:** TypeScript 5.6, Node 20+, `node:test`, existing HostAgentClient / SessionStore / review modules.

**Spec:** `docs/superpowers/specs/2026-08-12-host-agent-plan6-deferred-parity-design.md`  
**Reference CLI (read-only):** `/Users/nietao/VSCode-plugins/smart-commit-cli` @ package `peerReference.cliVersion`

**Global constraints:**
- Do not modify `smart-commit-cli`
- Zero LLM HTTP in host-agent
- Keep listApi concurrency/behavior identical to CLI
- No hybrid / chunked / correction unless required for write-path parity

---

## File structure

| Path | Responsibility |
|------|----------------|
| `src/pullRequest/reviewActions.ts` | Port write APIs + `getCurrentUser` / list comments from CLI `reviewApi.ts` |
| `src/pullRequest/reviewComment.ts` | Port summary/inline body builders + markers |
| `src/pullRequest/reviewGate.ts` | Port publish gates |
| `src/pullRequest/mergeGate.ts` | Port merge eligibility |
| `src/pullRequest/applyReviewActions.ts` | Post-turn publish/approve/merge orchestration (CLI `reviewWorkflow` publish segment) |
| `src/commands/pullRequestReview.ts` | Call apply after turn; honor dry-run + new config fields |
| `src/config/*` | Extend `pullRequestReview.*` + `myPullRequest.batchReviewKinds` + `passHistory` / report fields as needed |
| `src/pullRequest/serialReviewOrchestrator.ts` | Port serial batch loop |
| `src/pullRequest/batchReviewSummary.ts` | Port exit code + summary helpers |
| `src/commands/myPullRequestBatchReview.ts` | Command + resume semantics |
| `src/reporting/*` + `src/commands/reportGenerate.ts` | Port report generate |
| `src/cliApp.ts` / `src/contracts.ts` | Wire commands + schemas |
| Tests | mocked fetch + command e2e |
| Docs | parity-matrix, README, roadmap |

---

### Task 1: Review write APIs + comment/gate helpers

**Files:**
- Create: `src/pullRequest/reviewActions.ts`, `reviewComment.ts`, `reviewGate.ts`, `mergeGate.ts`
- Modify: `src/pullRequest/http.ts` only if encode helpers missing (prefer reuse existing exports)
- Test: `src/test/reviewActions.test.ts`, `src/test/reviewComment.test.ts`

- [x] **Step 1: Failing tests** for `createSummaryComment` (GitHub issues comments POST + GitLab notes POST) and `approvePullRequest` with `withMockedFetch`; unit test `buildSummaryCommentBody` includes marker `<!-- smart-commit-pr-review -->`.

- [x] **Step 2: Port** from CLI `reviewApi.ts` only the write/list helpers needed: `getCurrentUser`, `listSmartCommitReviewComments`, `createSummaryComment`, `updateSummaryComment`, `listInlineCommentBodies`, `createInlineComment`, `approvePullRequest`, `mergePullRequest`, `hasPullRequestApprovalFromUser`. Import HTTP from `./http`. Do not re-port `getPullRequestDetails` / `getPullRequestDiff` (already in `reviewFetch.ts`).

- [x] **Step 3: Port** `reviewComment.ts`, `reviewGate.ts`, `mergeGate.ts` from CLI with minimal adaptation (types from host-agent review types).

- [x] **Step 4: `npm test` green; commit** `feat: add PR/MR review write APIs and comment gates`

---

### Task 2: Config fields for review publish

**Files:**
- Modify: `src/config/schema.ts`, `defaults.ts`, `load.ts`, `contracts.ts`
- Test: extend `src/test/configResolve.test.ts`

- [x] **Step 1: Failing test** — defaults include `summarySeverities: ["P0","P1","P2"]`, `commentSeverities: ["P0","P1"]`, `skipSummaryOnPass: true`, `skipCommentOnPass: true`; file config can override.

- [x] **Step 2: Implement** parsers + merge + validate (non-empty severity arrays when present; values in P0–P3).

- [x] **Step 3: Commit** `feat: extend pullRequestReview publish config fields`

---

### Task 3: Wire publish/approve/merge into `pull-request review`

**Files:**
- Create: `src/pullRequest/applyReviewActions.ts`
- Modify: `src/commands/pullRequestReview.ts`
- Test: `src/test/applyReviewActions.test.ts`, update `src/test/pullRequestReview.test.ts`

**Flow after successful review turn:**
1. Build API input from platform + number + authToken + timeout (30_000)
2. If dry-run → actions attempted=false/performed=false with CLI-like dry-run details; no HTTP writes
3. Else `applyPullRequestReviewActions({ details, reviewResult, config.pullRequestReview, … })`
4. Merge returned action fields into command payload; append warnings

- [x] **Step 1: Failing e2e** — mocked fetch review + summary POST → `summaryCommentAction` is `created` (not skipped) when score fails threshold or when skipSummaryOnPass=false; dry-run leaves actions skipped/not performed.

- [x] **Step 2: Implement `applyReviewActions.ts`** by porting the publish/approve/merge section of CLI `reviewWorkflow.ts` (not the LLM `runReviewExecution` part).

- [x] **Step 3: Wire command**; remove deferred skipped stubs.

- [x] **Step 4: `npm test` green; commit** `feat: publish review comments and approve/merge via platform API`

---

### Task 4: `batchReviewKinds` + serial orchestrator

**Files:**
- Modify: `src/config/*` for `myPullRequest.batchReviewKinds`
- Create: `src/pullRequest/batchReviewSummary.ts`, `serialReviewOrchestrator.ts`
- Test: `src/test/serialReviewOrchestrator.test.ts`

- [x] **Step 1: Failing tests** — orchestrator reviews items in order; on abort sets `cancelledRemaining`; on throw records `error` outcome.

- [x] **Step 2: Port** CLI modules; adapt `reviewOne` callback type to host-agent config (no `ReviewProvider`).

- [x] **Step 3: Commit** `feat: add batch review orchestrator and batchReviewKinds config`

---

### Task 5: `my-pull-request batch-review` command

**Files:**
- Create: `src/commands/myPullRequestBatchReview.ts`
- Modify: `src/cliApp.ts`, `src/contracts.ts`, help text
- Test: `src/test/myPullRequestBatchReview.test.ts`

**Resume rule (locked):**
- Batch uses a session; when `reviewOne` throws `NeedsHostAgentError`, command exits `needs_host_agent` with that session/request paths.
- Persist batch progress in session sidecar or reuse bridge-state pattern: store listed item URLs + outcomes so far under session dir (`batch-review-state.json`).
- On resume with `--session`, skip completed URLs and continue from first pending item.

- [x] **Step 1: Failing tests** — empty list → ok; auth missing → CONFIG_ERROR; all passed → ok; any not_passed → blocked exit; account+remoteHost skips git; needs_host_agent then resume completes.

- [x] **Step 2: Implement command** mirroring CLI `myPullRequestBatchReview.ts` + host-agent resolve/redact patterns from `myPullRequestList.ts`.

- [x] **Step 3: Wire CLI**; update README + parity-matrix row.

- [x] **Step 4: Commit** `feat: add my-pull-request batch-review`

---

### Task 6: `report generate`

**Files:**
- Create: `src/reporting/` (port needed files from CLI `src/reporting`), `src/commands/reportGenerate.ts`, optional `src/passHistory/` read helpers
- Modify: config for `passHistory` subset; `cliApp.ts`; contracts
- Test: `src/test/reportGenerate.test.ts`

- [x] **Step 1: Failing tests** — local render mode writes report file without turn; invalid period → CONFIG_ERROR.

- [x] **Step 2: Port local report path** (facts + render + write).

- [x] **Step 3: AI path** via `HostAgentClient.complete` (`purpose: "report"`); needs_host_agent + resume; fallback local only if CLI does the same.

- [x] **Step 4: Wire CLI + docs; commit** `feat: add report generate with host-agent turns`

---

### Task 7: Docs + roadmap closeout

**Files:**
- Modify: `docs/parity-matrix.md`, `docs/superpowers/plans/2026-08-10-host-agent-roadmap.md`, README status table, Plan 5 deferred notes

- [x] **Step 1: Update matrix** — batch-review / report / review write actions marked aligned (note remaining intentional gaps: no chunked/hybrid).

- [x] **Step 2: Roadmap** — Plan 6 complete; deferred list cleared.

- [x] **Step 3: Commit** `docs: mark Plan 6 deferred parity complete`

---

## Acceptance

- `npm test` all green; no real network in CI
- `pull-request review` can create/update summary, post inline, approve, merge (mocked fetch); dry-run does not write
- `my-pull-request batch-review` lists then serially reviews with turn resume
- `report generate` local + AI-turn paths work
- Zero LLM HTTP; zero changes to `smart-commit-cli`
- Parity matrix §4 rows no longer “未跟进” for these three

## Spec coverage

| Spec § | Task |
|--------|------|
| 6.1 write APIs + gates | 1–3 |
| 6.1 config severities | 2 |
| 6.2 batch-review | 4–5 |
| 6.3 report | 6 |
| Docs / success criteria | 7 |