@harness-engineering/cli 3.0.1 → 4.0.0

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

@@ -0,0 +1,173 @@
+# Harness Maintenance Pipeline
+
+> One on-demand entry point for project maintenance. Runs the checks that are actually overdue, triages what needs attention, and asks you — in plain text — which to fix. A thin wrapper over `harness maintenance run`; it owns no state of its own.
+
+## When to Use
+
+- You want to answer "which maintenance did I forget to run?" without standing up an orchestrator.
+- At a milestone or before a release, to sweep overdue health checks (dead code, doc drift, dependency health, security, hotspots, project health).
+- When you want a report first and an explicit, opt-in fix step — never a surprise PR.
+- NOT for running a single known check — call that skill or `harness maintenance run --only <id>` directly.
+- NOT for the autonomous cron fix-and-PR path — that is the orchestrator scheduler's job; this is the human-invoked, report-first path.
+
+## What this skill does NOT do
+
+- It does not implement any maintenance check, scheduler, or registry — the CLI and the existing 22-task registry are the single source of truth.
+- It does not write artifacts. The CLI writes `.harness/maintenance/last-run-summary.json` and records history; this skill only reads and relays.
+- It does not open PRs. Fixes are opt-in via the explicit fix step; when a backend is configured, `--fix` dispatches a real agent that commits to the worktree (no PR). When no backend is configured it honestly skips (see Phase 3 / FIX).
+
+## Process
+
+### Phase 1: SWEEP — run the overdue report
+
+1. Run the report-mode sweep and capture stdout:
+
+   ```bash
+   harness maintenance run --json
+   ```
+
+   No flags = overdue, sweep-eligible tasks only, report mode (no PRs). Capture both stdout (the JSON report) and the exit code.
+
+2. Parse stdout as a `ConsolidatedReport`:
+
+   ```ts
+   // shape emitted by the CLI (packages/cli/src/commands/maintenance-run.ts)
+   {
+     generatedAt: string;
+     mode: 'report' | 'fix';
+     fix: boolean;
+     exitCode: 0 | 1;
+     tasks: Array<{
+       taskId: string;
+       status: 'success' | 'failure' | 'skipped' | 'no-issues';
+       findings: number;       // a COUNT — there is no per-finding severity
+       fixed: number;
+       prUrl: string | null;
+       summary: string;        // 'clean' | `${n} finding(s)` | error text
+       error?: string;
+     }>;
+     overdueNowCurrent: string[];
+   }
+   ```
+
+   If capturing stdout is awkward, read the same object from `.harness/maintenance/last-run-summary.json` with the Read tool.
+
+3. Read the **exit code**: `0` = the sweep completed (findings are NOT failures); `1` = at least one check failed to execute; `2` = invalid invocation (a bug in how this skill called the CLI — fix the invocation, do not report it as a finding).
+
+4. If `tasks` is empty, tell the human "All maintenance is current — nothing overdue." and stop. Do not invent work.
+
+### Phase 2: TRIAGE — present a human-readable summary
+
+There is no per-finding severity in the report, so triage by **status** then **findings count** (rows arrive pre-sorted failures-first, then findings-descending). Bucket the tasks:
+
+- **Failed to execute** — `status === 'failure'`. The check itself crashed; surface `summary`/`error`. These are the most urgent: a finding you cannot see is worse than one you can.
+- **Needs attention** — `findings > 0` (and not a failure). Order by `findings` descending. Derive a coarse domain from the task id (e.g. `dead-code`, `doc-drift`, `dependency-health`, `security`, `hotspots`, `project-health`).
+- **Skipped (couldn't run)** — `status === 'skipped'`. A precondition gate was not met, so the check **never ran** — it is NOT clean, it has simply told you nothing. Report these distinctly from clean tasks so the human knows coverage was incomplete (and can decide whether the precondition is worth satisfying). Summarize as a count and, if useful, surface `summary` for why it was gated.
+- **Clean** — `status` is `no-issues`/`success` with `findings === 0`. The check ran and found nothing. Summarize as a count ("8 checks clean"); do not enumerate unless asked. Do NOT fold `skipped` tasks in here — a gated check that never ran is not a clean result.
+
+Render a compact summary, for example:
+
+```
+Maintenance sweep (report mode) — 18 overdue tasks ran, exit 0
+
+Failed to execute (1):
+  stale-constraints   — check crashed: <summary>
+
+Needs attention (3):
+  dead-code           — 12 finding(s)
+  doc-drift           —  4 finding(s)
+  dependency-health   —  1 finding(s)
+
+Skipped — couldn't run (1): license-audit (precondition not met)
+
+Clean (13): project-health, hotspots, security, …
+```
+
+If `overdueNowCurrent` is non-empty, add a one-line footer: "N tasks were overdue and are now marked current."
+
+### Phase 3: FIX — ask in plain text, then opt in
+
+1. **Ask the human in plain text, in your own reply.** Do NOT use `emit_interaction` and do NOT use `AskUserQuestion` for this — those channels do not reliably reach the human (an `emit_interaction` ask collapses to "Called harness" and the human never sees the question). Write the question as ordinary text, listing the actionable task ids (the "Failed to execute" and "Needs attention" buckets) and asking which, if any, to fix. For example:
+
+   > These tasks have findings: `dead-code` (12), `doc-drift` (4), `dependency-health` (1). Which would you like me to fix? Reply with a comma-separated list of task ids, "all", or "none".
+
+   Then stop and wait for the human's reply. Do not proceed to a fix without an explicit answer.
+
+2. **If the human picks tasks**, re-invoke the CLI in fix mode, scoped to exactly those ids — and capture **both** streams separately:
+
+   ```bash
+   harness maintenance run --only <comma,separated,ids> --fix --json
+   ```
+
+   stdout stays a clean, parseable `ConsolidatedReport` (parse it as JSON, same shape as the sweep). Any honesty notice is written to **stderr**, NOT stdout — so capture stderr too (e.g. redirect to a separate file/buffer) and inspect it. If you only read stdout you will silently drop the notice; if you merge stderr into stdout you will break `JSON.parse`. Keep them apart: JSON ← stdout, notice ← stderr.
+
+3. **Relay the result honestly.** `--fix` threads fix mode through the **real agent dispatcher** (#679): when a backend is configured for the default maintenance backend, the agent runs and commits its fixes directly to the worktree — there is **no PR** (`prUrl` stays `null`), and `fixed` is the real commit count. When **no** backend is configured (a plain checkout with no `agent.backends` in `harness.orchestrator.md`), `--fix` does not crash and does not pretend to work — it skips dispatch and prints this notice to **stderr** (which is why step 2 captures stderr separately):
+
+   > `--fix: no agent backend configured for maintenance dispatch — dispatch was skipped and nothing was fixed. Configure agent.backends in harness.orchestrator.md (and maintenance.aiBackend), or run maintenance via the orchestrator.`
+
+   Inspect the captured stderr for that notice and, if present, surface it verbatim. Report what the CLI actually did (the stdout report's `fixed` counts; `prUrl` is always `null` — there is no PR) — never claim a fix was applied or a PR opened when the report does not show one.
+
+4. **If the human picks "none"**, stop. The report stands on its own.
+
+## Harness Integration
+
+- **`harness maintenance run --json`** — the report-mode sweep this skill wraps. Runs overdue, sweep-eligible tasks only and emits the `ConsolidatedReport` to stdout (also written to `.harness/maintenance/last-run-summary.json`). This is the single entry point — the skill adds no execution path of its own.
+- **`harness maintenance run --only <ids> --fix --json`** — the opt-in fix leg, scoped to the ids the human picked. Threads `mode: 'fix'` through the same `TaskRunner`, using the real agent dispatcher (#679). Capture stdout (the JSON report) and stderr **separately**: when no agent backend is configured it prints the honest no-backend skip notice to stderr (stdout stays clean JSON) — inspect that captured stderr and relay any notice verbatim.
+- **`harness maintenance list` / `harness maintenance show <id>`** — inspect the registry (the 22-task source of truth) when the human wants to know what a task id means before choosing to fix it.
+- **Read tool on `.harness/maintenance/last-run-summary.json`** — the documented fallback parse path if capturing `--json` stdout is awkward on a given platform. The skill never writes this file; the CLI owns it.
+
+## Gates
+
+- **Plain-text ask only.** The "which to fix?" question must be ordinary text in your reply. Never route it through `emit_interaction` or `AskUserQuestion`.
+- **Report before fix, always.** Never pass `--fix` on the first sweep. Fix is opt-in after the human sees the report and chooses.
+- **No invented findings.** Report only what the `ConsolidatedReport` contains. If `tasks` is empty, say so and stop.
+- **No self-persistence.** Do not write `.harness/maintenance/*` or any report file — the CLI owns artifacts.
+- **Honest fix status.** Relay what the CLI reports: real `fixed` counts when a backend dispatched, or the no-backend skip notice (if it appears on stderr) when it did not. `prUrl` is always `null` — the agent commits to the worktree; never imply a PR was opened.
+
+## Success Criteria
+
+- Ran `harness maintenance run --json`, parsed the consolidated report, and read the exit code.
+- Presented a triaged summary bucketed by status (failed / needs-attention / clean) and ordered by findings count.
+- Asked the human in plain text which tasks to fix, and waited for a reply.
+- On opt-in, re-invoked `--only <ids> --fix` and relayed the result (real `fixed` counts, or the honest no-backend skip notice if it appeared) verbatim.
+- Wrote no files of its own.
+
+## Examples
+
+### Example: Milestone sweep with mixed results
+
+The human invokes the skill before tagging a release.
+
+1. **SWEEP:** Run `harness maintenance run --json`. Exit code `0`; `tasks` has 18 rows; `overdueNowCurrent` lists 18 ids.
+2. **TRIAGE:** Bucket the pre-sorted rows:
+
+   ```
+   Maintenance sweep (report mode) — 18 overdue tasks ran, exit 0
+
+   Failed to execute (1):
+     stale-constraints   — check crashed: cannot read .harness/constraints.json
+
+   Needs attention (3):
+     dead-code           — 12 finding(s)
+     doc-drift           —  4 finding(s)
+     dependency-health   —  1 finding(s)
+
+   Clean (14): project-health, hotspots, security, …
+   18 tasks were overdue and are now marked current.
+   ```
+
+3. **FIX (plain-text ask):** In the reply, write: "These tasks have findings: `dead-code` (12), `doc-drift` (4), `dependency-health` (1), plus `stale-constraints` failed to execute. Which would you like me to fix? Reply with a comma-separated list of task ids, \"all\", or \"none\"." Then stop and wait.
+4. The human replies `dead-code,doc-drift`. Run `harness maintenance run --only dead-code,doc-drift --fix`. With a backend configured, the agent dispatches and commits its fixes to the worktree — report the real `fixed` counts from the report (`prUrl: null` — there is no PR). If no backend is configured, the CLI prints to stderr: `--fix: no agent backend configured for maintenance dispatch — dispatch was skipped and nothing was fixed. Configure agent.backends in harness.orchestrator.md (and maintenance.aiBackend), or run maintenance via the orchestrator.` Relay that verbatim and report `fixed: 0`, `prUrl: null` — do not claim a fix or PR.
+
+### Example: Nothing overdue
+
+Run `harness maintenance run --json`. On the nothing-overdue happy path stdout is still a parseable `ConsolidatedReport` whose `tasks` is an **empty array** (`tasks: []`, `exitCode: 0`) — NOT a plain `All maintenance current.` sentinel (that human string is emitted only on the non-`--json` path). So `JSON.parse(stdout)` succeeds; read `tasks.length === 0`. Tell the human "All maintenance is current — nothing overdue." and stop. Do not invent work or run `--fix`.
+
+## Rationalizations to Reject
+
+| Rationalization                                        | Reality                                                                                                                                                                    |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll just run `--fix` directly to save a round-trip." | Report-first is the whole point. A surprise fix on an on-demand sweep is exactly the hazard this path avoids.                                                              |
+| "I'll ask via `emit_interaction` so it's structured."  | That ask never reaches the human — it collapses to "Called harness". Ask in plain text.                                                                                    |
+| "The report shows findings, so I'll say I fixed them." | `--fix` only fixes when a backend dispatched; relay what the CLI reports (real `fixed` counts, or the no-backend skip notice). `prUrl` is always `null`. Do not overclaim. |
+| "There's no severity field, so I'll assign my own."    | Triage by the status + findings count the report actually provides. Do not fabricate a severity taxonomy.                                                                  |

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

@@ -0,0 +1,43 @@
+name: harness-maintenance-pipeline
+version: '1.0.0'
+description: On-demand, report-first maintenance sweep — runs overdue checks via `harness maintenance run`, triages findings, and asks the human in plain text before dispatching any fix
+stability: draft
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - cursor
+  - codex
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+cli:
+  command: harness skill run harness-maintenance-pipeline
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-maintenance-pipeline
+    path: string
+type: flexible
+tier: 2
+phases:
+  - name: sweep
+    description: Run `harness maintenance run --json` (overdue, report mode) and parse the consolidated report
+    required: true
+  - name: triage
+    description: Present a human-readable summary bucketed by status and findings count
+    required: true
+  - name: fix
+    description: Ask the human in plain text which tasks to fix, then re-invoke `--only <ids> --fix` and relay the result
+    required: false
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -35,6 +35,8 @@
 
 4. **Read `.harness/state.json`** if it exists. This reveals what was happening in the last session — current phase, active task, any blockers that were recorded.
 
+5. **Detect the roadmap layout.** If `docs/roadmap.d/` exists the project uses the **sharded** roadmap: per-row shards `docs/roadmap.d/<slug>.md` (plus `_meta.md`) are canonical and `docs/roadmap.md` is a **generated** `merge=ours` aggregate (do not hand-edit it). New contributors must run the one-time per-clone setup so generated-file merges behave: `git config merge.ours.driver true` (the `.gitattributes merge=ours` entry is inert without it — `harness validate` warns clones that have not run it). Surface this in "Getting Started". If only `docs/roadmap.md` exists, the project is monolith; if neither, it is file-less or uninitialized. See the adoption guide `docs/guides/roadmap-sharding.md`.
+
 ### Phase 2: MAP — Understand the Codebase Structure
 
 Use `code_outline` to get structural overviews of key modules (functions, classes, exports) without reading full source files. Use `code_search` to locate patterns, symbols, or conventions across the codebase.

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

@@ -95,44 +95,21 @@ Store the parsed skill list for use in Phase 2 task annotation.
 
    **Read-only constraint:** Steps 1-6 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
 
-   When scope is ambiguous, use `emit_interaction`:
-
-   ```json
-   emit_interaction({
-     path: "<project-root>",
-     type: "question",
-     question: {
-       text: "The spec mentions X but does not define behavior for Y. Should we:",
-       options: [
-         {
-           label: "A) Include Y in this plan",
-           pros: ["Complete feature in one pass", "No follow-up coordination"],
-           cons: ["Increases scope and time", "May delay delivery"],
-           risk: "medium",
-           effort: "high"
-         },
-         {
-           label: "B) Defer Y to a follow-up plan",
-           pros: ["Keeps current plan focused", "Ship sooner"],
-           cons: ["Y remains unhandled", "May need rework when Y is added"],
-           risk: "low",
-           effort: "low"
-         },
-         {
-           label: "C) Update the spec first",
-           pros: ["Design is complete before planning", "No surprises during execution"],
-           cons: ["Blocks planning until spec is updated", "Extra round-trip"],
-           risk: "low",
-           effort: "medium"
-         }
-       ],
-       recommendation: {
-         optionIndex: 1,
-         reason: "Keeping the current plan focused reduces risk. Y can be addressed in a follow-up.",
-         confidence: "medium"
-       }
-     }
-   })
+   When scope is ambiguous, ask 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).
+
+   Present the choice as a markdown table so tradeoffs are scannable, state your recommendation, then STOP and wait for the human's reply:
+
+   ```markdown
+   ### Decision needed: The spec mentions X but does not define behavior for Y. Should we:
+
+   |            | A) Include Y in this plan                               | B) Defer Y to a follow-up plan                       | C) Update the spec first                                          |
+   | ---------- | ------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+   | **Pros**   | Complete feature in one pass; no follow-up coordination | Keeps current plan focused; ship sooner              | Design is complete before planning; no surprises during execution |
+   | **Cons**   | Increases scope and time; may delay delivery            | Y remains unhandled; may need rework when Y is added | Blocks planning until spec is updated; extra round-trip           |
+   | **Risk**   | Medium                                                  | Low                                                  | Low                                                               |
+   | **Effort** | High                                                    | Low                                                  | Medium                                                            |
+
+   **Recommendation:** B) Defer Y to a follow-up plan (confidence: medium) — keeping the current plan focused reduces risk; Y can be addressed in a follow-up.
    ```
 
 #### EARS Requirement Patterns
@@ -223,7 +200,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
    **Estimated total:** 8 tasks, ~33 minutes
    ```
 
