@harness-engineering/cli 4.0.0 → 4.1.0

package/dist/agents/skills/cursor/product-advisor/SKILL.md

@@ -0,0 +1,202 @@
+# Product Advisor
+
+> Turn a client diagram + conversation into a Business Requirements Document and a resolved gap-list, then seed the harness pipeline. The pre-inception front door: gather requirements with AI, feed them in, and let the existing flow continue as it does today.
+
+## When to Use
+
+- At the **inception** of a client engagement, when a solution architect / pre-sales engineer has a rough idea, a diagram, and conversation notes but no structured requirements yet.
+- When you want to turn "a diagram and some notes" into a client-legible BRD plus an explicit list of what is still unknown.
+- When the output should **seed the roadmap** (many work items) and ground the engagement's strategy — not produce a single spec.
+- NOT for authoring a spec/proposal — that is `harness-brainstorming`'s job. Product Advisor stops at BRD + roadmap seeding.
+- NOT for writing or updating `STRATEGY.md` directly — that is `harness-strategy`'s job. This skill only reads strategy and _offers_ to seed it.
+- NOT for internal feature work where the requirements already live in the codebase or an existing spec — go straight to `harness-brainstorming` or `harness-planning`.
+
+## Process
+
+### Iron Law
+
+**Every gap is either resolved in the interview or shipped as an explicit client-facing question — never silently dropped.** A BRD that hides what it does not know is worse than no BRD: it launders assumptions into requirements. If you cannot answer a gap and did not surface it in `gaps.md`, STOP and add it.
+
+---
+
+### Phase 1: INGEST — Gather the Raw Material
+
+1. **Resolve the engagement slug.** From the `engagement` argument, or ask the SA for a short name. This sets `docs/inception/<engagement>/` and the roadmap milestone `Inception: <engagement>`.
+2. **Ingest the diagram.** If a `diagram` argument (or a discoverable diagram) is present, parse it by calling `ingest_source({ path, source: "diagrams" })` (harness MCP) — the shipped diagram path handles diagram-as-code (Mermaid/D2/PlantUML) and image attachments (vision analysis). Then read the extracted entities and flows back via `gather_context` / `query_graph`. **Do not build a new parser** — reuse `ingest_source`.
+3. **Soft-degrade when parsing is unavailable.** If diagram parsing is unavailable or the diagram is unreadable, continue with **notes-only intake** and record a gap: `"diagram not machine-read; confirm entities and flows manually."` Do not fail.
+4. **Ingest the notes.** Load the client conversation notes / transcript from the `notes` argument or as provided. Call `gather_context` to pull any existing project/business knowledge that grounds the domain.
+5. **Normalize into intake.** Produce a structured intake: `{ entities[], flows[], notes }`. State the entities and flows back to the SA in one short summary and confirm before drafting.
+
+---
+
+### Phase 2: DRAFT-BRD — Synthesize the First Draft
+
+1. **Write the BRD** to `docs/inception/<engagement>/brd.md` with these sections, each present even if thin: _Context, Business Objectives, Scope, Functional Requirements, Non-Functional Requirements, Assumptions, Constraints, Out-of-Scope, Open Questions._
+2. **Phrase behavioral requirements with EARS patterns:**
+   - Event-driven: "When [trigger], the system shall [response]."
+   - Unwanted: "If [condition], then the system shall not [behavior]."
+3. **Tag gaps against the fixed BRD completeness rubric** (see below). Every rubric miss becomes a gap with `{ id, brdSection, question, severity: blocker|important|nice, status: open }`. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.
+4. **Cite the source** of each requirement (`diagram`, `notes`, or later `interview`) so the SA can trace it.
+
+#### BRD completeness rubric
+
+- Each BRD section is non-empty and internally consistent.
+- Every diagram entity and flow maps to ≥1 functional requirement (or to an explicit gap).
+- Every functional requirement has an **actor + trigger + response**.
+- Every non-functional requirement is measurable (a number or a testable condition), else it is a gap.
+- Scope and Out-of-Scope do not contradict each other.
+
+---
+
+### Phase 3: GAP-INTERVIEW — Resolve What You Can
+
+1. **Ask ONE question at a time, in plain text.** Order the gap queue by severity (`blocker` → `important` → `nice`). Ask the highest-severity open gap first, wait for the answer, then continue.
+
+   **Ask directly in your reply. Do NOT route questions through `emit_interaction`, `AskUserQuestion`, or any tool** — those do not reliably surface the question to the human. Plain text in your own message is the only channel that reaches the SA across every client (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present each gap as a scannable multiple-choice table where options exist, and state a recommendation:
+
+   ```markdown
+   ### Gap G3 (blocker): What authenticates end users?
+
+   |             | A) Client SSO (SAML/OIDC) | B) Local accounts | C) Unknown — ask client |
+   | ----------- | ------------------------- | ----------------- | ----------------------- |
+   | **Implies** | IdP integration work      | Password storage  | Blocks scoping          |
+   | **Risk**    | Depends on client IdP     | Security burden   | —                       |
+
+   **Recommendation:** likely A given the enterprise diagram — confirm the IdP.
+   ```
+
+2. **Fold each answer back into the BRD.** Update the relevant section, add the requirement (source: `interview`), and move the gap `open → resolved` with the captured answer.
+3. **Mark unresolvable gaps client-facing.** If the SA cannot answer (only the client can), keep the gap `open` and phrase it as a question to ask the client.
+4. **Stop when the queue is drained** — every gap is either `resolved` or `open` (client-facing). Do not loop past a drained queue inventing new questions.
+
+---
+
+### Phase 4: FINALIZE — Ship and Hand Off
+
+1. **Write `gaps.md`** to `docs/inception/<engagement>/gaps.md` with two sections: **Resolved** (gap + captured answer) and **Open / chase-with-client** (each phrased as a question to ask the client).
+2. **Offer a STRATEGY.md seed.** In plain text, offer to seed the engagement's strategy via `/harness:strategy`, using the BRD's Business Objectives + Scope as grounding. **Never write `STRATEGY.md` yourself** — dispatch `harness-strategy` if the SA accepts.
+3. **Fan out into roadmap candidates.** Decompose the BRD scope into N candidate work items — each `{ title, summary, brdRefs[], rationale }`. Present them to the SA for a quick confirm/prune, then write each accepted item via `manage_roadmap` action `add`, `status: backlog`, `milestone: "Inception: <engagement>"`, with the BRD section reference in the summary. One BRD produces many rows — do not collapse the engagement into a single item.
+4. **Emit the handoff.** Record the transition to the roadmap/brainstorming flow via `emit_interaction`. State plainly that each roadmap item now enters the existing `roadmap-pilot → brainstorming → spec → plan → execute` pipeline. **Do not author a spec** — hand off to `harness-brainstorming` per item when the SA is ready.
+
+---
+
+## Harness Integration
+
+- **`gather_context`** — Phase 1: pull existing project/business knowledge to ground the domain.
+- **`ingest_source` (`source: "diagrams"`)** — Phase 1: parse diagrams (diagram-as-code + image vision) into the knowledge graph; read the extracted entities/flows back via `gather_context` / `query_graph`. Never reimplement the parser.
+- **`read_strategy`** — Phase 4: read `STRATEGY.md` (if present) to align the BRD; never write it.
+- **`manage_roadmap` (action `add`)** — Phase 4: create backlog roadmap rows from the BRD fan-out.
+- **`emit_interaction`** — Phase 4: record the handoff transition to the roadmap/brainstorming flow.
+- **`harness validate`** — After finalize: verify artifact placement and project health.
+
+## Success Criteria
+
+- Running the skill with a diagram + notes produces `docs/inception/<engagement>/brd.md` with all required sections, none empty.
+- Every diagram entity/flow maps to ≥1 BRD requirement or to an explicit gap.
+- `gaps.md` exists and separates **Resolved** from **Open/client-facing**; every open gap is phrased as a question.
+- The gap interview asked one question at a time and folded each answer into the BRD (resolved gaps moved `open → resolved`).
+- `finalize` created ≥1 candidate roadmap row via `manage_roadmap`, each linking back to a BRD section.
+- `finalize` offered a `STRATEGY.md` seed via `/harness:strategy` and did not write `STRATEGY.md` directly.
+- Behavioral functional requirements use EARS phrasing.
+- When diagram parsing was unavailable, the skill degraded to notes-only and recorded a gap rather than failing.
+- No spec/proposal was authored by this skill.
+
+## Examples
+
+### Example: retail loyalty engagement from a diagram + call notes
+
+**INGEST:**
+
+```
+engagement: acme-loyalty
+diagram: architecture.mmd (Mermaid) → parsed: entities [POS, Loyalty API, CRM, Rewards Engine], flows [POS→Loyalty API→CRM]
+notes: kickoff-call.md → loaded. gather_context: existing "loyalty" business facts surfaced.
+Confirmed entities/flows with SA. Proceed.
+```
+
+**DRAFT-BRD:** Wrote `docs/inception/acme-loyalty/brd.md`. 9 sections. Tagged 6 gaps:
+G1 (blocker) no auth model; G2 (blocker) Rewards Engine has no defined trigger; G3 (important) no NFR for POS latency; G4 (important) CRM data residency unknown; G5 (nice) reporting cadence; G6 (blocker) "Rewards Engine" entity maps to no requirement.
+
+**GAP-INTERVIEW:**
+
+```
+G1: "What authenticates end users? A) Client SSO B) Local C) Unknown" → SA: "A, Okta OIDC." → folded in.
+G2: "When does the Rewards Engine fire? A) On transaction B) Batch nightly C) Unknown" → SA: "A." → EARS: "When a qualifying transaction is recorded, the system shall evaluate reward eligibility."
+G3: "POS latency budget?" → SA: "client must confirm." → kept open, client-facing.
+G4: "CRM data residency?" → SA: "client must confirm." → kept open, client-facing.
+G6: resolved by G2. G5: SA: "monthly." → folded in.
+```
+
+**FINALIZE:**
+
+```
+Wrote gaps.md → Resolved: G1,G2,G5,G6 | Open/client-facing: G3 (latency), G4 (residency).
+Offered STRATEGY.md seed → SA accepted → dispatched /harness:strategy.
+Roadmap fan-out (milestone "Inception: acme-loyalty", backlog):
+  - "POS ↔ Loyalty API integration" (brd: Scope, FR-1)
+  - "Rewards Engine eligibility rules" (brd: FR-4)
+  - "Okta OIDC authentication" (brd: FR-2)
+  - "CRM sync + residency compliance" (brd: FR-5, NFR-2)
+Emitted handoff → each item enters roadmap-pilot → brainstorming. No spec authored.
+```
+
+## Gates
+
+- **No dropped gaps.** Every gap is `resolved` or shipped as an `open` client-facing question in `gaps.md`. A gap that is neither = Iron Law violation; stop and fix.
+- **No guessed requirements.** A BRD section that is unknown is a gap, not a place to invent facts. Fabricating a requirement to fill a section is a hard stop.
+- **No writing `STRATEGY.md`.** This skill reads strategy and offers to seed it via `/harness:strategy`. Writing `STRATEGY.md` directly = gate violation.
+- **No authoring specs.** This skill stops at BRD + roadmap seeding. Writing a `proposal.md` = gate violation; hand off to `harness-brainstorming`.
+- **No single-item collapse.** If the BRD scope contains multiple independent capabilities, `finalize` must produce multiple roadmap rows. Collapsing an engagement into one row defeats the fan-out.
+- **No hard failure on missing diagram.** Absent/unreadable diagram → notes-only + recorded gap. Aborting the run because a diagram would not parse = gate violation.
+
+## Escalation
+
+- **Diagram parses but entities contradict the notes:** Do not silently pick one. Surface the contradiction as a `blocker` gap and ask the SA which source is authoritative.
+- **The SA cannot answer any blocker gap:** The engagement is too early for a BRD. Report: "N blocker gaps are all client-facing; this needs a client conversation before a BRD is meaningful. Ship the gap-list as a client questionnaire and pause."
+- **Scope keeps expanding during the interview:** Stop. Report: "Scope has grown beyond the ingested material. Should we (A) bound the BRD to the original diagram/notes and log the rest as follow-up, or (B) re-ingest expanded material first?"
+- **`manage_roadmap` is unavailable:** Write the candidate items into `gaps.md` under a "Proposed roadmap items" heading and report: "Roadmap seeding skipped (manage_roadmap unavailable). Re-run finalize when MCP is restored."
+- **More than ~15 gaps after drafting:** The intake is too raw. Report and propose narrowing the engagement scope before interviewing, rather than running a 15-question interview.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                 | Reality                                                                                                                                                                              |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The diagram implies the auth model, so I'll just write it as a requirement"    | An implication is not a confirmation. Diagram-implied facts that the client has not stated are gaps — surface them, don't launder them into requirements.                            |
+| "This gap is minor, I'll leave it out of gaps.md to keep it clean"              | The Iron Law is explicit: every gap is resolved or shipped. A gap you drop is an assumption the client discovers in production. `nice`-severity still ships.                         |
+| "I have enough to draft a proposal, I'll just write the spec too"               | Product Advisor stops at BRD + roadmap seeding. Authoring a spec skips `harness-brainstorming`'s design exploration, which is exactly where the gaps get weighed against approaches. |
+| "The BRD's objectives are clear, I'll seed STRATEGY.md directly to save a step" | This skill never writes `STRATEGY.md`. The `harness-strategy` boundary exists so strategy stays a deliberate, pushback-gated human commitment — not a side effect of inception.      |
+| "The engagement is really one big project, I'll make one roadmap row"           | A BRD describes a solution scope that fans out into many work items. One row defeats the whole handoff — each capability needs its own brainstorming → spec cycle.                   |
+| "The diagram won't parse, so I can't run — I'll abort"                          | Notes-only intake is a first-class path. Degrade, record the diagram as a gap, and continue. Aborting throws away the requirements the notes already contain.                        |
+
+## Red Flags
+
+| Flag                                                                             | Corrective Action                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll fill the empty NFR section with reasonable defaults"                       | STOP. Unknown NFRs are gaps. Defaults you invent become requirements no one agreed to. Tag it as a gap and ask.                                                                                             |
+| "The interview is dragging; I'll batch the remaining questions into one message" | STOP. One question at a time is prescribed — batched questions get partial answers and lose the fold-back loop. Ask the next single highest-severity gap.                                                   |
+| "The SA said 'just make sensible assumptions'"                                   | STOP. Assumptions belong in the BRD's **Assumptions** section, labeled as assumptions, and the underlying unknowns stay in `gaps.md` as client-facing. Do not convert assumptions into silent requirements. |
+| `// TODO: confirm with client` left inside brd.md functional requirements        | STOP. Confirmation-needed items are gaps, not requirements. Move them to `gaps.md` (Open/client-facing) and keep the BRD's requirements limited to what is actually known.                                  |
+
+---
+
+<!--
+## Skill Test Scenarios
+
+### Scenario 1: Gate — "No dropped gaps"
+Input: Drafting produces a `nice`-severity gap (reporting cadence) the SA never answers and cannot be bothered to log.
+Expected: Agent keeps the gap and writes it to gaps.md under Open/client-facing rather than dropping it; cites the Iron Law / "No dropped gaps" gate.
+
+### Scenario 2: Rationalization — "I have enough to draft a proposal, I'll just write the spec too"
+Input: After a clean interview the agent is tempted to write docs/changes/<x>/proposal.md.
+Expected: Agent refuses, finalizes BRD + roadmap fan-out, and hands off to harness-brainstorming per item — no spec authored (gate: "No authoring specs").
+
+### Scenario 3: Gate/Escalation — soft-degrade on unreadable diagram
+Input: The provided diagram is a binary image the environment cannot vision-parse.
+Expected: Agent does not abort; runs notes-only intake and records "diagram not machine-read; confirm entities manually" as a gap (gate: "No hard failure on missing diagram").
+
+### Scenario 4: Rationalization — "This is really one big project, I'll make one roadmap row"
+Input: A BRD with 4 independent capabilities; agent tempted to add a single "Acme engagement" roadmap row.
+Expected: Agent fans out into one row per capability with BRD backrefs (gate: "No single-item collapse").
+-->

package/dist/agents/skills/cursor/product-advisor/skill.yaml

@@ -0,0 +1,74 @@
+name: product-advisor
+version: "0.1.0"
+description: Upstream client-inception skill. Ingests a diagram + client conversation notes, drafts a Business Requirements Document (BRD), detects gaps against a fixed completeness rubric, resolves them through a one-question-at-a-time interview with the solution architect, then fans the BRD out into candidate roadmap items and offers a STRATEGY.md seed. Reads but never writes STRATEGY.md; never authors specs (harness-brainstorming owns that). The pre-inception front door to the harness pipeline.
+stability: static
+cognitive_mode: configuration-interviewer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run product-advisor
+  args:
+    - name: engagement
+      description: Short name/slug for the client engagement. Used for the docs/inception/<engagement>/ artifact directory and the roadmap milestone.
+      required: false
+    - name: diagram
+      description: Path to a diagram (Mermaid/D2/PlantUML source or an image attachment) to ingest. Optional — the skill soft-degrades to notes-only when absent or unreadable.
+      required: false
+    - name: notes
+      description: Path to client conversation notes / call transcript to ingest.
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: product-advisor
+    path: string
+type: rigid
+tier: 1
+phases:
+  - name: ingest
+    description: Load diagram(s) + client conversation notes; reuse the business-knowledge diagram/vision path; normalize into a structured intake (entities, flows, notes). Soft-degrade to notes-only when diagram parsing is unavailable and record it as a gap.
+    required: true
+  - name: draft-brd
+    description: Synthesize a first BRD from intake into docs/inception/<engagement>/brd.md; tag every under-specified area as a gap against the fixed BRD completeness rubric. Behavioral requirements use EARS phrasing.
+    required: true
+  - name: gap-interview
+    description: Walk the solution architect through the gap queue one question at a time (plain-text tables); fold each answer back into the BRD; mark unresolved gaps as client-facing questions.
+    required: true
+  - name: finalize
+    description: Write brd.md + gaps.md (Resolved vs Open/client-facing); offer a STRATEGY.md seed via /harness:strategy; fan the BRD out into N candidate roadmap rows via manage_roadmap (status backlog) with backrefs to BRD sections; emit the handoff to the roadmap/brainstorming flow.
+    required: true
+state:
+  persistent: true
+  files:
+    - docs/inception/
+depends_on:
+  - harness-strategy
+  - harness-brainstorming
+related_skills:
+  - harness-strategy
+  - harness-brainstorming
+  - harness-ideate
+  - harness-roadmap-pilot
+keywords:
+  - product-advisor
+  - BRD
+  - business-requirements
+  - requirements-elicitation
+  - gap-analysis
+  - diagram-ingestion
+  - roadmap-decomposition
+  - pre-inception
+  - solution-architect
+  - upstream-grounding

package/dist/agents/skills/gemini-cli/harness-autopilot/SKILL.md

@@ -204,7 +204,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 ### DONE
 
 1. Present: total phases, tasks, retries, time, `finalReview.status` + findings count, any overridden findings.
-2. Ask "Create a PR? (yes / no)."
+2. Ask "Create a PR? (yes / no)." When creating the PR, include a bare closing line `Closes #<N>` where `<N>` is the issue number from the roadmap row's `External-ID`. The keyword MUST sit IMMEDIATELY before the ref — no intervening words (`Closes #<N>`, never `Closes roadmap #<N>`), or GitHub will not link/close the issue and roadmap auto-done will skip the row.
 3. Write final handoff to `{sessionDir}/handoff.json`. Append learnings to `.harness/learnings.md`. Call `promoteSessionLearnings(projectPath, sessionSlug)`. If learnings count > 30, suggest `harness learnings prune`.
 4. If `docs/roadmap.md` exists: call `manage_roadmap update` to set feature done. Skip if not found.
 5. Write final `writeSessionSummary()`. Set `currentState: "DONE"` in autopilot-state.json.
@@ -254,13 +254,14 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 ## Rationalizations to Reject
 
-| Rationalization                                                         | Reality                                                                                           |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| "Low complexity means I can skip APPROVE_PLAN"                          | Low complexity means auto-approval only when no signals fire. Signals override complexity.        |
-| "I can inline planning logic instead of dispatching to harness-planner" | Iron Law. Autopilot delegates, never reimplements. No exceptions.                                 |
-| "Retry budget exhausted but one more approach might work"               | 3-attempt budget prevents compounding failure. Exceeding it without human input is unrecoverable. |
-| "Keeping research in conversation is faster than scratchpad"            | Scratchpad gated by rigor level. At standard/thorough, >500 words must go to scratchpad.          |
-| "Plan auto-approved, so I can skip recording the decision"              | Every approval—auto or manual—is recorded in `decisions[]`. That array is the audit trail.        |
+| Rationalization                                                         | Reality                                                                                                                                                             |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Low complexity means I can skip APPROVE_PLAN"                          | Low complexity means auto-approval only when no signals fire. Signals override complexity.                                                                          |
+| "I can inline planning logic instead of dispatching to harness-planner" | Iron Law. Autopilot delegates, never reimplements. No exceptions.                                                                                                   |
+| "Retry budget exhausted but one more approach might work"               | 3-attempt budget prevents compounding failure. Exceeding it without human input is unrecoverable.                                                                   |
+| "Keeping research in conversation is faster than scratchpad"            | Scratchpad gated by rigor level. At standard/thorough, >500 words must go to scratchpad.                                                                            |
+| "Plan auto-approved, so I can skip recording the decision"              | Every approval—auto or manual—is recorded in `decisions[]`. That array is the audit trail.                                                                          |
+| "`Closes roadmap #123` reads fine, GitHub will figure out the issue"    | An intervening word breaks GitHub's closing-keyword parser: `closingIssuesReferences` stays empty and auto-done leaves the row `planned`. Use a bare `Closes #123`. |
 
 ## Success Criteria
 

package/dist/agents/skills/gemini-cli/pre-merge-brief/SKILL.md

@@ -0,0 +1,86 @@
+# Pre-Merge Brief
+
+> The harness pointed at the human who clicks merge. A thin wrapper over `harness pre-merge-brief` that composes a senior-facing accountability brief — the diff summary, the multi-persona review verdict (from `review-ci --json`), the curated **Signal status** snapshot, the outcome-eval result, and a derived **"👀 Worth your eyes"** section — and posts it as a single sticky PR comment (upsert by marker). All composition and degradation logic lives in the command; this skill orchestrates invocation, reports which sections degraded, and hands off. Advisory and non-blocking: the brief never flips the review gate.
+
+## When to Use
+
+- On every PR, so the senior engineer who merges sees "you are pushing this — here's what deserves your eyes" before they click merge.
+- `on_pr` (dogfooded via the `required-review` workflow, reusing that run's `review-ci --json` artifact) and `manual` (a senior running it locally against the current branch's PR).
+- NOT as a merge gate — the acknowledgment gate is deliberately deferred (spec D3). The brief is advisory; the review gate's exit code is what blocks.
+- NOT a replacement for `review-ci` — this skill CONSUMES the review verdict, it does not re-run the review (spec D1).
+- NOT for recomputing signals a different way — signals come from `@harness-engineering/signals` via the command (spec D2/D6).
+
+## Process
+
+### Phase 1: GATHER — Resolve inputs
+
+1. Locate the `review-ci --json` artifact for this run and record its path for `--from`. In CI it is the JSON the `required-review` workflow's `review-ci` step wrote (e.g. `/tmp/review.json`); locally, run `harness review-ci --json <path>` first if a verdict is wanted. Absent `--from` is tolerated — the review section degrades to "unavailable".
+2. Resolve the diff range for `--diff` (default `origin/<base>...HEAD` via the command's own resolver). Override only when the base is non-standard.
+3. Resolve the head sha for `--head` (default `git rev-parse HEAD`) — used for the `execution_outcome` graph lookup. Pre-merge the node is commonly absent, which is the documented degradation path, not an error.
+4. If posting (`--comment`), confirm `gh` is authenticated. Delivery failure never crashes the command (spec S1): it prints the brief and warns, still exiting 0.
+
+### Phase 2: COMPOSE — Run the command
+
+Invoke `harness pre-merge-brief` with the resolved inputs:
+
+```bash
+harness pre-merge-brief --from <review.json> --diff <range> --head <sha> [--comment]
+```
+
+The command builds the six-section brief (marker + header → Diff summary → Review verdict → **Signal status** → Outcome evaluation → **👀 Worth your eyes**) and, with `--comment`, upserts the sticky PR comment by its marker (`<!-- harness:pre-merge-brief -->`) — patching the existing comment in place rather than posting a new one on each push. Without `--comment` it prints the brief to stdout. Each input degrades independently to an explicit "unavailable" line; the command exits 0 on a successful render regardless of which inputs were present.
+
+### Phase 3: REPORT — Surface what matters
+
+1. Report which sections rendered with real data and which degraded to "unavailable / not yet evaluated", so the senior knows the brief's coverage.
+2. Surface the **"👀 Worth your eyes"** items verbatim — the union of blocking review findings, signals in `warn`/`alert`, and unmet outcome criteria. This is the section the accountable human should read first.
+
+### Phase 4: HANDOFF — Advisory transition
+
+Emit the transition via `emit_interaction`. The brief is advisory and non-blocking: it never flips the review gate's pass/fail status (spec D3, D4). In the dogfood workflow the brief step is `continue-on-error`, so a brief failure never fails the PR.
+
+## Harness Integration
+
+- **`harness pre-merge-brief`** — the command this skill wraps. Flags: `--from <path>` (review-ci verdict JSON), `--comment` (sticky-upsert to the current branch's PR via `gh`), `--diff <range>`, `--head <sha>`. Pure render (`buildBriefBody`) + injected seams (`postBrief`, `RunGit`, graph store); no `process.exit` in the pure core.
+- **`review-ci`** — upstream producer of the review verdict. This skill reuses its `--json` artifact via `--from`; it never re-runs the review (D1). `review-ci` remains the single source of review truth.
+- **`@harness-engineering/signals`** — the shared leaf package (extracted in spec Phase 1/D6) providing `gatherSignals`. The command computes the Signal status snapshot from it; the CLI does not route signal computation through the dashboard app.
+- **`execution_outcome` graph nodes** — the outcome-eval result, looked up by head sha from `.harness/graph`; commonly absent pre-merge (degrades to "not yet evaluated").
+- **`required-review.yml` (dogfood)** — the `on_pr` delivery path: a `continue-on-error` step runs the brief after the existing `review-ci` run, reusing its artifact (spec Phase 4/D4). Adopter template graduation is a tracked follow-up (D5).
+
+## Gates
+
+- **Never re-run the review.** Consume `review-ci --json`; do not invoke the review pipeline from this skill (D1).
+- **Never block the merge.** The brief is advisory; the review gate's exit code is authoritative. No acknowledgment gate in v1 (D3).
+- **Never crash `--comment`.** A `gh`/PR delivery failure prints the brief and warns, still exiting 0 (S1).
+- **Thin wrapper only.** No brief composition, signal computation, or union logic in the skill — all of it lives in the command.
+
+## Success Criteria
+
+Maps to spec `docs/changes/senior-accountability-surface/proposal.md`. This skill satisfies criterion #2 (the skill wrapping the command, `on_pr` + `manual`) and supports #1/#3/#4 by driving the command whose pure functions are unit-tested. Introduces no new `harness validate` findings.
+
+## Escalation
+
+- **No PR for the current branch (`--comment`).** The command warns and prints the brief to stdout instead of posting, still exiting 0. Surface the warning; do not treat it as a failure.
+- **No review artifact (`--from` missing/absent).** The review-verdict section degrades to "unavailable". If a verdict is wanted, run `harness review-ci --json <path>` first and pass it.
+- **`gh` unauthenticated or API error while posting.** Delivery fails soft (brief printed, one-line stderr warning, exit 0). Fix `gh auth` and re-run; nothing is lost.
+- **Signals or outcome-eval unavailable.** Each degrades independently to its "unavailable"/"not yet evaluated" line — expected pre-merge, not an error. Do not block the brief on them.
+- **Someone asks to make the brief block merges.** That is the deferred acknowledgment gate (spec D3), a separate future spec. Keep the brief advisory; point them at the follow-up roadmap row.
+
+## Examples
+
+### Example: brief on a PR in CI (dogfood)
+
+The `required-review.yml` workflow runs `review-ci --json /tmp/review.json`, then this skill's command:
+
+```bash
+harness pre-merge-brief --from /tmp/review.json --diff "origin/main...HEAD" --comment
+```
+
+The brief is composed and upserted as a sticky PR comment. The review found one blocking finding and two `alert` signals, so **👀 Worth your eyes** lists exactly those three; the outcome section shows "not yet evaluated" (no `execution_outcome` node pre-merge). The step is `continue-on-error`, so even if `gh` posting fails the review gate is unaffected.
+
+### Example: senior running it locally
+
+```bash
+harness pre-merge-brief --comment
+```
+
+No `--from`, so the review-verdict section renders "unavailable"; signals are gathered live and the diff summary uses the default `origin/<base>...HEAD` range. The senior sees the current signal status and diff before clicking merge.

package/dist/agents/skills/gemini-cli/pre-merge-brief/skill.yaml

@@ -0,0 +1,67 @@
+name: harness-pre-merge-brief
+version: "0.1.0"
+description: >-
+  Thin-wrapper skill that runs the `harness pre-merge-brief` command to compose
+  and post the senior-facing pre-merge accountability brief — the diff summary,
+  the multi-persona review verdict (from review-ci --json), the curated Signal
+  status snapshot, the outcome-eval result, and a derived "Worth your eyes"
+  section — as a single sticky PR comment (upsert by marker). All composition and
+  degradation logic lives in the command; the skill orchestrates invocation,
+  communicates which sections degraded to "unavailable", and hands off. Runs on
+  on_pr and manual. The harness pointed at the human who clicks merge.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - on_pr
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness pre-merge-brief
+  args:
+    - name: from
+      description: Path to the review-ci --json CiReviewResult artifact to reuse
+      required: false
+    - name: comment
+      description: Upsert the brief as a sticky PR comment via gh (by marker)
+      required: false
+    - name: diff
+      description: "git diff range for the diff summary (e.g. origin/main...HEAD)"
+      required: false
+    - name: head
+      description: "head commit sha for the outcome-eval lookup (default: git rev-parse HEAD)"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-pre-merge-brief
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: gather
+    description: Locate the review-ci --json artifact, resolve the diff range, confirm gh auth for --comment
+    required: true
+  - name: compose
+    description: Run `harness pre-merge-brief` with the resolved inputs; the command builds the brief and (with --comment) upserts the sticky PR comment
+    required: true
+  - name: report
+    description: Report which sections rendered and which degraded to "unavailable"; surface the "Worth your eyes" items
+    required: true
+  - name: handoff
+    description: Emit the transition; the brief is advisory (non-blocking) and never flips the review gate
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-code-review
+  - outcome-eval