@harness-engineering/cli 3.1.0 → 4.0.1

package/dist/agents/personas/harness-pm.yaml

@@ -0,0 +1,33 @@
+version: 2
+name: Harness PM
+description: Owns acceptance-criteria and eval-coverage quality for specs
+role: >
+  Owns acceptance-criteria and eval-coverage quality. Reviews every spec for
+  measurable, testable, complete success criteria; flags user-visible behaviors
+  with no covering test; blocks specs that ship with no measurable criteria.
+  The upstream twin of the outcome-eval ship gate.
+skills:
+  - acceptance-eval
+steps:
+  - command: validate
+    when: always
+  - skill: acceptance-eval
+    when: on_pr
+    output: auto
+  - skill: acceptance-eval
+    when: manual
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - 'docs/changes/**'
+  - event: manual
+config:
+  severity: error
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: true
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/skills/claude-code/acceptance-eval/SKILL.md

@@ -0,0 +1,92 @@
+# Acceptance Eval
+
+> Pre-execution LLM-judgment: does this spec carry measurable, testable, complete acceptance criteria before work begins? Resolves the spec's acceptance section, critiques observability / testability / completeness (advisory `criteriaFindings`), flags user-visible behaviors with no covering test (advisory `coverageFindings`), and emits a confidence-rated `AcceptanceVerdict` (`MEASURABLE | NOT_MEASURABLE | INCONCLUSIVE`) with a rationale. Merge authority is derived in TypeScript, never trusted from the LLM: a high-confidence `NOT_MEASURABLE` blocks merge; every other verdict is advisory. The upstream twin of the `outcome-eval` ship gate — it keeps the downstream gate fed with judgable specs.
+
+## When to Use
+
+- On every spec entering the repo under `docs/changes/**` — triggered `on_pr` (and `manual`) — before execution begins.
+- When you need a durable, structured answer to "can this spec's success be objectively judged later?"
+- NOT for judging whether an implementation satisfied its spec post-execution (use `outcome-eval`, the downstream twin).
+- NOT for authoring acceptance criteria — `acceptance-eval` reviews; humans own the thinking layer. It never writes the criteria it judges.
+- NOT for rule-based floors (lint/architecture/entropy) or other craft ceilings — those run elsewhere.
+- NOT when no judgable spec section exists — the verdict degrades to INCONCLUSIVE/advisory and never blocks.
+
+## Process
+
+### Phase 1: RESOLVE — Find the judgment section
+
+The evaluator resolves the section internally via the fallback chain `## Success Criteria` -> `## User-Visible Behavior` -> `## Overview` (reusing `outcome-eval`'s resolver, not a fork), recording the match in `judgedAgainst`. No manual action — pass `specPath` and let `AcceptanceEvaluator` resolve. If no section is judgable, the verdict is INCONCLUSIVE/advisory.
+
+### Phase 2: GATHER — Locate test evidence for coverage (optional)
+
+For responsibility (b), supply test evidence so the judge can flag user-visible behaviors with no covering test: pass `testGlobs` (globs the tool reads) or `testContent` (snippets you already read). This evidence is optional: omitting it degrades `coverageFindings` to advisory-empty but NEVER affects the (c) measurability gate. Gather it when the spec describes user-visible behavior.
+
+### Phase 3: JUDGE — Invoke the evaluator
+
+1. Invoke the MCP tool `mcp__harness__acceptance_eval` with `{ specPath }` plus optional `{ testGlobs | testContent, model }`. The tool constructs `AcceptanceEvaluator` cli-side and returns the verdict; the supported v1 provider is the anthropic analysis provider (`ANTHROPIC_API_KEY`).
+2. The LLM returns ONLY `measurability / confidence / criteriaFindings / coverageFindings / rationale`. `authority` is computed in TypeScript from `(measurability, confidence)` via `deriveAcceptanceAuthority` and is never read from the LLM — do not attempt to override it. The tool returns the verdict exactly as the evaluator derives it.
+3. The call is degrade-safe: provider failure (incl. no `ANTHROPIC_API_KEY`), empty test evidence, or a missing judgable section yields INCONCLUSIVE/low/advisory. It never throws and never blocks.
+
+### Phase 4: GATE — Render and (conditionally) halt
+
+1. Render the verdict: `measurability`, `confidence`, `judgedAgainst`, `rationale`, `criteriaFindings` (a, advisory), and `coverageFindings` (b, advisory).
+2. Authority rule (must match `deriveAcceptanceAuthority`): authority is `blocking` **iff** `measurability === 'NOT_MEASURABLE' && confidence === 'high'`; every other combination — including all `INCONCLUSIVE` and `MEASURABLE` cases, and all `medium`/`low` `NOT_MEASURABLE` — is `advisory`.
+3. **On a blocking verdict: HALT before merge.** Report the missing measurable criteria and stop; the spec must not merge. Resolution requires a human adding measurable success criteria and re-running `acceptance-eval`.
+4. On an advisory verdict: report the `criteriaFindings` and `coverageFindings` for human attention and proceed. Advisory findings do not stop the workflow.
+
+## Harness Integration
+
+- **`mcp__harness__acceptance_eval`** — MCP tool (the invocation surface). Inputs: `specPath` (required), `testGlobs` / `testContent` (optional (b) evidence), `model` (optional). The handler builds the cli `AnalysisProvider`, constructs `AcceptanceEvaluator`, and returns the `AcceptanceVerdict` with `authority` exactly as derived in TypeScript. (No graph persistence in v1 — the seam is documented in the tool header.)
+- **Evaluator surface:** `AcceptanceEvaluator`, `deriveAcceptanceAuthority`, `acceptanceVerdictSchema`, `AcceptanceVerdict` are exported from `@harness-engineering/intelligence`. The section resolver is imported from `outcome-eval`, not duplicated.
+- **Provider path (v1 supported):** the anthropic analysis provider (`ANTHROPIC_API_KEY`). When no provider is configured the call degrades to INCONCLUSIVE/advisory.
+- **Relationship to `outcome-eval`:** `acceptance-eval` is the upstream twin. It guards spec measurability before execution; `outcome-eval` judges implementation satisfaction after. The same "authority is never read from the LLM" discipline spans both ends of the lifecycle.
+
+## Known Limitations
+
+- **Coverage findings (b) are heuristic and advisory.** Without `testGlobs`/`testContent` they are advisory-empty; even with evidence they are LLM-judgment over the behavior section plus located tests, not a graph-backed coverage map (deferred — see spec Decision D4). Heuristic misses are low-harm because (b) never blocks.
+- **The (c) gate blocks only on high-confidence NOT_MEASURABLE.** A spec with weak-but-present criteria yields an advisory verdict, not a block — intentional, to avoid taste-blocks-merge false positives.
+- **openai-compatible strict mode** is not the v1 path; the supported provider is anthropic/claude-cli.
+
+## Success Criteria
+
+See `docs/changes/harness-pm-persona/proposal.md` for the full criteria. This skill satisfies SC1 (skill exists, `tier: 2`, `type: rigid`, four-client artifacts), SC6 (blocking halt on high-confidence NOT_MEASURABLE; advisory-and-proceed otherwise), and SC7 (emits advisory `criteriaFindings` / `coverageFindings`).
+
+## Examples
+
+### Example: NOT_MEASURABLE with high confidence (blocks)
+
+**Input:** a spec whose only "success criteria" are "the feature works well" and "users are happy" — no observable, testable assertions.
+
+**Verdict:**
+
+```
+measurability:   NOT_MEASURABLE
+confidence:      high
+judgedAgainst:   success-criteria
+authority:       blocking
+criteriaFindings:
+  - { target: "'works well' / 'users are happy'", message: "No observable assertion — cannot be tested." }
+rationale:       "The success section contains only subjective statements; nothing can be judged at outcome time."
+```
+
+**Action:** HALT before merge. Report the missing measurable criteria; the spec must not merge until a human adds them.
+
+### Example: measurable criteria (advisory, proceeds)
+
+**Input:** a spec whose Success Criteria list concrete, testable assertions; one user-visible behavior lacks an obvious covering test.
+
+**Verdict:** `measurability: MEASURABLE confidence: high authority: advisory`, with one `coverageFindings` `{target, message}` object (the one user-visible behavior lacking a covering test) surfaced for review. The workflow proceeds.
+
+## Gates
+
+- **Authority is never read from the LLM.** The verdict's `authority` is always `deriveAcceptanceAuthority(measurability, confidence)` computed in TypeScript. If you find yourself letting the model assert blocking/advisory, STOP — that defeats the entire purpose of this gate.
+- **Block only on high-confidence NOT_MEASURABLE.** `authority === 'blocking'` iff `measurability === 'NOT_MEASURABLE' && confidence === 'high'`. Every other combination is advisory. Do not halt on an advisory verdict.
+- **Never author criteria.** `acceptance-eval` reviews specs; it does not write the acceptance criteria it judges. Humans own the thinking layer.
+- **Never block on infrastructure noise.** A provider failure, an unparseable response, or a missing spec section must resolve to INCONCLUSIVE/advisory, never a thrown error or a block. The evaluator enforces this; do not reintroduce a hard failure in the wrapper.
+
+## Escalation
+
+- **Blocking verdict the author disputes:** the resolution is for a human to add measurable success criteria (or fix the section the resolver judged) and re-run `acceptance-eval` — not to override the gate.
+- **Repeated INCONCLUSIVE on a real spec:** usually means no judgable section exists. Confirm the spec has a Success Criteria / User-Visible Behavior / Overview section.
+- **No `ANTHROPIC_API_KEY` configured:** every verdict degrades to INCONCLUSIVE/advisory and nothing blocks. Surface this to the human — the gate is effectively disabled until a provider is configured.
+- **Verdict seems wrong (false positive/negative):** capture the spec section and verdict and route to the maintainers; do not loosen the conservative-confidence prompt ad hoc.

package/dist/agents/skills/claude-code/acceptance-eval/skill.yaml

@@ -0,0 +1,54 @@
+name: acceptance-eval
+version: '0.1.0'
+description: >-
+  Pre-execution LLM-judgment skill: does a spec carry measurable, testable,
+  complete acceptance criteria before work begins? Resolves the spec's
+  acceptance section, critiques observability / testability / completeness
+  (advisory), flags user-visible behaviors with no covering test (advisory),
+  and emits a confidence-rated AcceptanceVerdict
+  (MEASURABLE | NOT_MEASURABLE | INCONCLUSIVE). Authority is derived in
+  TypeScript, never from the LLM: a high-confidence NOT_MEASURABLE blocks
+  merge; every other verdict is advisory. The upstream twin of the
+  outcome-eval ship gate.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - cursor
+  - codex
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+mcp:
+  tool: acceptance_eval
+  # specPath is the only required input. testGlobs/testContent are the (b)
+  # coverage evidence: omitting them degrades coverage findings to
+  # advisory-empty but NEVER affects the (c) measurability gate.
+  input:
+    specPath: 'string (required) — absolute or repo-relative path to the spec markdown to evaluate'
+    testGlobs: 'string[] (optional) — globs locating test files that evidence (b) coverage; omission degrades coverage findings to advisory-empty, never the (c) gate'
+    testContent: 'string (optional) — pre-read test snippets as (b) coverage evidence; an alternative to testGlobs'
+    model: 'string (optional) — model override for the acceptance-eval LLM call'
+type: rigid
+tier: 2
+phases:
+  - name: resolve
+    description: Resolve the judgment section (Success Criteria -> User-Visible Behavior -> Overview), recorded in judgedAgainst
+    required: true
+  - name: gather
+    description: Locate test evidence for (b) coverage via testGlobs/testContent; optional — omission degrades coverage findings, never the (c) gate
+    required: false
+  - name: judge
+    description: Invoke AcceptanceEvaluator; the LLM returns measurability/confidence/criteriaFindings/coverageFindings/rationale; authority is derived in TS via deriveAcceptanceAuthority
+    required: true
+  - name: gate
+    description: Render the verdict; on a blocking verdict (NOT_MEASURABLE + high confidence) HALT before merge
+    required: true
+state:
+  persistent: false

package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md

@@ -8,7 +8,7 @@
 - When the problem space is ambiguous and needs exploration
 - When multiple approaches exist and tradeoffs must be weighed
 - When `on_new_feature` trigger fires and scope is non-trivial
-- NOT when the implementation path is already clear (go straight to harness-planning)
+- NOT when the implementation path is already clear (go straight to harness-planning, or harness-autopilot if the spec already exists)
 - NOT when fixing a bug with an obvious root cause (use harness-debugging or harness-tdd)
 - NOT for simple refactors with no design decisions (use harness-refactoring)
 
@@ -64,22 +64,23 @@ When no arguments are provided (standalone invocation), the skill operates exact
 
 ### Phase 2: EVALUATE -- Ask Questions and Narrow
 
-1. **Ask ONE question at a time.** Ask the most important question first. Wait for the answer. Let it inform the next question. Use `emit_interaction` with `type: 'question'`:
+1. **Ask ONE question at a time, in plain text.** Ask the most important question first. Wait for the answer. Let it inform the next question.
 
-   ```json
-   emit_interaction({
-     path: "<project-root>",
-     type: "question",
-     question: {
-       text: "For auth, which approach should we use?",
-       options: [
-         { "label": "A) Existing JWT middleware", "pros": ["Already in codebase"], "cons": ["No refresh tokens"], "risk": "low", "effort": "low" },
-         { "label": "B) OAuth2 via provider X", "pros": ["Industry standard"], "cons": ["New dependency"], "risk": "medium", "effort": "medium" },
-         { "label": "C) External auth service", "pros": ["Zero maintenance"], "cons": ["Vendor lock-in", "Cost"], "risk": "medium", "effort": "low" }
-       ],
-       recommendation: { "optionIndex": 0, "reason": "Sufficient for current requirements.", "confidence": "high" }
-     }
-   })
+   **Ask directly in your reply. Do NOT route the question through `emit_interaction`, `AskUserQuestion`, or any tool.** `emit_interaction` records the question in state but does not display it to the human — the client collapses it to "Called harness" and the rendered prompt only returns to the model, so the human sees nothing and you end up narrating a question they cannot answer. `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present the question as a markdown table so tradeoffs are scannable, state your recommendation, then STOP and wait for the human's reply:
+
+   ```markdown
+   ### Decision needed: For auth, which approach should we use?
+
+   |            | A) Existing JWT middleware | B) OAuth2 via provider X | C) External auth service |
+   | ---------- | -------------------------- | ------------------------ | ------------------------ |
+   | **Pros**   | Already in codebase        | Industry standard        | Zero maintenance         |
+   | **Cons**   | No refresh tokens          | New dependency           | Vendor lock-in; cost     |
+   | **Risk**   | Low                        | Medium                   | Medium                   |
+   | **Effort** | Low                        | Medium                   | Low                      |
+
+   **Recommendation:** A) Existing JWT middleware (confidence: high) — sufficient for current requirements.
    ```
 
 2. **Prefer multiple choice over open-ended questions.** Give 2-4 concrete options with brief tradeoff notes.
@@ -169,24 +170,21 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
 
 5. **Run `harness validate`** to verify proper placement and project health.
 
-6. **Request sign-off via `emit_interaction`:**
+6. **Request sign-off in plain text.** Ask directly in your reply — do NOT route the request through `emit_interaction` or `AskUserQuestion` (the human will not see it). Present it as:
 
-   ```json
-   emit_interaction({
-     path: "<project-root>",
-     type: "confirmation",
-     confirmation: {
-       text: "Approve spec at <file-path>?",
-       context: "<one-paragraph summary>",
-       impact: "Spec approval unlocks implementation planning. No code changes yet.",
-       risk: "low"
-     }
-   })
+   ```markdown
+   Approve spec at <file-path>?
+
+   Context: <one-paragraph summary>
+   Impact: Spec approval unlocks implementation planning. No code changes yet.
+   Risk: low
+
+   Proceed? (yes/no)
    ```
 
-   The human must explicitly approve before this skill is complete.
+   The human must explicitly approve (a clear "yes") before this skill is complete.
 
-7. **Promote the roadmap row.** If `docs/roadmap.md` exists, transition the named row to `planned` and link the spec in a single structured call (steps 7 and 8 are intentionally ordered so the commit captures the roadmap mutation). Skip silently only when no roadmap exists.
+7. **Promote the roadmap row.** If a roadmap exists (a `docs/roadmap.md` aggregate **or** a `docs/roadmap.d/` shard directory), transition the named row to `planned` and link the spec in a single structured call (steps 7 and 8 are intentionally ordered so the commit captures the roadmap mutation). Skip silently only when no roadmap exists. In sharded mode `manage_roadmap promote` writes the single row's shard under `docs/roadmap.d/` **and** regenerates the `docs/roadmap.md` aggregate — both are staged in step 8.
    - Derive the lookup key from the slash-command `ARGUMENTS` string (D1). Derive the summary from the spec title (the H1 heading).
    - Call `manage_roadmap` with action `promote`, `feature: "<ARGUMENTS>"`, `spec: "docs/changes/<feature>/proposal.md"`, and `summary: "<H1>"`.
    - Branch on the returned `PromoteResult` envelope:
@@ -210,11 +208,11 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
 8. **Commit spec artifacts and roadmap promotion.** After a successful promote (or a silent skip when no roadmap exists), commit the spec, skill recommendations, and the roadmap mutation together so the promotion ships atomically with the spec:
 
    ```bash
-   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md docs/roadmap.md
+   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md docs/roadmap.d/ docs/roadmap.md
    git commit -m "docs(<feature>): add spec and promote to planned"
    ```
 
-   Include `docs/roadmap.md` in `git add` only when it exists; omit it when the project has no roadmap. Do not skip this step — `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats a file, re-add and re-commit.
+   Stage the roadmap by mode: **sharded mode** (`docs/roadmap.d/` present) — stage both `docs/roadmap.d/` (the written shard) and the regenerated `docs/roadmap.md` aggregate; **monolith mode** — stage only `docs/roadmap.md`; **no roadmap** — omit both. Do not skip this step — `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats a file, re-add and re-commit.
 
 9. **Write handoff and suggest transition.** After approval:
 
@@ -241,14 +239,21 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
    }
    ```
 
-   Call `emit_interaction`:
+   **Choose the next skill with the human — ask in plain text, not via `emit_interaction`** (a `transition` records the handoff; it does not surface the choice). Present both paths and recommend autopilot:
+
+   > Spec approved. How do you want to build it?
+   >
+   > - **Autopilot (recommended)** — autonomously chains plan → execute → verify → review, pausing only at decision points. Best when the spec's `## Implementation Order` lays out clear phases.
+   > - **Planning** — work the implementation plan interactively before any execution. Choose this when phases are uncertain or you want to drive the breakdown by hand.
+
+   Record the answer as `<next>` (`autopilot` or `planning`), then call `emit_interaction`:
 
    ```json
    {
      "type": "transition",
      "transition": {
        "completedPhase": "brainstorming",
-       "suggestedNext": "planning",
+       "suggestedNext": "<next>",
        "reason": "Spec approved and written to docs/",
        "artifacts": ["<spec path>"],
        "requiresConfirmation": true,
@@ -269,7 +274,10 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
    }
    ```
 
-   If confirmed: invoke harness-planning with the spec path.
+   If confirmed, dispatch by the recorded choice:
+   - `autopilot` → invoke harness-autopilot with `--spec <spec path>`.
+   - `planning` → invoke harness-planning with the spec path.
+
    If declined: stop. The handoff is written for future invocation.
 
 ---
@@ -348,11 +356,11 @@ Technical claims about existing code, architecture, or tradeoffs MUST cite evide
 - **`harness check-docs`** -- Verify spec does not conflict with existing docs.
 - **`STRATEGY.md` grounding (Phase 1 step 0a)** -- When present at repo root and valid, loaded via the `read_strategy` MCP tool (which the harness MCP server backs with `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` from `@harness-engineering/core` — projects do not need core installed). Soft-fails when absent or invalid; cites strategy sections in the spec's evidence annotations when present. Boundary with `harness-strategy`: brainstorming READS; `harness-strategy` WRITES. Never modify `STRATEGY.md` from this skill.
 - **Spec location** -- `docs/changes/<feature>/proposal.md`.
-- **Handoff** -- Once approved, invoke harness-planning to create the implementation plan.
+- **Handoff** -- Once approved, hand off per the human's choice: harness-autopilot (recommended -- autonomous plan → execute → verify → review) or harness-planning (interactive plan only).
 - **Session directory** — When session slug is known, handoff goes to `.harness/sessions/<slug>/handoff.json`. The session directory structure is: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and file lists). Do not write to `.harness/handoff.json` in session context.