-   **Approval gate:** Present via `emit_interaction` (type: `confirmation`, text: "Approve skeleton direction?"). If approved, proceed to step 3. If rejected, revise and re-present.
+   **Approval gate:** Ask in plain text in your reply — do NOT route this through `emit_interaction` or `AskUserQuestion` (they do not display to the human; `emit_interaction` collapses to "Called harness" and `AskUserQuestion` is Claude-Code-only). Ask directly: "Approve skeleton direction?" and wait. If approved, proceed to step 3. If rejected, revise and re-present.
 
 3. **Decompose into atomic tasks.** Each task must:
    - Be completable in 2-5 minutes, fit in a single context window
@@ -313,7 +290,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 
 10. **Write session summary (if session is known).** Call `writeSessionSummary` with skill, status, plan path, keyContext, nextStep. Skip if no session slug.
 
-11. **Request plan sign-off:** Use `emit_interaction` (type: `confirmation`) with plan path, task count, and time estimate.
+11. **Request plan sign-off in plain text.** Ask directly in your reply — do NOT route this through `emit_interaction` or `AskUserQuestion` (the human will not see it; `emit_interaction` collapses to "Called harness" and `AskUserQuestion` is Claude-Code-only). Present the plan path, task count, and time estimate, then ask: "Proceed? (yes/no)" and wait for the reply.
 
 12. **Suggest transition to execution.** After approval, call `emit_interaction` with type: `transition`, `completedPhase: "planning"`, `suggestedNext: "execution"`, `requiresConfirmation: true`. Include `qualityGate` with checks: plan-written, harness-validate, observable-truths-traced, human-approved. If confirmed: invoke harness-execution. If declined: stop (handoff already written).
 

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

