@harness-engineering/cli 2.7.1 → 3.0.0

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

@@ -33,20 +33,22 @@ A reviewer who applies fixes is no longer reviewing — they are editing with re
 The review runs as a 7-phase pipeline. Each phase has a clear input, output, and exit condition.
 
 ```
-Phase 1: GATE --> Phase 2: MECHANICAL --> Phase 3: CONTEXT --> Phase 4: FAN-OUT
-                                                                      |
-Phase 7: OUTPUT <-- Phase 6: DEDUP+MERGE <-- Phase 5: VALIDATE <------+
+Phase 1: GATE --> Phase 2: MECHANICAL --> Phase 3: CONTEXT --> Phase 3.5: CALIBRATE
+                                                                                 |
+                                                                                 v
+Phase 7: OUTPUT <-- Phase 6: DEDUP+MERGE <-- Phase 5: VALIDATE <-- Phase 4: FAN-OUT
 ```
 
-| Phase          | Tier  | Purpose                          | Exit Condition                                    |
-| -------------- | ----- | -------------------------------- | ------------------------------------------------- |
-| 1. GATE        | fast  | Skip ineligible PRs (CI only)    | PR eligible, or exit with reason                  |
-| 2. MECHANICAL  | none  | Lint, typecheck, test, sec scan  | All pass -> continue; any fail -> report and stop |
-| 3. CONTEXT     | fast  | Scope context per review domain  | Context bundles assembled for each subagent       |
-| 4. FAN-OUT     | mixed | Parallel review subagents        | All subagents return ReviewFinding[]              |
-| 5. VALIDATE    | none  | Exclude mechanical dupes, verify | Unvalidated findings discarded                    |
-| 6. DEDUP+MERGE | none  | Group, merge, assign severity    | Deduplicated finding list with merged evidence    |
-| 7. OUTPUT      | none  | Text output or GitHub comments   | Review delivered, exit code set                   |
+| Phase          | Tier  | Purpose                                            | Exit Condition                                    |
+| -------------- | ----- | -------------------------------------------------- | ------------------------------------------------- |
+| 1. GATE        | fast  | Skip ineligible PRs (CI only)                      | PR eligible, or exit with reason                  |
+| 2. MECHANICAL  | none  | Lint, typecheck, test, sec scan                    | All pass -> continue; any fail -> report and stop |
+| 3. CONTEXT     | fast  | Scope context per review domain                    | Context bundles assembled for each subagent       |
+| 3.5. CALIBRATE | none  | Pick depth tier + activate conditional subagents   | DepthCalibration recorded in PipelineContext      |
+| 4. FAN-OUT     | mixed | Parallel review subagents (4 base + N conditional) | All subagents return ReviewFinding[]              |
+| 5. VALIDATE    | none  | Exclude mechanical dupes, verify                   | Unvalidated findings discarded                    |
+| 6. DEDUP+MERGE | none  | Group, merge, assign severity                      | Deduplicated finding list with merged evidence    |
+| 7. OUTPUT      | none  | Text output or GitHub comments                     | Review delivered, exit code set                   |
 
 ### Finding Schema
 