-- **Spec commit** -- After sign-off, the Phase 4 step 8 commit captures `docs/changes/<feature>/proposal.md`, `docs/changes/<feature>/SKILLS.md`, and the promoted `docs/roadmap.md` together so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
+- **Spec commit** -- After sign-off, the Phase 4 step 8 commit captures `docs/changes/<feature>/proposal.md`, `docs/changes/<feature>/SKILLS.md`, and the promoted roadmap together (in sharded mode: the `docs/roadmap.d/` shard plus the regenerated `docs/roadmap.md` aggregate; in monolith mode: `docs/roadmap.md`) so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
 - **Roadmap promotion** -- After approval (Phase 4 step 7), call `manage_roadmap` action `promote` to transition the named row to `planned` and link the spec atomically with the spec commit. Falls back to `add` (create new row) when the row does not exist; refuses on `in-progress`/`done`/`ambiguous`. Skip silently if no roadmap.
-- **`emit_interaction`** -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).
+- **`emit_interaction`** -- End of Phase 4 to record the transition to harness-autopilot or harness-planning (the human picks; default autopilot). The choice itself is asked in plain text -- `emit_interaction` records the confirmed transition, it does not surface the question.
 
 #### Requirement Phrasing
 

package/dist/agents/skills/claude-code/harness-brainstorming/skill.yaml