@@ -35,7 +35,7 @@ Read `references/interview.md` for the SMART pushback rules and the READ-WRITE-D
    - If `name` is non-null, confirm it as the product name; otherwise prompt.
    - For each `keyMetric`, walk it through the SMART bar in step 4.
 
-2. **Pick the lookback default.** Use `emit_interaction` (type: `question`) when in MCP mode; otherwise present numbered options in chat: `["24h", "7d", "30d", "custom"]`. Default `24h` per spec.
+2. **Pick the lookback default.** Ask in plain text — present numbered options `["24h", "7d", "30d", "custom"]` and wait (do NOT use `emit_interaction`/`AskUserQuestion`; the human won't see it — it renders only to the model and the client collapses the call to "Called harness"). Default `24h` per spec.
 
 3. **Identify the primary engagement event** (e.g. `session_started`). Apply the SMART bar. If the user can't name one, set `null` and add a pending entry. Record the event name in `primaryEvent`.
 

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

@@ -25,6 +25,23 @@ If the human has not seen and approved the milestone groupings and feature list,
 
 ---
 
+### Storage mode: monolith vs sharded
+
+The roadmap has two physical layouts, auto-detected (not configured) by the presence of `docs/roadmap.d/`:
+
+- **Monolith** — a single `docs/roadmap.md` aggregate is canonical (legacy default).
+- **Sharded** — per-row shards `docs/roadmap.d/<slug>.md` (plus `_meta.md`) are canonical, and `docs/roadmap.md` is a generated `merge=ours` aggregate. New `harness init` projects are sharded by default.
+
+In sharded mode a write patches a **single shard** (conflict-free by construction) and **regenerates the aggregate** — so when committing a roadmap change, stage both `docs/roadmap.d/` and the regenerated `docs/roadmap.md`. Read/write only through `manage_roadmap` / the `RoadmapStore`; never parse the aggregate for content (read-source invariant R, ADR 0050). Subcommands:
+
+- `harness roadmap shard` — adopt sharding (split the monolith into shards), reversible with `harness roadmap unshard` (semantic round-trip).
+- `harness roadmap regen` — regenerate the aggregate from the shards (the fix when `harness validate` warns the aggregate has drifted).
+- `harness roadmap reconcile` — offline merge-triggered auto-done (flip closed-issue rows to `done`).
+
+**Stop hand-marking rows `done`** — rows reach `done` automatically when the implementing PR merges (auto-done reconciler; see knowledge [`merge-triggered-auto-done.md`](../../../../docs/knowledge/roadmap/merge-triggered-auto-done.md)). See also the adoption guide [`docs/guides/roadmap-sharding.md`](../../../../docs/guides/roadmap-sharding.md).
+
+---
+
 ### Command: `--create` -- Bootstrap Roadmap
 
 #### Phase 1: SCAN -- Discover Artifacts

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

@@ -1,6 +1,6 @@
 # Harness Roadmap Pilot
 
-> AI-assisted selection of the next highest-impact unblocked roadmap item. Scores candidates, recommends one, assigns it, and transitions to the appropriate next skill.
+> AI-assisted selection of the next highest-impact unblocked roadmap item. Scores candidates, recommends one, and transitions to the appropriate next skill. Selection does NOT assign — the `assignee` field names who is _executing_, and is written at execution start (harness-execution), not at selection.
 
 ## When to Use
 
@@ -14,9 +14,9 @@
 
 ### Iron Law
 
-**Never assign or transition without the human confirming the recommendation first.**
+**Never transition without the human confirming the recommendation first. Selection never writes `assignee`.**
 
-Present the ranked candidates, the AI reasoning, and the recommended pick. Wait for explicit confirmation before making any changes.
+Present the ranked candidates, the AI reasoning, and the recommended pick. Wait for explicit confirmation before transitioning. The `assignee` field means _who is executing_ and is claimed at execution start by harness-execution — picking an item must NOT mark it assigned (an early assignee makes the item look human-claimed and the orchestrator silently skips it).
 
 ---
 
@@ -133,28 +133,27 @@ Ask the human in plain text (matching the `y/n/pick another` example above). Do
    - If **pick another**: ask which candidate number, then proceed with that pick.
    - If **no**: stop. No changes made.
 
-### Phase 4: ASSIGN -- Execute Assignment and Transition
+### Phase 4: TRANSITION -- Hand Off to the Next Skill
 
-1. Call `manage_roadmap` with action `update` to assign the feature:
+**Do NOT write the `assignee` field here.** Selection picks the item; it does not
+claim it. harness-execution claims the item (`status=in-progress` + `assignee`) at
+execution start. Writing an assignee at selection makes the orchestrator treat the
+item as already-claimed and silently skip it (the bug this skill must not reintroduce).
+The item stays `planned`/`backlog` with `Assignee: —` and remains orchestrator-eligible.
 
-   ```json
-   manage_roadmap({
-     path: "<project-root>",
-     action: "update",
-     feature: "<feature-name>",
-     assignee: "<currentUser>"
-   })
-   ```
-
-   - This updates the feature's `Assignee` field with assignment history tracking
-   - Automatically triggers external sync (GitHub Issues) if tracker config exists in `harness.config.json`
-   - External sync is fire-and-forget — errors are logged but do not block the assignment
+**Sharded mode + auto-done.** When the claim is later written (at execution start),
+in sharded mode (`docs/roadmap.d/` present) it patches the **single row's shard**
+and appends an assignment record to the shared `_meta.md`, then regenerates the
+`docs/roadmap.md` aggregate — stage both. And there is **no manual done-marking
+step**: a row reaches `done` automatically when the implementing PR merges
+(merge-triggered auto-done via `External-ID`; the reconciler clears the assignee per
+RMH005). See knowledge [`merge-triggered-auto-done.md`](../../../../docs/knowledge/roadmap/merge-triggered-auto-done.md).
 
-2. Determine the transition target:
+1. Determine the transition target:
    - If the feature has a `spec` field (non-null): transition to `harness:autopilot`
    - If the feature has no `spec`: transition to `harness:brainstorming`
 
-3. Present the transition to the human via `emit_interaction`:
+2. Present the transition to the human via `emit_interaction`:
 
    ```json
    emit_interaction({
@@ -163,16 +162,16 @@ Ask the human in plain text (matching the `y/n/pick another` example above). Do
      transition: {
        completedPhase: "roadmap-pilot",
        suggestedNext: "<brainstorming|autopilot>",
-       reason: "Feature '<name>' assigned and ready for <brainstorming|execution>",
+       reason: "Feature '<name>' selected and ready for <brainstorming|execution>",
        artifacts: ["docs/roadmap.md"],
        requiresConfirmation: true,
-       summary: "Assigned '<name>' to <user>. <Spec exists -- ready for autopilot|No spec -- needs brainstorming first>.",
+       summary: "Selected '<name>'. <Spec exists -- ready for autopilot|No spec -- needs brainstorming first>. (Not assigned — harness-execution claims it at execution start.)",
        qualityGate: {
          checks: [
            { "name": "roadmap-parsed", "passed": true },
            { "name": "candidate-scored", "passed": true },
            { "name": "human-confirmed", "passed": true },
-           { "name": "assignment-written", "passed": true }
+           { "name": "no-assignment-at-selection", "passed": true }
          ],
          allPassed: true
        }
@@ -180,7 +179,7 @@ Ask the human in plain text (matching the `y/n/pick another` example above). Do
    })
    ```
 
-4. Run `harness validate`.
+3. Run `harness validate`.
 
 ---
 
@@ -190,19 +189,18 @@ Ask the human in plain text (matching the `y/n/pick another` example above). Do
 - **`loadProjectRoadmapMode` / `loadTrackerClientConfigFromProject` / `createTrackerClient`** -- Resolve `roadmap.mode` and obtain a `RoadmapTrackerClient` for file-less mode. Import from `@harness-engineering/core`.
 - **`scoreRoadmapCandidatesForMode`** -- Mode-aware scoring entry point. Import from `@harness-engineering/core`. In file-backed mode delegates to `scoreRoadmapCandidates`; in file-less mode routes through `scoreRoadmapCandidatesFileLess` (priority + createdAt sort, FR-S3).
 - **`scoreRoadmapCandidates`** -- Underlying file-backed scoring algorithm. Prefer `scoreRoadmapCandidatesForMode` from the skill; direct callers in file-backed-only code paths can still use this.
-- **`manage_roadmap update`** -- Used for assignment. Supports `assignee` field which delegates to `assignFeature` internally, handles history tracking, and automatically triggers external sync (GitHub Issues). In file-less mode, `manage_roadmap` dispatches through the tracker; the skill flow is unchanged.
-- **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
+- **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists). This skill does NOT call `manage_roadmap update` to assign — the `assignee` field is owned by harness-execution (claim at execution start), enforced by RMH005 (`assignee ≠ null ⟺ in-progress`).
 - **`STRATEGY.md` alignment (Phase 2 step 1a)** -- When present at repo root and valid, loaded via `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` from `@harness-engineering/core`. Applied as a bounded tiebreaker bonus (max `+0.75`) only when candidates score within `0.05` on the base formula. Boundary: roadmap-pilot READS; `harness-strategy` WRITES. Never modify `STRATEGY.md` from this skill.
