@harness-engineering/cli 3.1.0 → 4.0.1

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/gemini-cli/product-advisor/SKILL.md

@@ -0,0 +1,202 @@
+# Product Advisor
+
+> Turn a client diagram + conversation into a Business Requirements Document and a resolved gap-list, then seed the harness pipeline. The pre-inception front door: gather requirements with AI, feed them in, and let the existing flow continue as it does today.
+
+## When to Use
+
+- At the **inception** of a client engagement, when a solution architect / pre-sales engineer has a rough idea, a diagram, and conversation notes but no structured requirements yet.
+- When you want to turn "a diagram and some notes" into a client-legible BRD plus an explicit list of what is still unknown.
+- When the output should **seed the roadmap** (many work items) and ground the engagement's strategy — not produce a single spec.
+- NOT for authoring a spec/proposal — that is `harness-brainstorming`'s job. Product Advisor stops at BRD + roadmap seeding.
+- NOT for writing or updating `STRATEGY.md` directly — that is `harness-strategy`'s job. This skill only reads strategy and _offers_ to seed it.
+- NOT for internal feature work where the requirements already live in the codebase or an existing spec — go straight to `harness-brainstorming` or `harness-planning`.
+
+## Process
+
+### Iron Law
+
+**Every gap is either resolved in the interview or shipped as an explicit client-facing question — never silently dropped.** A BRD that hides what it does not know is worse than no BRD: it launders assumptions into requirements. If you cannot answer a gap and did not surface it in `gaps.md`, STOP and add it.
+
+---
+
+### Phase 1: INGEST — Gather the Raw Material
+
+1. **Resolve the engagement slug.** From the `engagement` argument, or ask the SA for a short name. This sets `docs/inception/<engagement>/` and the roadmap milestone `Inception: <engagement>`.
+2. **Ingest the diagram.** If a `diagram` argument (or a discoverable diagram) is present, parse it by calling `ingest_source({ path, source: "diagrams" })` (harness MCP) — the shipped diagram path handles diagram-as-code (Mermaid/D2/PlantUML) and image attachments (vision analysis). Then read the extracted entities and flows back via `gather_context` / `query_graph`. **Do not build a new parser** — reuse `ingest_source`.
+3. **Soft-degrade when parsing is unavailable.** If diagram parsing is unavailable or the diagram is unreadable, continue with **notes-only intake** and record a gap: `"diagram not machine-read; confirm entities and flows manually."` Do not fail.
+4. **Ingest the notes.** Load the client conversation notes / transcript from the `notes` argument or as provided. Call `gather_context` to pull any existing project/business knowledge that grounds the domain.
+5. **Normalize into intake.** Produce a structured intake: `{ entities[], flows[], notes }`. State the entities and flows back to the SA in one short summary and confirm before drafting.
+
+---
+
+### Phase 2: DRAFT-BRD — Synthesize the First Draft
+
+1. **Write the BRD** to `docs/inception/<engagement>/brd.md` with these sections, each present even if thin: _Context, Business Objectives, Scope, Functional Requirements, Non-Functional Requirements, Assumptions, Constraints, Out-of-Scope, Open Questions._
+2. **Phrase behavioral requirements with EARS patterns:**
+   - Event-driven: "When [trigger], the system shall [response]."
+   - Unwanted: "If [condition], then the system shall not [behavior]."
+3. **Tag gaps against the fixed BRD completeness rubric** (see below). Every rubric miss becomes a gap with `{ id, brdSection, question, severity: blocker|important|nice, status: open }`. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.
+4. **Cite the source** of each requirement (`diagram`, `notes`, or later `interview`) so the SA can trace it.
+
+#### BRD completeness rubric
+
+- Each BRD section is non-empty and internally consistent.
+- Every diagram entity and flow maps to ≥1 functional requirement (or to an explicit gap).
+- Every functional requirement has an **actor + trigger + response**.
+- Every non-functional requirement is measurable (a number or a testable condition), else it is a gap.
+- Scope and Out-of-Scope do not contradict each other.
+
+---
+
+### Phase 3: GAP-INTERVIEW — Resolve What You Can
+
+1. **Ask ONE question at a time, in plain text.** Order the gap queue by severity (`blocker` → `important` → `nice`). Ask the highest-severity open gap first, wait for the answer, then continue.
+
+   **Ask directly in your reply. Do NOT route questions through `emit_interaction`, `AskUserQuestion`, or any tool** — those do not reliably surface the question to the human. Plain text in your own message is the only channel that reaches the SA across every client (Claude Code, Cursor, Codex, Gemini CLI).
+
+   Present each gap as a scannable multiple-choice table where options exist, and state a recommendation:
+
+   ```markdown
+   ### Gap G3 (blocker): What authenticates end users?
+
+   |             | A) Client SSO (SAML/OIDC) | B) Local accounts | C) Unknown — ask client |
+   | ----------- | ------------------------- | ----------------- | ----------------------- |
+   | **Implies** | IdP integration work      | Password storage  | Blocks scoping          |
+   | **Risk**    | Depends on client IdP     | Security burden   | —                       |
+
+   **Recommendation:** likely A given the enterprise diagram — confirm the IdP.
+   ```
+
+2. **Fold each answer back into the BRD.** Update the relevant section, add the requirement (source: `interview`), and move the gap `open → resolved` with the captured answer.
+3. **Mark unresolvable gaps client-facing.** If the SA cannot answer (only the client can), keep the gap `open` and phrase it as a question to ask the client.
+4. **Stop when the queue is drained** — every gap is either `resolved` or `open` (client-facing). Do not loop past a drained queue inventing new questions.
+
+---
+
+### Phase 4: FINALIZE — Ship and Hand Off
+
+1. **Write `gaps.md`** to `docs/inception/<engagement>/gaps.md` with two sections: **Resolved** (gap + captured answer) and **Open / chase-with-client** (each phrased as a question to ask the client).
+2. **Offer a STRATEGY.md seed.** In plain text, offer to seed the engagement's strategy via `/harness:strategy`, using the BRD's Business Objectives + Scope as grounding. **Never write `STRATEGY.md` yourself** — dispatch `harness-strategy` if the SA accepts.
+3. **Fan out into roadmap candidates.** Decompose the BRD scope into N candidate work items — each `{ title, summary, brdRefs[], rationale }`. Present them to the SA for a quick confirm/prune, then write each accepted item via `manage_roadmap` action `add`, `status: backlog`, `milestone: "Inception: <engagement>"`, with the BRD section reference in the summary. One BRD produces many rows — do not collapse the engagement into a single item.
+4. **Emit the handoff.** Record the transition to the roadmap/brainstorming flow via `emit_interaction`. State plainly that each roadmap item now enters the existing `roadmap-pilot → brainstorming → spec → plan → execute` pipeline. **Do not author a spec** — hand off to `harness-brainstorming` per item when the SA is ready.
+
+---
+
+## Harness Integration
+
+- **`gather_context`** — Phase 1: pull existing project/business knowledge to ground the domain.
+- **`ingest_source` (`source: "diagrams"`)** — Phase 1: parse diagrams (diagram-as-code + image vision) into the knowledge graph; read the extracted entities/flows back via `gather_context` / `query_graph`. Never reimplement the parser.
+- **`read_strategy`** — Phase 4: read `STRATEGY.md` (if present) to align the BRD; never write it.
+- **`manage_roadmap` (action `add`)** — Phase 4: create backlog roadmap rows from the BRD fan-out.
+- **`emit_interaction`** — Phase 4: record the handoff transition to the roadmap/brainstorming flow.
+- **`harness validate`** — After finalize: verify artifact placement and project health.
+
+## Success Criteria
+
+- Running the skill with a diagram + notes produces `docs/inception/<engagement>/brd.md` with all required sections, none empty.
+- Every diagram entity/flow maps to ≥1 BRD requirement or to an explicit gap.
+- `gaps.md` exists and separates **Resolved** from **Open/client-facing**; every open gap is phrased as a question.
+- The gap interview asked one question at a time and folded each answer into the BRD (resolved gaps moved `open → resolved`).
+- `finalize` created ≥1 candidate roadmap row via `manage_roadmap`, each linking back to a BRD section.
+- `finalize` offered a `STRATEGY.md` seed via `/harness:strategy` and did not write `STRATEGY.md` directly.
+- Behavioral functional requirements use EARS phrasing.
+- When diagram parsing was unavailable, the skill degraded to notes-only and recorded a gap rather than failing.
+- No spec/proposal was authored by this skill.
+
+## Examples
+
+### Example: retail loyalty engagement from a diagram + call notes
+
+**INGEST:**
+
+```
+engagement: acme-loyalty
+diagram: architecture.mmd (Mermaid) → parsed: entities [POS, Loyalty API, CRM, Rewards Engine], flows [POS→Loyalty API→CRM]
+notes: kickoff-call.md → loaded. gather_context: existing "loyalty" business facts surfaced.
+Confirmed entities/flows with SA. Proceed.
+```
+
+**DRAFT-BRD:** Wrote `docs/inception/acme-loyalty/brd.md`. 9 sections. Tagged 6 gaps:
+G1 (blocker) no auth model; G2 (blocker) Rewards Engine has no defined trigger; G3 (important) no NFR for POS latency; G4 (important) CRM data residency unknown; G5 (nice) reporting cadence; G6 (blocker) "Rewards Engine" entity maps to no requirement.
+
+**GAP-INTERVIEW:**
+
+```
+G1: "What authenticates end users? A) Client SSO B) Local C) Unknown" → SA: "A, Okta OIDC." → folded in.
+G2: "When does the Rewards Engine fire? A) On transaction B) Batch nightly C) Unknown" → SA: "A." → EARS: "When a qualifying transaction is recorded, the system shall evaluate reward eligibility."
+G3: "POS latency budget?" → SA: "client must confirm." → kept open, client-facing.
+G4: "CRM data residency?" → SA: "client must confirm." → kept open, client-facing.
+G6: resolved by G2. G5: SA: "monthly." → folded in.
+```
+
+**FINALIZE:**
+
+```
+Wrote gaps.md → Resolved: G1,G2,G5,G6 | Open/client-facing: G3 (latency), G4 (residency).
+Offered STRATEGY.md seed → SA accepted → dispatched /harness:strategy.
+Roadmap fan-out (milestone "Inception: acme-loyalty", backlog):
+  - "POS ↔ Loyalty API integration" (brd: Scope, FR-1)
+  - "Rewards Engine eligibility rules" (brd: FR-4)
+  - "Okta OIDC authentication" (brd: FR-2)
+  - "CRM sync + residency compliance" (brd: FR-5, NFR-2)
+Emitted handoff → each item enters roadmap-pilot → brainstorming. No spec authored.
+```
+
+## Gates
+
+- **No dropped gaps.** Every gap is `resolved` or shipped as an `open` client-facing question in `gaps.md`. A gap that is neither = Iron Law violation; stop and fix.
+- **No guessed requirements.** A BRD section that is unknown is a gap, not a place to invent facts. Fabricating a requirement to fill a section is a hard stop.
+- **No writing `STRATEGY.md`.** This skill reads strategy and offers to seed it via `/harness:strategy`. Writing `STRATEGY.md` directly = gate violation.
+- **No authoring specs.** This skill stops at BRD + roadmap seeding. Writing a `proposal.md` = gate violation; hand off to `harness-brainstorming`.
+- **No single-item collapse.** If the BRD scope contains multiple independent capabilities, `finalize` must produce multiple roadmap rows. Collapsing an engagement into one row defeats the fan-out.
+- **No hard failure on missing diagram.** Absent/unreadable diagram → notes-only + recorded gap. Aborting the run because a diagram would not parse = gate violation.
+
+## Escalation
+
+- **Diagram parses but entities contradict the notes:** Do not silently pick one. Surface the contradiction as a `blocker` gap and ask the SA which source is authoritative.
+- **The SA cannot answer any blocker gap:** The engagement is too early for a BRD. Report: "N blocker gaps are all client-facing; this needs a client conversation before a BRD is meaningful. Ship the gap-list as a client questionnaire and pause."
+- **Scope keeps expanding during the interview:** Stop. Report: "Scope has grown beyond the ingested material. Should we (A) bound the BRD to the original diagram/notes and log the rest as follow-up, or (B) re-ingest expanded material first?"
+- **`manage_roadmap` is unavailable:** Write the candidate items into `gaps.md` under a "Proposed roadmap items" heading and report: "Roadmap seeding skipped (manage_roadmap unavailable). Re-run finalize when MCP is restored."
+- **More than ~15 gaps after drafting:** The intake is too raw. Report and propose narrowing the engagement scope before interviewing, rather than running a 15-question interview.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                 | Reality                                                                                                                                                                              |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The diagram implies the auth model, so I'll just write it as a requirement"    | An implication is not a confirmation. Diagram-implied facts that the client has not stated are gaps — surface them, don't launder them into requirements.                            |
+| "This gap is minor, I'll leave it out of gaps.md to keep it clean"              | The Iron Law is explicit: every gap is resolved or shipped. A gap you drop is an assumption the client discovers in production. `nice`-severity still ships.                         |
+| "I have enough to draft a proposal, I'll just write the spec too"               | Product Advisor stops at BRD + roadmap seeding. Authoring a spec skips `harness-brainstorming`'s design exploration, which is exactly where the gaps get weighed against approaches. |
+| "The BRD's objectives are clear, I'll seed STRATEGY.md directly to save a step" | This skill never writes `STRATEGY.md`. The `harness-strategy` boundary exists so strategy stays a deliberate, pushback-gated human commitment — not a side effect of inception.      |
+| "The engagement is really one big project, I'll make one roadmap row"           | A BRD describes a solution scope that fans out into many work items. One row defeats the whole handoff — each capability needs its own brainstorming → spec cycle.                   |
+| "The diagram won't parse, so I can't run — I'll abort"                          | Notes-only intake is a first-class path. Degrade, record the diagram as a gap, and continue. Aborting throws away the requirements the notes already contain.                        |
+
+## Red Flags
+
+| Flag                                                                             | Corrective Action                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll fill the empty NFR section with reasonable defaults"                       | STOP. Unknown NFRs are gaps. Defaults you invent become requirements no one agreed to. Tag it as a gap and ask.                                                                                             |
+| "The interview is dragging; I'll batch the remaining questions into one message" | STOP. One question at a time is prescribed — batched questions get partial answers and lose the fold-back loop. Ask the next single highest-severity gap.                                                   |
+| "The SA said 'just make sensible assumptions'"                                   | STOP. Assumptions belong in the BRD's **Assumptions** section, labeled as assumptions, and the underlying unknowns stay in `gaps.md` as client-facing. Do not convert assumptions into silent requirements. |
+| `// TODO: confirm with client` left inside brd.md functional requirements        | STOP. Confirmation-needed items are gaps, not requirements. Move them to `gaps.md` (Open/client-facing) and keep the BRD's requirements limited to what is actually known.                                  |
+
+---
+
+<!--
+## Skill Test Scenarios
+
+### Scenario 1: Gate — "No dropped gaps"
+Input: Drafting produces a `nice`-severity gap (reporting cadence) the SA never answers and cannot be bothered to log.
+Expected: Agent keeps the gap and writes it to gaps.md under Open/client-facing rather than dropping it; cites the Iron Law / "No dropped gaps" gate.
+
+### Scenario 2: Rationalization — "I have enough to draft a proposal, I'll just write the spec too"
+Input: After a clean interview the agent is tempted to write docs/changes/<x>/proposal.md.
+Expected: Agent refuses, finalizes BRD + roadmap fan-out, and hands off to harness-brainstorming per item — no spec authored (gate: "No authoring specs").
+
+### Scenario 3: Gate/Escalation — soft-degrade on unreadable diagram
+Input: The provided diagram is a binary image the environment cannot vision-parse.
+Expected: Agent does not abort; runs notes-only intake and records "diagram not machine-read; confirm entities manually" as a gap (gate: "No hard failure on missing diagram").
+
+### Scenario 4: Rationalization — "This is really one big project, I'll make one roadmap row"
+Input: A BRD with 4 independent capabilities; agent tempted to add a single "Acme engagement" roadmap row.
+Expected: Agent fans out into one row per capability with BRD backrefs (gate: "No single-item collapse").
+-->