@@ -53,4 +53,5 @@ state:
   files: []
 depends_on:
   - harness-planning
+  - harness-autopilot
   - harness-soundness-review

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

@@ -539,17 +539,16 @@ gh api repos/{owner}/{repo}/pulls/{pr}/comments \
 
 ### Review Acceptance
 
-```json
-emit_interaction({
-  path: "<project-root>",
-  type: "confirmation",
-  confirmation: {
-    text: "Review complete: <Assessment>. Accept review?",
-    context: "<N critical, N important, N suggestion findings>",
-    impact: "Accepting finalizes findings. Approve = ready for merge. Request-changes = fixes needed.",
-    risk: "<low if approve, high if critical>"
-  }
-})
+Ask for acceptance directly in your reply. Do NOT route this through `emit_interaction`, `AskUserQuestion`, or any tool. `emit_interaction` records the prompt but does not display it to the human (the client collapses the call to "Called harness" and the rendered text only returns to the model); `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI). Present it as:
+
+```markdown
+Review complete: <Assessment>. Accept review?
+
+Context: <N critical, N important, N suggestion findings>
+Impact: Accepting finalizes findings. Approve = ready for merge. Request-changes = fixes needed.
+Risk: <low if approve, high if critical>
+
+Proceed? (yes/no)
 ```
 
 #### Handoff and Transition