-- **`harness validate`** -- Run after assignment is written.
+- **`harness validate`** -- Run after the transition is presented.
 
 ## Success Criteria
 
 1. Roadmap is parsed and unblocked planned/backlog items are scored
 2. Scoring uses two-tier sort: explicit priority first, then weighted score
 3. AI reads top candidates' specs and provides recommendation with reasoning
-4. Human confirms before any changes are made
-5. Assignment updates feature field, appends history records, and syncs externally
-6. Reassignment produces two history records (unassigned + assigned)
+4. Human confirms before the transition is made
+5. Selection does NOT write the `assignee` field (no assignment, no history record, no external assignee sync) — the pick stays `planned`/`backlog` and orchestrator-eligible
+6. The `assignee` field is owned by harness-execution, which claims at execution start; RMH005 enforces `assignee ≠ null ⟺ in-progress`
 7. Transition routes to brainstorming (no spec) or autopilot (spec exists)
 8. When a pulse report exists, the recommendation rationale cites pulse signal for any top-3 candidate whose area is referenced in the pulse Headlines or Followups.
 9. When `STRATEGY.md` is present and valid AND two candidates score within `0.05` on the base formula, the recommendation rationale cites strategy-alignment as the tiebreaker. The bonus never overrides a meaningful base-score difference.
