@harness-engineering/cli 3.1.0 → 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

@@ -141,6 +141,14 @@ execution start. Writing an assignee at selection makes the orchestrator treat t
 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.
 
+**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).
+
 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`

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

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

@@ -1,6 +1,6 @@
 # Initialize Harness Project
 
-> Scaffold a new harness-compliant project, migrate an existing project to the next adoption level, or bootstrap an existing project that just got the harness marketplace plugin installed (no `harness setup`). Assess current state, scaffold or migrate, configure, validate, instrument (baselines / telemetry / Tier-0 integrations), and finalize.
+> Scaffold a new harness-compliant project, migrate an existing project to the next adoption level, or bootstrap an existing project that just got the harness marketplace plugin installed (no `harness setup`). Ground the project in a strategic anchor (`STRATEGY.md`) first, then assess current state, scaffold or migrate, configure, validate, instrument (baselines / telemetry / Tier-0 integrations), and finalize.
 
 ## When to Use
 
@@ -31,6 +31,52 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
 **Prompt the human in plain text** — every framework confirmation, migration check, and telemetry-identity question in this skill is plain text only. Do not elevate to `AskUserQuestion`: the framework list (~10 options) exceeds its 4-option cap and natural headers like "Confirm framework" exceed its 12-char cap, rendering the call as ERR.
 
+### Phase 0: GROUND — Capture the Strategic Anchor
+
+Run this before anything else — it is the first thing init does and the first question it asks the human.
+Offer to capture `STRATEGY.md`, the durable upstream product anchor read by `harness-brainstorming`,
+`harness-ideate`, and `harness-roadmap-pilot`. _Think first (strategy), build second (scaffold)._
+
+Ask in plain text in your reply, same as the design-system step (Phase 3 step 5b) — never via `emit_interaction`, `AskUserQuestion`, or any tool (the human won't see a tool-routed prompt; only plain text reaches them across Claude Code, Cursor, Codex, and Gemini CLI). State your recommendation, then STOP and wait for the human's reply:
+
+```markdown
+### Capture strategic anchor (STRATEGY.md) now?
+
+|            | A) Yes — run the strategy interview                                                                                        | B) No — this project does not need a strategy doc                           | C) Not sure yet                                                       |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **Pros**   | Grounds brainstorm/ideate/roadmap-pilot in product-level context; durable across milestones and phases (peer of README.md) | Permanent decline recorded; init does not re-ask on rerun                   | Decision deferred without commitment; can run /harness:strategy later |
+| **Cons**   | Adds an interview (10-20 minutes) to init                                                                                  | Re-running init will not re-offer; user must run /harness:strategy manually | No decline flag set; init may re-offer on rerun                       |
+| **Risk**   | Low                                                                                                                        | Low                                                                         | Low                                                                   |
+| **Effort** | Medium                                                                                                                     | Low                                                                         | Low                                                                   |
+
+**Recommendation:** A) Yes — run the strategy interview (confidence: medium) — strategy grounds brainstorm/ideate/roadmap-pilot; value compounds as the project grows.
+```
+
+Before prompting, check whether `STRATEGY.md` already exists at repo root. Three cases:
+
+- **Absent (most common on init).** Present the prompt above. Apply the answer:
+  - **Yes:** delegate to `harness-strategy` (which routes via its own Phase 0 to the first-run interview). It writes a valid `STRATEGY.md` at repo root, doc-validated via the `write_strategy` / `validate_strategy` MCP tools. Do **not** run a project-level `harness validate` here — `harness.config.json` does not exist until SCAFFOLD. When `harness-strategy` completes, proceed to Phase 1.
+  - **No:** record the decline in working memory. `Phase 3: CONFIGURE` step 0 persists `init.strategy.declined: true` to `.harness/state.json` after SCAFFOLD creates it. Do **not** touch `.harness/` here — it does not exist yet.
+  - **Not sure:** record nothing. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.
+
+- **Present and valid.** Skip the prompt silently. Surface a one-line note: `STRATEGY.md detected — downstream skills will pick it up as grounding`. No decline is recorded.
+
+- **Present but invalid.** Surface the validation error via the `validate_strategy` MCP tool (the MCP server already has `@harness-engineering/core` loaded, so this resolves even for plugin-only adopters with no `node_modules`). Offer three paths (mirror `harness-strategy` Phase 0):
+  - **a) Fix now via `/harness:strategy` update** → delegate to `harness-strategy` with the broken section pre-selected.
+  - **b) Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run a fresh interview** → rename, then delegate to `harness-strategy` Phase 1.
+  - **c) Ignore for this init and proceed** → record the decline (persisted in `Phase 3: CONFIGURE` step 0) and continue. Init does NOT block on a present-but-invalid `STRATEGY.md`.
+
+**Guards:**
+
+- Phase 0 runs for **all** project shapes, including test suites — strategy is offered before the Phase 1
+  step 5 test-suite classification and the step-6 dispatch, identical in reach to the legacy step.
+- A present-valid (skip) or present-invalid (offer fix) `STRATEGY.md` is the migration path for an existing
+  strategy doc — distinct from the `.harness/`-based adoption-level classification in `Phase 1: ASSESS`,
+  which Phase 0 must not pre-empt.
+- **No / Not-sure proceeds immediately into `Phase 1: ASSESS`. Phase 0 never blocks init.**
+
+This mirrors the ask-once-record-the-answer pattern also used by the i18n and design-system prompts in Phase 3.
+
 ### Phase 1: ASSESS — Determine Current State
 
 1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.
@@ -82,6 +128,14 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
 ### Phase 3: CONFIGURE — Customize for the Project
 
+0. **Persist the Phase 0 grounding decision.** SCAFFOLD has now created `.harness/`. If the user **declined**
+   the strategic anchor in `Phase 0: GROUND` (answered "No", or chose "ignore" on a present-but-invalid
+   `STRATEGY.md`), write `init.strategy.declined: true` to `.harness/state.json` (merge into existing JSON;
+   do not clobber). If the user answered "Yes" or "Not sure" in Phase 0, write nothing. This is the deferred
+   half of the Phase 0 offer: Phase 0 captures the answer, this step records the decline once `.harness/`
+   exists — so the relocation never fabricates `.harness/` early and never misclassifies a new project as a
+   migration in `Phase 1: ASSESS`.
+
 1. **Configure personas.** Run `harness persona generate` to create persona definitions based on the project's stack and team structure. Personas define how agents should behave in this project — coding style, communication preferences, constraint strictness.
 
 2. **Customize AGENTS.md.** The generated template needs project-specific content:
@@ -100,39 +154,21 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
    - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
    - **Not sure:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
 
-5b. **Configure design system (non-test-suite projects).** Ask: "Will this project have a UI requiring a design system?" Mirror the i18n step's three-way response shape. Use `emit_interaction`:
-
-    ```json
-    emit_interaction({
-      type: "question",
-      question: {
-        text: "Will this project have a UI requiring a design system?",
-        options: [
-          {
-            label: "Yes — capture design intent now",
-            pros: ["Records platforms in harness.config.json", "harness-design-system fires automatically on first design-touching feature"],
-            cons: ["One extra follow-up question (which platforms)"],
-            risk: "low",
-            effort: "low"
-          },
-          {
-            label: "No — this project has no UI",
-            pros: ["No future design nudges", "Permanent decline recorded"],
-            cons: ["Re-running init is required if a UI is added later"],
-            risk: "low",
-            effort: "low"
-          },
-          {
-            label: "Not sure yet",
-            pros: ["Decision deferred without commitment", "Can run harness-design-system later"],
-            cons: ["No design.enabled flag set; on_new_feature will prompt later"],
-            risk: "low",
-            effort: "low"
-          }
-        ],
-        recommendation: { optionIndex: 0, reason: "Most product/service projects benefit from a centralized design system", confidence: "medium" }
-      }
-    })
+5b. **Configure design system (non-test-suite projects).** Mirror the i18n step's three-way response shape.
+
+    **Ask directly in your reply. Do NOT route this 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. `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). State your recommendation, then STOP and wait for the human's reply:
+
+    ```markdown
+    ### Will this project have a UI requiring a design system?
+
+    | | A) Yes — capture design intent now | B) No — this project has no UI | C) Not sure yet |
+    |---|---|---|---|
+    | **Pros** | Records platforms in harness.config.json; harness-design-system fires automatically on first design-touching feature | No future design nudges; permanent decline recorded | Decision deferred without commitment; can run harness-design-system later |
+    | **Cons** | One extra follow-up question (which platforms) | Re-running init is required if a UI is added later | No design.enabled flag set; on_new_feature will prompt later |
+    | **Risk** | Low | Low | Low |
+    | **Effort** | Low | Low | Low |
+
+    **Recommendation:** A) Yes — capture design intent now (confidence: medium) — most product/service projects benefit from a centralized design system.
     ```
 
     Based on the answer:
@@ -142,60 +178,6 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
     **Skip this step entirely if Phase 1 step 5 classified the project as a test suite.** Test-suite projects will be dispatched at step 6 below to `initialize-test-suite-project` and have no UI to govern.
 
-5c. **Capture strategic anchor (all levels).** Offer a three-way prompt for `STRATEGY.md` — the durable upstream product anchor read by `harness-brainstorming`, `harness-ideate`, and `harness-roadmap-pilot`. Use `emit_interaction`:
-
-    ```json
-    emit_interaction({
-      type: "question",
-      question: {
-        text: "Capture strategic anchor (STRATEGY.md) now?",
-        options: [
-          {
-            label: "Yes — run the strategy interview",
-            pros: [
-              "Grounds brainstorm/ideate/roadmap-pilot in product-level context",
-              "Durable across milestones and phases (peer of README.md)"
-            ],
-            cons: ["Adds an interview (10-20 minutes) to init"],
-            risk: "low",
-            effort: "medium"
-          },
-          {
-            label: "No — this project does not need a strategy doc",
-            pros: ["Permanent decline recorded; init does not re-ask on rerun"],
-            cons: ["Re-running init will not re-offer; user must run /harness:strategy manually"],
-            risk: "low",
-            effort: "low"
-          },
-          {
-            label: "Not sure yet",
-            pros: ["Decision deferred without commitment", "Can run /harness:strategy later"],
-            cons: ["No decline flag set; init may re-offer on rerun"],
-            risk: "low",
-            effort: "low"
-          }
-        ],
-        recommendation: { optionIndex: 0, reason: "Strategy grounds brainstorm/ideate/roadmap-pilot — value compounds as the project grows", confidence: "medium" }
-      }
-    })
-    ```
-
-    Before prompting, check whether `STRATEGY.md` already exists at repo root. Three cases:
-
-    - **Absent (most common on init).** Present the prompt above. Apply the answer:
-      - **Yes:** delegate to `harness-strategy` (which routes via its own Phase 0 to the first-run interview). When `harness-strategy` completes, continue with step 6.
-      - **No:** write `init.strategy.declined: true` to `.harness/state.json` (merge into existing JSON; do not clobber). This is the explicit decline location; re-running init detects the flag and skips the prompt.
-      - **Not sure:** no state write. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.
-
-    - **Present and valid.** Skip the prompt silently. Surface a one-line note: `STRATEGY.md detected — downstream skills will pick it up as grounding`. No `init.strategy.declined` write.
-
-    - **Present but invalid.** Surface the validation error verbatim (run a Node one-liner that imports `validateStrategy` from `@harness-engineering/core` and pipes the error). Offer three paths (mirror `harness-strategy` Phase 0):
-      - **a) Fix now via `/harness:strategy` update** → delegate to `harness-strategy` with the broken section pre-selected.
-      - **b) Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run a fresh interview** → rename, then delegate to `harness-strategy` Phase 1.
-      - **c) Ignore for this init and proceed** → record `init.strategy.declined: true` and continue. Init does NOT block on present-but-invalid STRATEGY.md.
-
-    Mirror the i18n / design-system pattern: ask once, record the answer, never silently skip.
-
 6. **Test-suite projects only — dispatch to `initialize-test-suite-project`.** If Phase 1 step 5 classified this as a test suite, invoke `initialize-test-suite-project` now and let it own archetype selection, shared-library decision, layer variants (A self-contained vs B consumer), ESLint flat-config fix, tag taxonomy, reporter stack, custom report, and the "prove the guards fire" verification. Return here for Phase 4 step 4+ (knowledge graph, roadmap, commit). Product and service projects skip this step entirely.
 
 ### Phase 4: VALIDATE — Confirm Everything Works
@@ -275,32 +257,21 @@ This phase closes the parity gap that the marketplace plugin install does not co
 
 ### Phase 6: FINALIZE — Roadmap and Commit
 
-1. **Set up project roadmap.** Ask: "Set up a project roadmap now? `docs/roadmap.md` tracks features, milestones, and status across your specs and plans." Use `emit_interaction`:
-
-   ```json
-   emit_interaction({
-     type: "question",
-     question: {
-       text: "Set up a project roadmap now?",
-       options: [
-         {
-           label: "Yes — create docs/roadmap.md now",
-           pros: ["Roadmap visible from day one", "Future specs auto-discovered on next sync"],
-           cons: ["Adds one file to the initial commit"],
-           risk: "low",
-           effort: "low"
-         },
-         {
-           label: "No — skip for now",
-           pros: ["Smaller initial footprint"],
-           cons: ["Run `/harness:roadmap --create` later when ready"],
-           risk: "low",
-           effort: "low"
-         }
-       ],
-       recommendation: { optionIndex: 0, reason: "Validation has just passed — a tangible 'project works' signal is the right moment to introduce planning artifacts", confidence: "medium" }
-     }
-   })
+1. **Set up project roadmap.** `docs/roadmap.md` tracks features, milestones, and status across your specs and plans.
+
+   **Ask in plain text in your reply, same as Phase 0: GROUND and Phase 3 step 5b — never via `emit_interaction`, `AskUserQuestion`, or any tool (the human won't see a tool-routed prompt; only plain text reaches them across Claude Code, Cursor, Codex, and Gemini CLI).** State your recommendation, then STOP and wait for the human's reply:
+
+   ```markdown
+   ### Set up a project roadmap now?
+
+   |            | A) Yes — create docs/roadmap.md now                                     | B) No — skip for now                             |
+   | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
+   | **Pros**   | Roadmap visible from day one; future specs auto-discovered on next sync | Smaller initial footprint                        |
+   | **Cons**   | Adds one file to the initial commit                                     | Run `/harness:roadmap --create` later when ready |
+   | **Risk**   | Low                                                                     | Low                                              |
+   | **Effort** | Low                                                                     | Low                                              |
+
+   **Recommendation:** A) Yes — create docs/roadmap.md now (confidence: medium) — validation has just passed; a tangible "project works" signal is the right moment to introduce planning artifacts.
    ```
 
    Based on the answer:
@@ -325,8 +296,8 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - **`harness integrations list` / `harness integrations add <name>`** — Phase 5 step 6. Lists Tier-0 (zero-config) and Tier-1 (API-key) MCP integrations and adds them to project `.mcp.json`.
 - **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
 - **`harness-design-system` (deferred via `on_new_feature`)** — Phase 3 step 5b records `design.enabled` + `design.platforms` in `harness.config.json` but does NOT run the full design-system skill. Token generation defers to the first design-touching feature, where `harness-design-system` fires via `on_new_feature` and reads `design.enabled` to decide whether to proceed.
-- **`harness-strategy`** — Phase 3 step 5c delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" init writes `init.strategy.declined: true` to `.harness/state.json`. On "not sure" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
-- **`validateStrategy`** — `@harness-engineering/core` helper used by Phase 3 step 5c to detect present-but-invalid `STRATEGY.md`. Invoked through a Node one-liner so init does not require importing core directly.
+- **`harness-strategy`** — Phase 0: GROUND delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" the decline is recorded in working memory and persisted as `init.strategy.declined: true` to `.harness/state.json` by Phase 3: CONFIGURE step 0 (after SCAFFOLD). On "not sure" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
+- **`validate_strategy` / `write_strategy` MCP tools** — used by Phase 0: GROUND to doc-validate `STRATEGY.md` and to detect a present-but-invalid one. Routed through the MCP server (which already has `@harness-engineering/core` loaded) so init does not require local `node_modules` or a `node -e` one-liner.
 - **`initialize-test-suite-project`** — Sub-skill. Invoked during Phase 3 step 6 when Phase 1 step 5 classified the project as a test suite. Owns archetype selection, shared-library vs in-repo decision, layer variants, tag taxonomy, reporter stack, custom report, and "prove the guards fire" verification.
 - **`harness-roadmap` skill** — Phase 6 step 1 invokes this skill (or `/harness:roadmap --create`) when the user opts in to creating `docs/roadmap.md`. The `manage_roadmap` MCP tool does not create roadmaps; it manages entries in an existing one.
 - **`manage_roadmap` MCP tool** — Phase 6 step 1, when `design.enabled === true`, calls `manage_roadmap` with `action: add` to insert a `planned` "Set up design system" item under milestone `Intake` with a summary describing the deferred work.
@@ -343,7 +314,7 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - All generated files are committed in a single atomic commit
 - i18n configuration is set if the human chose to enable it during init
 - For non-test-suite projects, the design-system question was asked and `harness.config.json` reflects the answer: `design.enabled: true` (with `design.platforms` populated) for yes, `design.enabled: false` for no, or absent for not sure.
-- The strategy question (Phase 3 step 5c) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists and `harness validate` passes against `StrategyDocSchema`; No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure → no `STRATEGY.md` and no `init.strategy.declined` flag.
+- The strategy question (Phase 0: GROUND) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists, doc-validated via `validate_strategy` against `StrategyDocSchema` (no project-level `harness validate` is run in Phase 0); No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure → no `STRATEGY.md` and no `init.strategy.declined` flag.
 - **Phase 5 (INSTRUMENT) outputs:** `.harness/graph/` is populated; `.harness/arch/baselines.json` exists; `harness check-perf` ran without errors (intermediate and above); `.harness/telemetry.json` exists if the human opted into identity tagging; legacy layout warnings were surfaced via `harness migrate --dry-run` and either resolved or explicitly deferred; Tier-0 MCP integrations (context7, sequential-thinking, playwright) are present in the project's `.mcp.json` (or the human declined and that decision is recorded).
 - The roadmap question was asked. If the user answered yes, `docs/roadmap.md` exists and was created via `harness-roadmap` (or the documented `/harness:roadmap --create` fallback).
 - When `design.enabled === true` AND the user answered yes to the roadmap question, `docs/roadmap.md` contains a `planned` entry titled "Set up design system" under milestone `Intake` with a summary describing the deferred work. The entry is absent in all other answer combinations.
@@ -358,9 +329,9 @@ This phase closes the parity gap that the marketplace plugin install does not co
 | "We should start at the advanced level since we want full coverage"          | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                                                                                                  |
 | "I will skip the i18n question to keep setup fast"                           | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                                                                                                             |
 | "I will skip the design-system question to keep setup fast"                  | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`.                                                                                   |
-| "I will skip the strategy question — it's just paperwork"                    | Phase 3 step 5c is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "no" or "not sure" answer is better than no answer because it locks in the decision (or absence of one). |
-| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 3 step 5c skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                            |
-| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 3 step 5c explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                       |
+| "I will skip the strategy question — it's just paperwork"                    | Phase 0: GROUND is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "no" or "not sure" answer is better than no answer because it locks in the decision (or absence of one). |
+| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 0: GROUND skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                            |
+| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 0: GROUND explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                       |
 | "Validation passed, so the project is ready"                                 | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                                                                                                           |
 | "Plugin install means setup is done"                                         | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                                                                                                        |
 | "Skip Phase 5 if we already ran `harness setup`"                             | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                                                                                                        |
@@ -410,6 +381,16 @@ git commit -m "feat: initialize harness project at basic level"
 
 ### Example: New TypeScript Web App with Design and Roadmap
 
+**GROUND (Phase 0 — asked first, before ASSESS/SCAFFOLD):**
+
+```
+Phase 0 (strategy): "Capture strategic anchor (STRATEGY.md) now?"
+  Human: "Yes."
+  Delegate to harness-strategy → first-run interview → STRATEGY.md written.
+  Result: STRATEGY.md exists at repo root, doc-validated via validate_strategy (StrategyDocSchema);
+  no project-level harness validate runs in Phase 0.
+```
+
 **ASSESS:**
 
 ```
@@ -427,6 +408,8 @@ harness init --level basic --framework nextjs
 **CONFIGURE (Phase 3):**
 
 ```
+Step 0 (persist grounding): user answered "Yes" in Phase 0 → STRATEGY.md already written; nothing to persist.
+
 Step 5 (i18n): "Will this project support multiple languages?"
   Human: "No, English only."
   Result: i18n.enabled = false in harness.config.json.
@@ -439,11 +422,6 @@ Step 5b (design): "Will this project have a UI requiring a design system?"
   Inform: "Design tokens will be generated when you start your first design-touching
   feature — harness-design-system fires automatically via on_new_feature."
 
-Step 5c (strategy): "Capture strategic anchor (STRATEGY.md) now?"
-  Human: "Yes."
-  Delegate to harness-strategy → first-run interview → STRATEGY.md written.
-  Result: STRATEGY.md exists at repo root; harness validate passes against StrategyDocSchema.
-
 Step 6 (test-suite dispatch): skipped (not a test suite).
 ```
 
@@ -524,6 +502,14 @@ git commit -m "feat: migrate harness project to intermediate level with layers"
 
 The user installed `harness-claude` from the marketplace. They have an existing TypeScript repo with no `.harness/` directory. Goal: get them to a working harness install without asking them to `npm install -g`.
 
+**GROUND (Phase 0 — asked first, before ASSESS/SCAFFOLD):**
+
+```
+Phase 0 (strategy): "Capture strategic anchor (STRATEGY.md) now?"
+  Human: "Not sure."
+  Result: no STRATEGY.md written, no init.strategy.declined flag; /harness:strategy stays available later.
+```
+
 **ASSESS:**
 
 ```
@@ -546,10 +532,10 @@ npx @harness-engineering/cli init  # auto-detects framework
 **CONFIGURE:**
 
 ```
+Phase 3 step 0 (persist grounding): user was "Not sure" in Phase 0 → nothing to persist.
 Customize AGENTS.md with project-specific content.
 Phase 3 step 5 (i18n): "No, English only." → i18n.enabled = false.
 Phase 3 step 5b (design): "No, this is a backend service." → design.enabled = false.
-Phase 3 step 5c (strategy): "not sure." → no STRATEGY.md, no init.strategy.declined flag; user can run /harness:strategy later.
 Phase 3 step 6 (test-suite dispatch): not a test suite, skipped.
 ```
 

package/dist/agents/skills/gemini-cli/outcome-eval/SKILL.md

@@ -44,6 +44,7 @@ The evaluator resolves the section internally via the fallback chain `## Success
 - **Provider path (v1 supported):** the anthropic analysis provider (`ANTHROPIC_API_KEY`). When no provider is configured the call degrades to INCONCLUSIVE/advisory. The openai-compatible _strict_ structured-output path is a known follow-up (see Known Limitations).
 - **Orchestrator:** runs as step 6.5 between Code Review and Ship in `harness.orchestrator.md`.
 - **Persistence:** each `evaluate()` writes one `execution_outcome` node via `ExecutionOutcomeConnector`, consumable by `effectiveness/scorer.ts`.
+- **Relationship to `acceptance-eval`:** `acceptance-eval` is the upstream twin — it gates spec measurability before execution; `outcome-eval` judges implementation satisfaction after. The "authority is never read from the LLM" discipline spans both.
 
 ## Known Limitations
 

package/dist/agents/skills/tests/interaction-channel.test.ts

@@ -0,0 +1,64 @@
+// agents/skills/tests/interaction-channel.test.ts
+//
+// Guards the UX-channel invariant for skill prompts.
+//
+// `emit_interaction` with `type: 'question'` or `type: 'confirmation'` renders and
+// records a 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. A skill
+// that routes a user-facing ask through it leaves the human staring at "Called
+// harness" while the agent narrates a question they cannot answer.
+//
+// User-facing asks must be made in PLAIN TEXT in the agent's own reply — the only
+// channel that reliably reaches the human across every platform (Claude Code,
+// Cursor, Codex, Gemini CLI). `AskUserQuestion` is Claude-Code-only and caps headers
+// at 12 chars / 4 options, so it is not a portable substitute either.
+//
+// `type: 'transition'` is exempt: it does real work (saveHandoff + telemetry) and is
+// not a question posed to the human.
+
+import { describe, it, expect } from 'vitest';
+import { glob } from 'glob';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = resolve(__dirname, '..');
+
+// Matches `type: "question"`, `type: 'confirmation'`, and inline `type: \`question\``
+// forms — i.e. an emit_interaction ask aimed at the human. Does NOT match the prose
+// rationale that names the tool ("do NOT route this through `emit_interaction`"),
+// which never writes `type: question`.
+const FORBIDDEN_ASK = /type:\s*["'`](question|confirmation)["'`]/;
+
+describe('skill prompts use a human-visible channel', () => {
+  const skillMdFiles = glob.sync('**/SKILL.md', {
+    cwd: SKILLS_DIR,
+    ignore: ['**/node_modules/**', '**/tests/**'],
+  });
+
+  if (skillMdFiles.length === 0) {
+    it.skip('no SKILL.md files found yet', () => {});
+    return;
+  }
+
+  it.each(skillMdFiles)(
+    '%s does not route a user-facing ask through emit_interaction (question/confirmation)',
+    (file) => {
+      const content = readFileSync(resolve(SKILLS_DIR, file), 'utf-8');
+      const offending = content
+        .split('\n')
+        .map((line, i) => ({ line, n: i + 1 }))
+        .filter(({ line }) => FORBIDDEN_ASK.test(line));
+
+      expect(
+        offending,
+        `${file} asks the human via emit_interaction at line(s) ` +
+          `${offending.map((o) => o.n).join(', ')}. ` +
+          `Ask in plain text in the reply instead — emit_interaction does not display ` +
+          `the prompt to the human (it collapses to "Called harness"). ` +
+          `type: 'transition' is exempt and uses a different type literal.`
+      ).toHaveLength(0);
+    }
+  );
+});

package/dist/{agents-md-YYCLGMBF.js → agents-md-7OSNWU52.js}

@@ -1,7 +1,7 @@
 import {
   generateAgentsMd
-} from "./chunk-TCVQVHEF.js";
-import "./chunk-A65QO5KN.js";
+} from "./chunk-IYWT3JJW.js";
+import "./chunk-KLPX55TI.js";
 import "./chunk-N55WOGN3.js";
 import "./chunk-BDGTZRZ6.js";
 import "./chunk-PP6ZRL5T.js";

package/dist/{architecture-5KPP4ID4.js → architecture-2XYGJGT3.js}

@@ -1,11 +1,11 @@
 import {
   checkDependenciesDefinition,
   handleCheckDependencies
-} from "./chunk-OQFEFVIN.js";
-import "./chunk-XZ2Q4UTW.js";
+} from "./chunk-MSBJ445U.js";
 import "./chunk-RC3OI5NK.js";
+import "./chunk-ZEYAOYJL.js";
 import "./chunk-W6Y7ZW3Y.js";
-import "./chunk-A65QO5KN.js";
+import "./chunk-KLPX55TI.js";
 import "./chunk-N55WOGN3.js";
 import "./chunk-BDGTZRZ6.js";
 import "./chunk-PP6ZRL5T.js";