package/dist/agents/skills/claude-code/harness-execution/SKILL.md

@@ -186,40 +186,37 @@ Three checkpoint types. Each requires pausing execution.
 
 **`[checkpoint:human-verify]` — Show and Confirm**
 
-Stop. Present via `emit_interaction`:
+Stop. Present the confirmation in plain text in your reply — do NOT route this through `emit_interaction`, `AskUserQuestion`, or any tool. `emit_interaction` records the prompt but does not display it to the human (the client collapses the call to "Called harness" and the rendered text only returns to the model); `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI).
 
-```json
-emit_interaction({
-  path: "<project-root>",
-  type: "confirmation",
-  confirmation: {
-    text: "Task N complete. Output: <summary>. Continue to Task N+1?",
-    context: "<test output or diff summary>",
-    impact: "Continuing proceeds to next task. Declining pauses for review.",
-    risk: "low"
-  }
-})
+```markdown
+Task N complete. Output: <summary>. Continue to Task N+1?
+
+Context: <test output or diff summary>
+Impact: Continuing proceeds to next task. Declining pauses for review.
+Risk: low
+
+Proceed? (yes/no)
 ```
 
 Wait for human confirmation.
 
 **`[checkpoint:decision]` — Present Options and Wait**
 
-Stop. Present via `emit_interaction`:
+Stop. Present the decision in plain text in your reply — do NOT route this through `emit_interaction`, `AskUserQuestion`, or any tool. `emit_interaction` records the prompt but does not display it to the human (the client collapses the call to "Called harness" and the rendered text only returns to the model); `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI).
 
-```json
-emit_interaction({
-  path: "<project-root>",
-  type: "question",
-  question: {
-    text: "Task N requires a decision: <description>",
-    options: [
-      { label: "<option A>", pros: ["..."], cons: ["..."], risk: "low", effort: "low" },
-      { label: "<option B>", pros: ["..."], cons: ["..."], risk: "medium", effort: "medium" }
-    ],
-    recommendation: { optionIndex: 0, reason: "<why>", confidence: "medium" }
-  }
-})
+Present the options as a markdown table so tradeoffs are scannable, state your recommendation, then STOP and wait for the human's reply:
+
+```markdown
+### Decision needed: Task N requires a decision: <description>
+
+|            | A) <option A>   | B) <option B>   |
+| ---------- | --------------- | --------------- |
+| **Pros**   | <option A pros> | <option B pros> |
+| **Cons**   | <option A cons> | <option B cons> |
+| **Risk**   | low             | medium          |
+| **Effort** | low             | medium          |
+
+**Recommendation:** A) <option A> (confidence: medium) — <why>.
 ```
 
 Wait for human choice.