@@ -211,12 +209,13 @@ Ask the human in plain text (matching the `y/n/pick another` example above). Do
 
 ## Rationalizations to Reject
 
-| Rationalization                                                                                                         | Reality                                                                                                                                                                          |
-| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The top-scored candidate is obviously correct, so I can assign it without asking the human"                            | The Iron Law: never assign or transition without the human confirming the recommendation first.                                                                                  |
-| "Affinity data is not available so the scoring is degraded -- I should just pick the first planned item"                | Proceed without affinity scoring by zeroing out the affinity weight. Position and dependents signals still produce meaningful rankings.                                          |
-| "The feature has no spec, but I can skip brainstorming and jump straight to planning since the summary is clear enough" | No spec routes to brainstorming, spec exists routes to autopilot. A one-line roadmap summary is not a spec.                                                                      |
-| "STRATEGY.md exists, so I should let it override the top-scored candidate when alignment is clear"                      | The alignment bonus is bounded (max `+0.75`) and only fires when base scores are within `0.05`. It is a tiebreaker, not a hard filter — a clearly higher-scored item still wins. |
+| Rationalization                                                                                                         | Reality                                                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The top-scored candidate is obviously correct, so I can transition without asking the human"                           | The Iron Law: never transition without the human confirming the recommendation first.                                                                                                                                                    |
+| "I'll write the assignee now so the pick is recorded / the user is credited"                                            | Selection never writes `assignee`. An assignee means _in-progress_ (set by harness-execution at execution start). Writing it at selection makes the orchestrator silently skip the item — the exact bug this skill must not reintroduce. |
+| "Affinity data is not available so the scoring is degraded -- I should just pick the first planned item"                | Proceed without affinity scoring by zeroing out the affinity weight. Position and dependents signals still produce meaningful rankings.                                                                                                  |
+| "The feature has no spec, but I can skip brainstorming and jump straight to planning since the summary is clear enough" | No spec routes to brainstorming, spec exists routes to autopilot. A one-line roadmap summary is not a spec.                                                                                                                              |
+| "STRATEGY.md exists, so I should let it override the top-scored candidate when alignment is clear"                      | The alignment bonus is bounded (max `+0.75`) and only fires when base scores are within `0.05`. It is a tiebreaker, not a hard filter — a clearly higher-scored item still wins.                                                         |
 
 ## Examples
 