@@ -62,19 +64,35 @@ interface ReviewFinding {
   suggestion?: string; // fix, if available
   evidence: string[]; // supporting context from agent
   validatedBy: 'mechanical' | 'graph' | 'heuristic';
+  // Additive — populated by the new conditional subagents only:
+  subagent?:
+    | 'compliance'
+    | 'bug'
+    | 'security'
+    | 'architecture'
+    | 'learnings'
+    | 'adversarial'
+    | 'typescript-strict'
+    | 'frontend-races';
+  confidence?: 'high' | 'medium' | 'low' | 25 | 50 | 75 | 100;
 }
 ```
 
+The two optional fields are additive — existing 4 agents leave them
+undefined. Numeric `confidence` values follow the anchored rubric at
+[references/confidence-rubric.md](references/confidence-rubric.md).
+
 ### Flags
 
-| Flag              | Effect                                                               |
-| ----------------- | -------------------------------------------------------------------- |
-| `--comment`       | Post inline comments to GitHub PR via `gh` CLI or GitHub MCP         |
-| `--deep`          | Pass `--deep` to `harness-security-review` for threat modeling       |
-| `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                 |
-| `--ci`            | Enable eligibility gate, non-interactive output                      |
-| `--fast`          | Skip learnings, fast-tier agents for all fan-out slots               |
-| `--thorough`      | Always load learnings, full roster + meta-judge, learnings in output |
+| Flag              | Effect                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `--comment`       | Post inline comments to GitHub PR via `gh` CLI or GitHub MCP                         |
+| `--deep`          | Pass `--deep` to `harness-security-review` for threat modeling                       |
+| `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                                 |
+| `--ci`            | Enable eligibility gate, non-interactive output                                      |
+| `--fast`          | Skip learnings, fast-tier agents for all fan-out slots                               |
+| `--thorough`      | Always load learnings, full roster + meta-judge, learnings in output                 |
+| `--depth`         | Override Phase 3.5 calibration: `quick`/`standard`/`deep`. `deep` activates all subs |
 
 ### Rigor Levels
 
@@ -254,7 +272,33 @@ git log --oneline -5 -- <affected-file>
 
 Use to determine: **Hotspot?** (3+ changes in last 5 commits) **Recently refactored?** **Multiple authors?** **Last change was bugfix?** (yellow flag)
 
-**Exit:** Context bundles assembled for all four domains. Continue to Phase 4.
+**Exit:** Context bundles assembled for all four domains. Continue to Phase 3.5.
+
+---
+
+### Phase 3.5: CALIBRATE DEPTH
+
+**Tier:** none (mechanical) | **Purpose:** Pick a depth tier (Quick/Standard/Deep) from diff size + risk-keyword detection and decide which conditional subagents activate in Phase 4. The existing 4 agents always run; this phase only gates _additional_ work.
+
+**Inputs:** `DiffInfo`, commit message, optional `--depth quick|standard|deep` override.
+
+**Steps:**
+
+1. **Count changed lines.** Sum `+`/`-` lines per file, excluding test files (`*.test.{ts,tsx,js,jsx}`, `__tests__/**`, `*.spec.{ts,tsx,js,jsx}`), generated files (`*.generated.{ts,tsx,js,jsx}`), lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`), and `dist/` / `build/` directories.
+2. **Detect risk keywords.** Match the canonical keyword list from [references/risk-keywords.md](references/risk-keywords.md) against the diff content, file paths, and commit message (case-insensitive, whole-word for single-word keywords, substring for multi-word keywords like `external API`).
+3. **Compute tier.**
+   - **Quick:** `< 50` lines AND `0` keywords
+   - **Standard:** `50–199` lines OR exactly `1` keyword
+   - **Deep:** `≥ 200` lines OR `≥ 2` keywords
+4. **Compute activation set** (`adversarial`, `typescript-strict`, `frontend-races`):
+   - `adversarial` — active at Standard or Deep
+   - `typescript-strict` — active when the diff contains a non-test `.ts` or `.tsx` (excluding `*.d.ts`)
+   - `frontend-races` — active when `typescript-strict` is active AND the diff contains one of `.tsx`, `useEffect`, `useState`, `setTimeout`, `setInterval`, `addEventListener`, `data-controller=`
+5. **Override (`--depth deep`)** — forces Deep tier and activates all three conditional subagents.
+
+**Output:** `DepthCalibration { depth, changedLines, riskSignals, activations, overridden }` recorded in `PipelineContext`. Phase 7 displays the calibration result at the top of the review.
+
+**Exit:** Calibration complete. Continue to Phase 4.
 
 ---
 
@@ -380,7 +424,48 @@ Reviews architectural violations, dependency direction, and design pattern compl
 
 **Output:** `ReviewFinding[]` with `domain: 'architecture'`
 
-**Exit:** All four agents returned findings. Continue to Phase 5.
+---
+
+#### Conditional Subagents (depth-gated, activated by Phase 3.5)
+
+The dispatcher reads `PipelineContext.depthCalibration.activations` and runs only those listed. Each conditional subagent emits findings under existing domain values (`bug` or `architecture`) and populates `subagent` + `confidence` per the [confidence rubric](references/confidence-rubric.md).
+
+##### Adversarial (strong tier) — activates at Standard or Deep
+
+Constructs failure scenarios that fall _between_ the base 4 agents.
+
+**Hunt categories:**
+
+- **Assumption violation** — invariants the diff depends on but does not enforce (e.g., `JSON.parse` on untrusted input)
+- **Composition failures** — two patterns correct alone that misbehave together (floating Promise chains, optional-chain calls)
+- **Abuse cases** — adversarial input shapes the diff does not anticipate (unbounded `fetch`, accidentally enumerable surfaces)
+- **Cascade chains (Deep only)** — single failures propagating through downstream callers (`new Promise` without `reject`)
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'`, `subagent: 'adversarial'`, `confidence: 50|75|100`.
+
+##### TypeScript-strict (standard tier) — activates when a non-test `.ts`/`.tsx` is in the diff
+
+**Hunt categories:**
+
+- **Type holes that disable the checker** — explicit `any`, `// @ts-ignore`, `as unknown as T`, non-null assertions in non-`process.env` contexts
+- **Refactor regression risk** — removed guards whose call sites have no test coverage
+- **Existing-file complexity** — production TS files growing past 400 lines (Single Responsibility flag)
+- **Five-second rule** — `handle*` / `process*` / `do*` style names that fail to predict behavior at the call site
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'` (type holes / regression) or `domain: 'architecture'` (complexity), `subagent: 'typescript-strict'`, `confidence: 50|75|100`.
+
+##### Frontend-races (standard tier) — activates when TypeScript-strict is active AND an async-UI signal is present
+
+**Hunt categories:**
+
+- **Lifecycle cleanup gaps** — `setInterval` / `setTimeout` / `addEventListener` without matching cleanup in the same module
+- **Hook timing mistakes** — `useEffect` immediately calling `setState` for a render-time-derivable value
+- **Concurrent interactions** — overlapping clicks/requests, impossible-state booleans
+- **Stale work** — `await fetch` followed by `setState` with no `AbortController` / `AbortSignal.timeout`
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'`, `subagent: 'frontend-races'`, `confidence: 50|75|100`.
+
+**Exit:** All base agents + active conditional subagents returned findings. Continue to Phase 5.
 
 ---
 

package/dist/agents/skills/gemini-cli/harness-code-review/references/confidence-rubric.md

@@ -0,0 +1,45 @@
+# Confidence Rubric
+
+> Anchored confidence rubric for `harness-code-review` conditional subagents. Numeric anchors avoid vague "high/medium/low" judgments. New subagents (`adversarial`, `typescript-strict`, `frontend-races`) populate `ReviewFinding.confidence` per this rubric. Existing 4 agents (compliance, bug, security, architecture) are not yet migrated.
+
+## Anchors
+
+| Score | Label                  | Definition                                                                                                                                      |
+| ----- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `100` | Mechanical             | Directly verifiable from the diff. The finding can be reproduced by quoting specific lines. No interpretation required.                         |
+| `75`  | Constructible scenario | The agent can describe a concrete sequence of inputs and observable outputs that triggers the issue. Every step is traceable to specific lines. |
+| `50`  | Judgment-based         | The issue is real but partly judgment. Depends on assumptions about behavior outside the diff.                                                  |
+| `25`  | Speculative            | Not supported by what is in the diff. **Suppress.** Agents must not emit.                                                                       |
+
+A finding with confidence below `25` must be discarded before it leaves the subagent.
+
+## Per-agent worked examples
+
+### `adversarial`
+
+- **100 — Mechanical**: every step in the cascade is traceable to specific lines. _Example: a `useState` updater on line 32 schedules work that the cleanup on line 45 never cancels — both lines are quoted._
+- **75 — Constructible scenario**: given specific input X, execution reaches line Y and produces wrong outcome Z. _Example: "If `parseDate('')` returns `null` (line 18), the chain at line 22 throws because there is no nullable check before `.toISOString()`."_
+- **50 — Judgment-based**: scenario depends on external API behavior assumed but unverified. _Example: "If the remote service occasionally returns `5xx`, the retry loop at line 60 enters a tight spin." — the tight spin is real but the retry condition needs runtime evidence._
+- **25 — Speculative**: "What if the caller ever does X?" with no diff evidence. _Suppress._
+
+### `typescript-strict`
+
+- **100 — Mechanical**: explicit `any`, `// @ts-ignore`, `as unknown as Foo`, or `unknown` assertion in the diff. _Example: `function load(x: any) { ... }` is quoted directly._
+- **75 — Constructible scenario**: a refactor in the diff removes a guard that the type system relied on. _Example: "Removing the `if (user)` check on line 12 means line 14's access `user.id` is now reachable for `null`, but no test exercises this path."_
+- **50 — Judgment-based**: naming or extraction quality calls. _Example: "Function `handleStuff` does three things — the five-second-rule fails for a future reader." — true but discretionary._
+- **25 — Speculative**: "Could be improved someday." _Suppress._
+
+### `frontend-races`
+
+- **100 — Mechanical**: `setInterval` with no `clearInterval` in disconnect/unmount; `addEventListener` with no `removeEventListener`. _Example: `setInterval(tick, 1000)` on line 30 with no cleanup return in the `useEffect`._
+- **75 — Constructible scenario**: race traceable to a specific interaction sequence. _Example: "Double-click on the submit button triggers two parallel network calls because `isSubmitting` is set inside an `await` (line 45) after the button stays clickable."_
+- **50 — Judgment-based**: race depends on timing windows not fully forceable from diff. _Example: "If the server replies before the cleanup runs, the stale callback updates the new component instance." — possible but requires timing assumptions._
+- **25 — Speculative**: "On a slow device this might race." _Suppress._
+
+## How dedup uses confidence
+
+Phase 6 DEDUP+MERGE prefers the higher-`severity` finding when two agents flag the same line. On a severity tie, the finding with explicit `confidence` set wins. When neither has confidence (the existing 4 agents), current dedup behavior is unchanged.
+
+## Compatibility
+
+The legacy security agent uses string values (`'high' | 'medium' | 'low'`). New subagents use numeric anchors (`25 | 50 | 75 | 100`). The `ReviewFinding.confidence` field accepts either. Future migration of the security agent to numeric anchors is opt-in and out of scope here.

package/dist/agents/skills/gemini-cli/harness-code-review/references/risk-keywords.md

@@ -0,0 +1,40 @@
+# Risk keywords for depth calibration
+
+> Used by Phase 3.5 CALIBRATE in `harness-code-review` to elevate a diff's depth tier when sensitive surfaces are touched. The list below is the **single source of truth** — Decisions 7 and 8 of the spec reference this file rather than re-enumerating. Modifications to this list are policy decisions; updates require PR review.
+
+The calibrator matches against the changed-file content, file paths, and the commit message. Matching is case-insensitive and whole-word where possible (substring for path matches like `auth/` directories).
+
+## Canonical list
+
+```
+auth
+authn
+authz
+password
+token
+payment
+billing
+migration
+migrate
+external API
+webhook
+cryptography
+crypto
+session
+cookie
+personally identifiable
+PII
+compliance
+```
+
+## Tier rules (from spec Decision 8)
+
+| Diff size | Keywords matched | Depth tier |
+| --------: | ---------------: | ---------- |
+|    `< 50` |              `0` | Quick      |
+|  `50–199` |              `0` | Standard   |
+|    `< 50` |              `1` | Standard   |
+|       any |            `≥ 2` | Deep       |
+|   `≥ 200` |              any | Deep       |
+
+Author override: `--depth quick|standard|deep` forces the tier and bypasses calibration.

package/dist/agents/skills/gemini-cli/harness-code-review/skill.yaml

@@ -42,6 +42,9 @@ cli:
     - name: --thorough
       description: Maximum rigor — always load learnings, full agent roster + meta-judge
       required: false
+    - name: --depth
+      description: "Override Phase 3.5 depth calibration: quick|standard|deep. 'deep' activates all conditional subagents (adversarial, typescript-strict, frontend-races)."
+      required: false
     - name: session-slug
       description: Session slug for scoped state/handoff (passed by autopilot)
       required: false

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

@@ -83,19 +83,22 @@ Read `docs/solutions/references/schema.yaml` for the authoritative track/categor
 ### Phase 5: WRITE (lock-protected)
 
 1. Compute slug: kebab-case from the title; if a file with that slug already exists in the target directory, append `-2`, `-3`, etc.
-2. **Acquire the per-category lock by shelling out.** Run a Node one-liner that imports `acquireCompoundLock` from `@harness-engineering/core`, holds the handle while you write the doc, then releases it. Example: `node -e "import('@harness-engineering/core').then(({ acquireCompoundLock }) => { const h = acquireCompoundLock('<category>'); /* write the doc here */ h.release(); }).catch(err => { console.error(err.message); process.exit(1); })"`. Lock path: `.harness/locks/compound-<category>.lock`. The MCP tool `acquire_compound_lock` is planned for a later phase — **do not attempt to call it yet**; the shell-out is the only supported path right now.
-   - On `CompoundLockHeldError`: report "compound lock for category `<category>` is held by pid `<N>` — wait for it to release or run `/harness:compound` for a different category" and stop. **Do not retry automatically.** A second invocation on the same problem after release will go through Phase 3 and find the doc the first invocation produced.
+2. **Acquire the per-category lock via the harness MCP server.** Call `acquire_compound_lock({ path: process.cwd(), category: '<category>' })`. On success it returns `{ acquired: true, token, lockPath }` — hold the `token` while you write the doc, then call `release_compound_lock({ token })` when finished. The MCP server holds the file handle and registers process-exit cleanup, so an abandoned agent does not leave a dangling lock-with-stale-PID. Lock path: `.harness/locks/compound-<category>.lock`. Fallback for environments without the MCP server (only works when `@harness-engineering/core` is resolvable from the project): `node -e "import('@harness-engineering/core').then(({ acquireCompoundLock }) => { const h = acquireCompoundLock('<category>'); /* write the doc here */ h.release(); })"`.
+   - On `{ acquired: false, error: 'CompoundLockHeldError', holderPid }` (or `CompoundLockHeldError` when invoked directly): report "compound lock for category `<category>` is held by pid `<holderPid>` — wait for it to release or run `/harness:compound` for a different category" and stop. **Do not retry automatically.** A second invocation on the same problem after release will go through Phase 3 and find the doc the first invocation produced.
 3. Re-run a quick Phase 3 overlap-check inside the lock (defends against TOCTOU when the first overlap-check returned "no overlap" but another invocation completed in the meantime; the re-check is cheap).
 4. Write the file at `docs/solutions/<track>/<category>/<slug>.md`.
 5. Validate frontmatter against `SolutionDocFrontmatterSchema` by running `harness validate` (which runs `validateSolutionsDir`).
