@harness-engineering/cli 3.0.1 → 4.0.0

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