@@ -378,6 +375,7 @@ Claims about task completion, test results, or code behavior MUST cite evidence:
 - **`harness state learn "<message>"`** — Append a learning from CLI.
 - **State/Learnings files** — Session-scoped when session known, otherwise `.harness/`. State updated after every task; learnings append-only.
 - **Roadmap claim** — Phase 2 Step 0: `manage_roadmap update` with `status: in-progress` + `assignee: <currentUser>` claims the item at execution start (the assignee = "who is executing" invariant). Stop if `currentUser` is unresolvable. Marking the row `done` later auto-clears the assignee via the lifecycle `setStatus` chokepoint — never leave a non-in-progress row assigned (RMH005).
+- **Auto-done (do NOT hand-mark rows done)** — A row reaches `done` automatically when the implementing PR merges and closes its linked issue: the merge-triggered auto-done reconciler flips exactly that shard via `External-ID` (CI Action authoritative; `harness roadmap reconcile` is the offline fallback). Execution should claim the row `in-progress` and let the merge drive it to `done` — do not call `manage_roadmap update status:done` by hand. See knowledge [`merge-triggered-auto-done.md`](../../../../docs/knowledge/roadmap/merge-triggered-auto-done.md). In sharded mode (`docs/roadmap.d/` present) the claim writes one shard and regenerates the aggregate.
 - **Roadmap sync** — After plan completion, `manage_roadmap sync` with `apply: true`. Mandatory when roadmap exists. No `force_sync: true`.
 - **`emit_interaction`** — Auto-transition to harness-verification at plan completion.
 