-6. Release the lock.
+6. Release the lock via `release_compound_lock({ token })` (or `handle.release()` on the fallback shell-out path).
 7. Surface to chat: file path created (or updated), category, and a one-sentence summary.
 
 ## Harness Integration
 
 - **`harness validate`** — Run after writing the doc; the solutions validator catches frontmatter errors before commit.
 - **`harness check-deps`** — Not required (no new module imports introduced by writing a doc).
-- **`@harness-engineering/core` lock primitive** — `acquireCompoundLock(category, { cwd })` returns a release handle; throws `CompoundLockHeldError` on contention. See `packages/core/src/locks/compound-lock.ts`.
+- **Harness MCP tools consumed by this skill** (canonical execution path — no project-local `@harness-engineering/core` required):
+  - `acquire_compound_lock({ path, category })` — returns `{ acquired: true, token, lockPath }` on success or `{ acquired: false, error: 'CompoundLockHeldError', holderPid, lockPath }` on contention.
+  - `release_compound_lock({ token })` — releases the lock; idempotent on repeat calls with the same token.
+- **`@harness-engineering/core` lock primitive** (only directly relevant when the MCP server is unavailable) — `acquireCompoundLock(category, { cwd })` returns a release handle; throws `CompoundLockHeldError` on contention. See `packages/core/src/locks/compound-lock.ts`.
 - **Schema authority** — `packages/core/src/solutions/schema.ts` is the single source of truth for tracks and categories. `docs/solutions/references/schema.yaml` mirrors it for human reading.
 - **Boundary with `harness-knowledge-pipeline`** — Knowledge-pipeline extracts structural facts FROM CODE. Compound captures post-mortem playbooks WRITTEN AFTER A FIX. Compound's knowledge-track output is a _candidate input_ to the pipeline (Phase 7 of the spec wires this).
 - **Boundary with `.harness/learnings.md`** — The file remains for ephemeral session notes. It is no longer the canonical sink for compounding knowledge — that's `docs/solutions/`.

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

