@harness-engineering/cli 3.1.0 → 4.0.0

package/dist/agents/skills/gemini-cli/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/gemini-cli/harness-brainstorming/skill.yaml

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

package/dist/agents/skills/gemini-cli/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/gemini-cli/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/gemini-cli/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

package/dist/agents/skills/gemini-cli/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/gemini-cli/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/gemini-cli/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.