package/dist/agents/skills/claude-code/harness-integration/SKILL.md

@@ -66,7 +66,7 @@ Before running sub-phases, resolve the effective integration tier:
    Tier escalated from `small` to `medium`: 8 new exports detected.
    ```
 
-   Use `emit_interaction` with type `confirmation` to inform and get acknowledgment.
+   Inform the human and get acknowledgment in plain text in your reply (do NOT route this through `emit_interaction` or `AskUserQuestion` — they record the prompt but do not display it to the human, so they won't see it).
 
 ---
 
@@ -213,7 +213,7 @@ Skip this sub-phase for `small` tier or `fast` rigor. For medium and large tiers
    <What follows from this decision -- positive, negative, and neutral?>
    ```
 
-   d. **Present for review.** In `thorough` rigor, present each ADR draft via `emit_interaction` (type: `confirmation`) and wait for human approval. In `standard` rigor, auto-approve but log the draft for review.
+   d. **Present for review.** In `thorough` rigor, present each ADR draft in plain text in your reply and wait for human approval — do NOT route it through `emit_interaction` or `AskUserQuestion`, which record the prompt but do not display it to the human (the client collapses the call to "Called harness" and the text only returns to the model). In `standard` rigor, auto-approve but log the draft for review.
 
 #### Knowledge Graph Enrichment (medium + large tiers)
 