@@ -56,7 +56,7 @@ When no arguments are provided (standalone invocation), discover plan from `docs
 4. **Load session summary for cold start.** If resuming (session slug known):
    - Call `listActiveSessions()` to read the session index.
    - Call `loadSessionSummary()` for the target session.
-   - If ambiguous, present the index and ask which session to resume.
+   - If ambiguous, present the index and ask which session to resume. Ask in plain text — do not elevate this to `AskUserQuestion` (the session index can exceed its 4-option cap and a natural header like "Pick session" can exceed its 12-char cap, rendering the call as ERR).
 
 5. **Check for known dead ends.** Review `learnings` tagged `[outcome:failure]`. Warn if any match current plan approaches.
 

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

@@ -13,6 +13,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every choice and destructive confirmation in this skill (worktree location, discard-experiment, etc.) is plain text only. Do not elevate to `AskUserQuestion`: option labels like the A/B/C worktree-location choices and natural headers like "Discard commits" routinely exceed its 4-option / 12-char caps and render as ERR.
+
 ### Part A: Worktree Creation
 
 #### Step 1: Choose Worktree Location

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

@@ -0,0 +1,279 @@
+# Harness Ideate
+
+> Pre-brainstorm ideation. Generates candidate ideas, critiques each against its strongest objection, and ranks them by `(impact × confidence) ÷ effort`. Writes a single ranked artifact to `docs/ideation/<slug>-YYYY-MM-DD.md`. **Produces ranked ideation, not specs** — brainstorming consumes the output.
+
+## When to Use
+
+- Before brainstorming, when the feature to design has not yet been selected
+- When the user asks "what should we build next in area X?" and there are several plausible answers
+- When a single domain (auth, pulse reports, onboarding…) has 5–10 candidate ideas worth comparing
+- After updating `STRATEGY.md` and wanting to surface candidates aligned with the new tracks
+- NOT when the feature is already selected — go straight to `harness-brainstorming`
+- NOT for ranking existing roadmap items — that is `harness-roadmap-pilot`'s job
+- NOT for generating specs, plans, or code — this skill writes one ideation artifact and stops
+- NOT for refreshing `STRATEGY.md` — that is `harness-strategy`'s job
+
+## Process
+
+**Prompt the human in plain text** — every confirmation and selection in this skill (`Proceed? (y/n)`, post-critique selection, etc.) is plain text only. Do not elevate to `AskUserQuestion`: natural headers like "Confirm inputs" exceed its 12-char cap and option lists routinely exceed its 4-option cap, rendering the call as ERR.
+
+### Iron Law
+
+**The skill produces exactly ONE ranked artifact per run, at `docs/ideation/<slug>-YYYY-MM-DD.md`, and NEVER produces a spec, plan, ADR, or code.** If the user wants a spec from a ranked idea, they invoke `harness-brainstorming` next — that is the contract.
+
+---
+
+### Phase 1: GROUND — Read STRATEGY.md and Confirm the Topic
+
+1. **Resolve the focus argument.** If the user passed `--focus` (or supplied a one-line topic in the conversation), use it verbatim. Otherwise ask:
+
+   ```
+   What is the ideation topic? One short line (e.g., "onboarding for plugin-only users",
+   "lateral review depth", "pulse-report follow-up routing").
+   ```
+
+   Capture the answer; do not proceed without one.
+
+2. **Resolve the count.** Default to 10 if `--count` is unset. Clamp silently to `[5, 25]` (`<5` is too few to rank meaningfully; `>25` loses signal). Proceed with the clamped value.
+
+3. **Read `STRATEGY.md` (grounding).** Call `read_strategy({ path: process.cwd() })` on the harness MCP server — it returns `{ present, valid, doc?, error? }` and runs validation + parsing inside the server so the project does not need `@harness-engineering/core` installed.
+
+   Three cases:
+   - **`{ present: false }`:** print one line — `STRATEGY.md not present — ranking will use impact × confidence ÷ effort only; no strategy-alignment tiebreaker`. Continue.
+   - **`{ present: true, valid: true, doc }`:** capture `doc.sections` for `Target problem`, `Our approach`, `Who it's for`, and `Tracks`. These four sections drive the strategy-alignment tiebreaker in Phase 4.
+   - **`{ present: true, valid: false, error }`:** print `error` verbatim and continue without strategy grounding. Do NOT block; this skill is not the place to repair `STRATEGY.md`. Suggest `/harness:strategy` as a follow-up.
+
+   Fallback for environments without the MCP server: `node -e "import('@harness-engineering/core').then(m => m.validateStrategy(process.cwd()).then(r => console.log(JSON.stringify(r))))"` — only works when `@harness-engineering/core` is resolvable from the project's `node_modules`.
+
+4. **Confirm the topic.** Before generating, surface a 2-line summary:
+
+   ```
+   Topic: <focus>
+   Count: <N>
+   Strategy grounding: <enabled|disabled — reason>
+   ```
+
+   Ask: `Proceed with these inputs? (y/n)`. Wait for confirmation.
+
+---
+
+### Phase 2: GENERATE — Produce Candidate Ideas
+
+Generate exactly N candidate ideas. Each idea is a structured object with the following fields:
+
+| Field        | Type                    | Description                                                                                                              |
+| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `premise`    | string (1 sentence)     | What this idea is, in one declarative sentence. Not aspirational — what the change IS, not what we hope it achieves.     |
+| `persona`    | string (1 sentence)     | Target persona segment (specific, not "developers"). If STRATEGY.md is present, prefer phrasing from its `Who it's for`. |
+| `complexity` | `low \| medium \| high` | Rough engineering complexity estimate.                                                                                   |
+| `key_risk`   | string (1 sentence)     | The single biggest reason this idea might fail or not be worth doing. Used in Phase 3 as the seed for critique.          |
+| `impact`     | `low \| medium \| high` | How much this matters if it works. Mapped to `1/2/3` for ranking.                                                        |
+| `confidence` | `low \| medium \| high` | How confident we are that we can pull it off. Mapped to `1/2/3` for ranking.                                             |
+| `effort`     | `low \| medium \| high` | Engineering effort to deliver. Mapped to `1/2/3` for ranking.                                                            |
+
+**Generation rules:**
+
+- **Spread the complexity surface.** Aim for at least one `low` and one `high` complexity idea; resist clustering everything as `medium`.
+- **Resist near-duplicates.** Two ideas with the same `premise` are one idea. If two ideas only differ by a parameter ("X for web" vs "X for mobile"), collapse them into a single idea with a parametric premise.
+- **Be honest about effort.** A `low`-effort idea must be plausibly implementable in <1 sprint by one engineer. If you find yourself defaulting everything to `medium`, slow down and re-estimate one extreme.
+- **When STRATEGY.md is present**, at least 60% of ideas should plausibly serve a current track in `Tracks`. Stretch ideas outside the tracks are allowed and useful, but the majority anchors in.
+
+Present the N candidates as a numbered list. Each line is 2-3 sentences max:
+
+```
+1. [Premise]. Persona: [...]. Complexity: medium. Key risk: [...]. Impact/Confidence/Effort: M/M/L.
+2. [Premise]. Persona: [...]. Complexity: low.    Key risk: [...]. Impact/Confidence/Effort: H/L/L.
+...
+```
+
+---
+
+### Phase 3: CRITIQUE — Identify and Address Strongest Objections
+
+For each candidate, surface the **single strongest objection** — the best argument against doing this idea. The seed is `key_risk` from Phase 2, but the critique should sharpen it (one paragraph, not one sentence):
+
+```
+Idea 3: [Premise].
+  Strongest objection: [...]. Most likely failure mode: [...]. What would need to be true
+  for this objection to NOT hold: [...].
+```
+
+After all N critiques are presented, ask the user:
+
+```
+Which objections do you want to answer (vs. accept as a downside)?
+Options:
+  - all   — I'll address every objection
+  - none  — accept all critiques as known downsides
+  - <list of numbers, e.g., "1, 3, 7">
+```
+
+For each idea the user elects to answer, ask: `For idea N, what makes the objection wrong or addressable?` Capture the user's one-paragraph answer. If the user cannot answer convincingly, leave the objection standing (this is a signal — it lowers the idea's ranking).
+
+Critique answers do NOT change the impact/confidence/effort scores from Phase 2. They feed into the rationale shown alongside each ranked idea in Phase 5.
+
+---
+
+### Phase 4: RANK — Score and Order
+
+For each candidate, compute `base_score = (impact × confidence) ÷ effort` using the `low|medium|high → 1|2|3` mapping documented in `references/scoring.md`. Higher is better; range is `[≈0.33, 9.0]`.
+
+**Strategy-alignment tiebreaker.** When `STRATEGY.md` was grounded in Phase 1, compute an alignment bonus per candidate:
+
+```
+alignment_bonus =
+  (premise plausibly advances a Tracks bullet ? 0.5 : 0)
++ (premise/persona references Target problem or Our approach ? 0.25 : 0)
+```
+
+Maximum bonus `+0.75`. The bonus is **bounded**: it is applied only when the absolute difference between two adjacent candidates' base scores is `≤ 0.05`. Outside that tie window, the base score wins and the bonus is recorded for transparency but does NOT change rank order. See `references/scoring.md` for the full contract (including the worked example and the boundary with `harness-roadmap-pilot`'s identical tiebreaker shape).
+
+Sort by final score descending. Stable on ties (preserve generation order so the user can find the original list).
+
+---
+
+### Phase 5: WRITE — Persist the Ranked Artifact
+
+1. **Compute the slug.** Kebab-case the focus argument; lowercase; collapse whitespace and `[^a-z0-9-]` into `-`; trim leading/trailing `-`; truncate to **≤30 characters**. Example: `"onboarding for plugin-only users"` → `onboarding-for-plugin-only-use`.
+
+2. **Compute today's date** as `YYYY-MM-DD` (UTC).
+
+3. **Compute the output path.** `docs/ideation/<slug>-<YYYY-MM-DD>.md`. If that path already exists (same focus, same day), append a 6-character lowercase hex suffix derived from `sha1(focus + iso_timestamp).slice(0, 6)`:
+
+   ```
+   docs/ideation/onboarding-for-plugin-only-use-2026-06-02.md         # first run
+   docs/ideation/onboarding-for-plugin-only-use-2026-06-02-a3f9b2.md  # collision
+   ```
+
+4. **Render the artifact.** Frontmatter + ranked list. See ranking math in `references/scoring.md`. Required fields:
+
+   ```markdown
+   ---
+   topic: <focus argument verbatim>
+   generated_at: <ISO 8601 timestamp>
+   strategy_grounded: <true | false>
+   strategy_path: <STRATEGY.md path if grounded, else null>
+   count_requested: <N>
+   count_generated: <N>
+   ranking_formula: '(impact × confidence) ÷ effort; strategy-alignment tiebreaker (max +0.75) applied only when |Δbase_score| ≤ 0.05'
+   ---
+
+   # Ideation: <focus>
+
+   ## Inputs
+
+   - Topic: <focus>
+   - Generated: <ISO timestamp>
+   - Strategy grounding: <enabled | disabled with one-line reason>
+
+   ## Ranked candidates
+
+   ### 1. <premise> — score: <final>
+
+   - Persona: <...>
+   - Complexity: <low|medium|high>
+   - Impact / Confidence / Effort: <H/M/L> — base score <X.XX>
+   - Strategy alignment: <none | +0.25 persona | +0.5 track:<name>> — final score <Y.YY>
+   - Strongest objection: <one paragraph>
+   - Objection answered: <yes/no — if yes, one paragraph rebuttal>
+
+   ### 2. ...
+   ```
+
+5. **Write the file.** Create `docs/ideation/` if it does not exist. Write via the standard `Write` tool — no Node one-liner is required here; the content is generated by the skill, not user-supplied prose with shell-escape hazards.
+
+6. **Print the handoff.** Three lines:
+
+   ```
+   Ideation artifact written: docs/ideation/<slug>-<date>.md
+   Top pick: <#1 premise> — score <Y.YY>
+   Next: invoke /harness:brainstorming <feature> to take a candidate into a spec, OR /harness:roadmap to enqueue picks for later.
+   ```
+
+---
+
+## Harness Integration
+
+- **Harness MCP tools consumed by this skill** (canonical execution path — no project-local `@harness-engineering/core` required):
+  - `read_strategy({ path })` — Phase 1 grounding oracle. Returns `{ present, valid, doc?, error? }` (the server runs `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` internally).
+- **`@harness-engineering/core`** (only directly relevant when the MCP server is unavailable):
+  - `validateStrategy(cwd)`, `parseStrategyDoc(raw)` + `asStrategyDoc(parsed)`, `StrategyDocSchema`, `REQUIRED_STRATEGY_SECTIONS`.
+- **Boundary with `harness-strategy`** — strategy WRITES `STRATEGY.md`; ideate READS it. Ideate never modifies `STRATEGY.md` and never offers to repair an invalid one (suggest `/harness:strategy` and continue without grounding).
+- **Boundary with `harness-brainstorming`** — ideate produces a ranked artifact at `docs/ideation/`; brainstorming produces a spec at `docs/changes/<feature>/proposal.md`. They have non-overlapping output locations (Decision 5 of the strategic-anchor proposal). Ideate's artifact may be cited as an input in a brainstorming spec; brainstorming's spec is NEVER auto-derived from ideate's artifact.
+- **Boundary with `harness-roadmap-pilot`** — ideate generates fresh candidates; roadmap-pilot prioritizes existing roadmap entries. If a user wants ranking-only over the existing roadmap, that is roadmap-pilot, not ideate.
+
+## Success Criteria
+
+- Exactly one artifact is written per run, at `docs/ideation/<slug>-<YYYY-MM-DD>.md`. No spec, plan, ADR, or code is produced.
+- The artifact contains exactly the number of candidates the user requested (after clamping to `[5, 25]`).
+- Every candidate has all 7 fields populated (premise, persona, complexity, key_risk, impact, confidence, effort).
+- Each candidate has a strongest-objection paragraph; objections the user elected to answer have a rebuttal paragraph.
+- Ranking is by `(impact × confidence) ÷ effort` with the 1/2/3 mapping. Strategy-alignment bonus is applied only when STRATEGY.md is present AND the absolute base-score delta is ≤ 0.05.
+- When `STRATEGY.md` is absent or invalid, the skill completes without error and the artifact's frontmatter records `strategy_grounded: false`.
+- The output filename collision rule (6-char hex suffix on same-day re-run for the same focus) produces a stable, deterministic suffix from `sha1(focus + iso_timestamp)`.
+- The artifact's frontmatter explicitly states the ranking formula so a future reader can reproduce the order.
+
+## Examples
+
+### Example: With STRATEGY.md (grounded, 10 candidates)
+
+```
+User: /harness:ideate --focus "pulse-report follow-up routing"
+
+Phase 1:
+  Topic confirmed: "pulse-report follow-up routing"
+  Count: 10
+  STRATEGY.md detected — grounding enabled.
+  Tracks read: ["pulse-reports", "compound-engineering", "feedback-loops"]
+  Who-it's-for read: "engineering teams adopting harness"
+
+Phase 2 (excerpt):
+  1. Auto-assign followups to the on-call rotation. Persona: on-call engineer.
+     Complexity: medium. Key risk: rotation data may be stale. I/C/E: H/M/M.
+  ...
+  10. Email-digest weekly pulse for distributed teams. Persona: async-first eng.
+     Complexity: low. Key risk: duplicates Slack. I/C/E: M/L/L.
+
+Phase 3:
+  User selects "answer 1, 4, 7"; provides three one-paragraph rebuttals.
+
+Phase 4 (ranking, excerpt):
+  - Idea 1 base score: (H=3 × M=2) ÷ M=2 = 3.00
+    Idea 7 base score: 2.97 (|Δ| = 0.03 ≤ 0.05 — alignment window applies)
+    Idea 1 alignment: track match "pulse-reports" (+0.5) + persona match (+0.25) = +0.75 → final 3.75
+    Idea 7 alignment: track match "feedback-loops" (+0.5) → final 3.47
+    Idea 4 base score: 2.50 (|Δ vs idea 1| = 0.50 > 0.05 — alignment recorded but not applied)
+
+Phase 5:
+  Write docs/ideation/pulse-report-follow-up-routin-2026-06-02.md
+  Top pick: "Auto-assign followups to the on-call rotation" — score 3.50
+  Next: invoke /harness:brainstorming "Pulse Followup Routing" to take this into a spec.
+```
+
+### Example: Without STRATEGY.md (no grounding, 5 candidates)
+
+- Phase 1: `read_strategy` returns `{ present: false }`. Strategy grounding disabled; skill prints the one-line note and continues.
+- Phase 2: 5 candidates generated. No track-alignment guidance applies; coverage of complexity surface remains a rule.
+- Phase 4: ranking uses `(impact × confidence) ÷ effort` only. No tiebreaker bonus is added.
+- Phase 5: artifact frontmatter has `strategy_grounded: false` and `strategy_path: null`. Handoff still routes the user to brainstorming.
+
+### Example: Slug collision (same focus, same day)
+
+- Run 1: writes `docs/ideation/onboarding-for-plugin-only-use-2026-06-02.md`.
+- Run 2 (same `--focus`, same day): destination collides. Skill computes `sha1("onboarding for plugin-only users" + "2026-06-02T15:21:04Z").slice(0,6)` → `a3f9b2`. Writes `docs/ideation/onboarding-for-plugin-only-use-2026-06-02-a3f9b2.md`. Both files coexist.
+
+## Gates
+
+- **One artifact per run, exactly.** A second write on the same run violates the Iron Law.
+- **Never modify `STRATEGY.md`.** Even on present-but-invalid: surface the error and continue without grounding. Repair is `/harness:strategy`'s job.
+- **Never derive a spec from ideate's artifact automatically.** Brainstorming is human-confirmed; ideate's output is an INPUT to brainstorming, not a replacement.
+- **Never produce 0 ideas.** Clamping enforces `N ≥ 5`. If the model would generate near-duplicates to reach N, prefer fewer-but-distinct over more-but-redundant — re-prompt within the skill to diversify.
+- **The strategy-alignment tiebreaker is bounded.** Maximum bonus is `+0.75` (`0.5 + 0.25`) and only applies when `|Δbase_score| ≤ 0.05`. The bonus must NEVER override a clear base-score winner.
+
+## Escalation
+
+- **User wants the artifact converted to a spec automatically.** Refuse; cite the Iron Law. Offer `/harness:brainstorming "<top-pick title>"` as the next step.
+- **STRATEGY.md is present but invalid.** Print the validation error verbatim; do not block. Suggest `/harness:strategy` and continue with `strategy_grounded: false`.
+- **User insists on `N > 25`.** Clamp to 25 and inform; offer to chain a second run with a different focus argument.
+- **User insists every idea is `medium` on all three axes.** Push back once: "If everything is medium, ranking is uninformative — what is your highest-impact vs. highest-confidence outlier?" If they decline to differentiate, write the artifact anyway with a frontmatter `quality_flag: undifferentiated` note.
+- **Output directory cannot be created.** Surface the filesystem error verbatim. Do not silently write to a fallback path.