@@ -252,25 +251,23 @@ Proceed? (y/n/pick another)
 
 Human confirms **y**.
 
-**Phase 4: ASSIGN**
+**Phase 4: TRANSITION**
 
 ```
-manage_roadmap update: Graph Connector assignee -> @cwarner
-History: +1 record (assigned, 2026-04-02)
-Roadmap updated: docs/roadmap.md
-External sync: github:harness-eng/harness#43 assigned (automatic)
+Graph Connector stays planned, Assignee: — (not assigned at selection).
+harness-execution will claim it (status=in-progress + assignee) at execution start.
 
 Transitioning to harness:autopilot (spec exists)...
 ```
 
 ## Gates
 
-- **No assignment without human confirmation.** The CONFIRM phase must complete with explicit approval. Never auto-assign.
-- **No transition without assignment.** The skill must write the assignment before transitioning to the next skill.
+- **No transition without human confirmation.** The CONFIRM phase must complete with explicit approval before transitioning.
+- **No assignment at selection.** This skill never writes the `assignee` field — that field means _who is executing_ and is claimed at execution start by harness-execution. Writing it here would make the orchestrator silently skip the item.
 - **No scoring without a parsed roadmap.** If `docs/roadmap.md` does not exist or fails to parse, stop with an error.
 
 ## Escalation
 
 - **When no unblocked candidates exist:** Inform the human. Suggest reviewing blocked items to see if blockers can be resolved, or adding new features via `harness-roadmap --add`.
 - **When affinity data is unavailable:** Proceed without affinity scoring (weight falls to 0 for all candidates). Note this in the output.