@@ -266,7 +266,7 @@ Skip this sub-phase for `small` tier or `fast` rigor. For medium and large tiers
 
 ---
 
-### Sub-Phase 3: UPDATE (medium + large tiers)
+### Sub-Phase 3: UPDATE (medium and large tiers)
 
 Report progress: `**[UPDATE]** Checking project metadata updates`
 
@@ -364,22 +364,24 @@ After all applicable sub-phases complete, produce the combined integration repor
 
    Immediately invoke harness-code-review without waiting for user input.
 
-4. **On FAIL:** Do NOT emit a transition. Report incomplete items with fix instructions. Present options via `emit_interaction`:
+4. **On FAIL:** Do NOT emit a transition. Report incomplete items with fix instructions, then ask the human how to proceed in plain text.
 
-   ```json
-   emit_interaction({
-     path: "<project-root>",
-     type: "question",
-     question: {
-       text: "Integration failed. <N> items incomplete. How to proceed?",
-       options: [
-         { "label": "fix -- Re-enter EXECUTE with integration-specific fix tasks, then re-VERIFY, re-INTEGRATE", "risk": "low", "effort": "medium" },
-         { "label": "skip -- Record decision and proceed to REVIEW (human override)", "risk": "medium", "effort": "low" },
-         { "label": "stop -- Save state and exit", "risk": "low", "effort": "low" }
-       ],
-       recommendation: { "optionIndex": 0, "reason": "Fixing integration gaps now prevents review rework.", "confidence": "high" }
-     }
-   })
+   **Ask directly in your reply. Do NOT route the question through `emit_interaction`, `AskUserQuestion`, or any tool.** `emit_interaction` records the prompt but does not display it to the human — the client collapses the call to "Called harness" and the rendered text only returns to the model, so the human sees nothing and you end up narrating a question they cannot answer. `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present the options as a markdown table, state your recommendation, then STOP and wait for the human's reply:
+
+   ```markdown
+   ### Decision needed: Integration failed. <N> items incomplete. How to proceed?
+
+   |            | fix                                                                                | skip                                                   | stop                      |
+   | ---------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------- |
+   | **What**   | Re-enter EXECUTE with integration-specific fix tasks, then re-VERIFY, re-INTEGRATE | Record decision and proceed to REVIEW (human override) | Save state and exit       |
+   | **Pros**   | Closes gaps before review                                                          | Unblocks progress immediately                          | Preserves state for later |
+   | **Cons**   | Another execute/verify cycle                                                       | Ships with known gaps                                  | No forward progress       |
+   | **Risk**   | Low                                                                                | Medium                                                 | Low                       |
+   | **Effort** | Medium                                                                             | Low                                                    | Low                       |
+
+   **Recommendation:** fix (confidence: high) — fixing integration gaps now prevents review rework.
    ```
 
    - **fix:** Record fix tasks in handoff. The autopilot re-enters EXECUTE with those tasks.
@@ -449,7 +451,7 @@ Every pass/fail assertion in the integration report MUST include concrete eviden
 - **`harness check-deps`** -- Run during WIRE if new modules were added.
 - **`ingest_source`** -- Run during MATERIALIZE to enrich knowledge graph with decision nodes.
 - **`manage_roadmap`** -- Run during UPDATE to sync roadmap status. Use `sync` with `apply: true`.
-- **`emit_interaction`** -- Tier escalation notification, ADR review (thorough mode), fail/skip/stop decision, transition to REVIEW on pass.
+- **`emit_interaction`** -- Used only for the transition to REVIEW on pass. Tier escalation, ADR review (thorough mode), and fail/skip/stop decisions are asked in plain text in your reply.
 - **Session directory** -- `.harness/sessions/<slug>/` contains all report files. Do not write to global `.harness/` when session slug is known.
 
 ## Success Criteria