-- **When external sync fails:** Log the error, complete the local assignment, and note that external sync can be retried with `harness-roadmap --sync`.
+- **When the human asks you to assign the item to them at selection:** Explain that the `assignee` field means _who is executing_ and is claimed at execution start by harness-execution; assigning at selection makes the orchestrator silently skip the item (enforced by RMH005). Proceed with the transition instead.

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

@@ -174,19 +174,16 @@ Use severity markers for critical findings: `**[CRITICAL]**` for blocking issues
 
 ### Verification Sign-Off
 
-After producing the report, request acceptance:
+After producing the report, request acceptance in plain text. Ask 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). Present it as:
 
-```json
-emit_interaction({
-  path: "<project-root>",
-  type: "confirmation",
-  confirmation: {
-    text: "Verification report: <VERDICT>. Accept and proceed?",
-    context: "<N artifacts checked, N gaps found>",
-    impact: "Accepting proceeds to code review. Declining requires gap resolution.",
-    risk: "<low if PASS, high if gaps remain>"
-  }
-})
+```markdown
+Verification report: <VERDICT>. Accept and proceed?
+
+Context: <N artifacts checked, N gaps found>
+Impact: Accepting proceeds to code review. Declining requires gap resolution.
+Risk: <low if PASS, high if gaps remain>
+
+Proceed? (yes/no)
 ```
 
 ### Handoff and Transition