@harness-engineering/cli 3.1.0 → 4.0.0

package/dist/agents/skills/claude-code/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/claude-code/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/codex/acceptance-eval/SKILL.md

@@ -0,0 +1,92 @@
+# Acceptance Eval
+
+> Pre-execution LLM-judgment: does this spec carry measurable, testable, complete acceptance criteria before work begins? Resolves the spec's acceptance section, critiques observability / testability / completeness (advisory `criteriaFindings`), flags user-visible behaviors with no covering test (advisory `coverageFindings`), and emits a confidence-rated `AcceptanceVerdict` (`MEASURABLE | NOT_MEASURABLE | INCONCLUSIVE`) with a rationale. Merge authority is derived in TypeScript, never trusted from the LLM: a high-confidence `NOT_MEASURABLE` blocks merge; every other verdict is advisory. The upstream twin of the `outcome-eval` ship gate — it keeps the downstream gate fed with judgable specs.
+
+## When to Use
+
+- On every spec entering the repo under `docs/changes/**` — triggered `on_pr` (and `manual`) — before execution begins.
+- When you need a durable, structured answer to "can this spec's success be objectively judged later?"
+- NOT for judging whether an implementation satisfied its spec post-execution (use `outcome-eval`, the downstream twin).
+- NOT for authoring acceptance criteria — `acceptance-eval` reviews; humans own the thinking layer. It never writes the criteria it judges.
+- NOT for rule-based floors (lint/architecture/entropy) or other craft ceilings — those run elsewhere.
+- NOT when no judgable spec section exists — the verdict degrades to INCONCLUSIVE/advisory and never blocks.
+
+## Process
+
+### Phase 1: RESOLVE — Find the judgment section
+
+The evaluator resolves the section internally via the fallback chain `## Success Criteria` -> `## User-Visible Behavior` -> `## Overview` (reusing `outcome-eval`'s resolver, not a fork), recording the match in `judgedAgainst`. No manual action — pass `specPath` and let `AcceptanceEvaluator` resolve. If no section is judgable, the verdict is INCONCLUSIVE/advisory.
+
+### Phase 2: GATHER — Locate test evidence for coverage (optional)
+
+For responsibility (b), supply test evidence so the judge can flag user-visible behaviors with no covering test: pass `testGlobs` (globs the tool reads) or `testContent` (snippets you already read). This evidence is optional: omitting it degrades `coverageFindings` to advisory-empty but NEVER affects the (c) measurability gate. Gather it when the spec describes user-visible behavior.
+
+### Phase 3: JUDGE — Invoke the evaluator
+
+1. Invoke the MCP tool `mcp__harness__acceptance_eval` with `{ specPath }` plus optional `{ testGlobs | testContent, model }`. The tool constructs `AcceptanceEvaluator` cli-side and returns the verdict; the supported v1 provider is the anthropic analysis provider (`ANTHROPIC_API_KEY`).
+2. The LLM returns ONLY `measurability / confidence / criteriaFindings / coverageFindings / rationale`. `authority` is computed in TypeScript from `(measurability, confidence)` via `deriveAcceptanceAuthority` and is never read from the LLM — do not attempt to override it. The tool returns the verdict exactly as the evaluator derives it.
+3. The call is degrade-safe: provider failure (incl. no `ANTHROPIC_API_KEY`), empty test evidence, or a missing judgable section yields INCONCLUSIVE/low/advisory. It never throws and never blocks.
+
+### Phase 4: GATE — Render and (conditionally) halt
+
+1. Render the verdict: `measurability`, `confidence`, `judgedAgainst`, `rationale`, `criteriaFindings` (a, advisory), and `coverageFindings` (b, advisory).
+2. Authority rule (must match `deriveAcceptanceAuthority`): authority is `blocking` **iff** `measurability === 'NOT_MEASURABLE' && confidence === 'high'`; every other combination — including all `INCONCLUSIVE` and `MEASURABLE` cases, and all `medium`/`low` `NOT_MEASURABLE` — is `advisory`.
+3. **On a blocking verdict: HALT before merge.** Report the missing measurable criteria and stop; the spec must not merge. Resolution requires a human adding measurable success criteria and re-running `acceptance-eval`.
+4. On an advisory verdict: report the `criteriaFindings` and `coverageFindings` for human attention and proceed. Advisory findings do not stop the workflow.
+
+## Harness Integration
+
+- **`mcp__harness__acceptance_eval`** — MCP tool (the invocation surface). Inputs: `specPath` (required), `testGlobs` / `testContent` (optional (b) evidence), `model` (optional). The handler builds the cli `AnalysisProvider`, constructs `AcceptanceEvaluator`, and returns the `AcceptanceVerdict` with `authority` exactly as derived in TypeScript. (No graph persistence in v1 — the seam is documented in the tool header.)
+- **Evaluator surface:** `AcceptanceEvaluator`, `deriveAcceptanceAuthority`, `acceptanceVerdictSchema`, `AcceptanceVerdict` are exported from `@harness-engineering/intelligence`. The section resolver is imported from `outcome-eval`, not duplicated.
+- **Provider path (v1 supported):** the anthropic analysis provider (`ANTHROPIC_API_KEY`). When no provider is configured the call degrades to INCONCLUSIVE/advisory.
+- **Relationship to `outcome-eval`:** `acceptance-eval` is the upstream twin. It guards spec measurability before execution; `outcome-eval` judges implementation satisfaction after. The same "authority is never read from the LLM" discipline spans both ends of the lifecycle.
+
+## Known Limitations
+
+- **Coverage findings (b) are heuristic and advisory.** Without `testGlobs`/`testContent` they are advisory-empty; even with evidence they are LLM-judgment over the behavior section plus located tests, not a graph-backed coverage map (deferred — see spec Decision D4). Heuristic misses are low-harm because (b) never blocks.
+- **The (c) gate blocks only on high-confidence NOT_MEASURABLE.** A spec with weak-but-present criteria yields an advisory verdict, not a block — intentional, to avoid taste-blocks-merge false positives.
+- **openai-compatible strict mode** is not the v1 path; the supported provider is anthropic/claude-cli.
+
+## Success Criteria
+
+See `docs/changes/harness-pm-persona/proposal.md` for the full criteria. This skill satisfies SC1 (skill exists, `tier: 2`, `type: rigid`, four-client artifacts), SC6 (blocking halt on high-confidence NOT_MEASURABLE; advisory-and-proceed otherwise), and SC7 (emits advisory `criteriaFindings` / `coverageFindings`).
+
+## Examples
+
+### Example: NOT_MEASURABLE with high confidence (blocks)
+
+**Input:** a spec whose only "success criteria" are "the feature works well" and "users are happy" — no observable, testable assertions.
+
+**Verdict:**
+
+```
+measurability:   NOT_MEASURABLE
+confidence:      high
+judgedAgainst:   success-criteria
+authority:       blocking
+criteriaFindings:
+  - { target: "'works well' / 'users are happy'", message: "No observable assertion — cannot be tested." }
+rationale:       "The success section contains only subjective statements; nothing can be judged at outcome time."
+```
+
+**Action:** HALT before merge. Report the missing measurable criteria; the spec must not merge until a human adds them.
+
+### Example: measurable criteria (advisory, proceeds)
+
+**Input:** a spec whose Success Criteria list concrete, testable assertions; one user-visible behavior lacks an obvious covering test.
+
+**Verdict:** `measurability: MEASURABLE confidence: high authority: advisory`, with one `coverageFindings` `{target, message}` object (the one user-visible behavior lacking a covering test) surfaced for review. The workflow proceeds.
+
+## Gates
+
+- **Authority is never read from the LLM.** The verdict's `authority` is always `deriveAcceptanceAuthority(measurability, confidence)` computed in TypeScript. If you find yourself letting the model assert blocking/advisory, STOP — that defeats the entire purpose of this gate.
+- **Block only on high-confidence NOT_MEASURABLE.** `authority === 'blocking'` iff `measurability === 'NOT_MEASURABLE' && confidence === 'high'`. Every other combination is advisory. Do not halt on an advisory verdict.
+- **Never author criteria.** `acceptance-eval` reviews specs; it does not write the acceptance criteria it judges. Humans own the thinking layer.
+- **Never block on infrastructure noise.** A provider failure, an unparseable response, or a missing spec section must resolve to INCONCLUSIVE/advisory, never a thrown error or a block. The evaluator enforces this; do not reintroduce a hard failure in the wrapper.
+
+## Escalation
+
+- **Blocking verdict the author disputes:** the resolution is for a human to add measurable success criteria (or fix the section the resolver judged) and re-run `acceptance-eval` — not to override the gate.
+- **Repeated INCONCLUSIVE on a real spec:** usually means no judgable section exists. Confirm the spec has a Success Criteria / User-Visible Behavior / Overview section.
+- **No `ANTHROPIC_API_KEY` configured:** every verdict degrades to INCONCLUSIVE/advisory and nothing blocks. Surface this to the human — the gate is effectively disabled until a provider is configured.
+- **Verdict seems wrong (false positive/negative):** capture the spec section and verdict and route to the maintainers; do not loosen the conservative-confidence prompt ad hoc.

package/dist/agents/skills/codex/acceptance-eval/skill.yaml

@@ -0,0 +1,54 @@
+name: acceptance-eval
+version: '0.1.0'
+description: >-
+  Pre-execution LLM-judgment skill: does a spec carry measurable, testable,
+  complete acceptance criteria before work begins? Resolves the spec's
+  acceptance section, critiques observability / testability / completeness
+  (advisory), flags user-visible behaviors with no covering test (advisory),
+  and emits a confidence-rated AcceptanceVerdict
+  (MEASURABLE | NOT_MEASURABLE | INCONCLUSIVE). Authority is derived in
+  TypeScript, never from the LLM: a high-confidence NOT_MEASURABLE blocks
+  merge; every other verdict is advisory. The upstream twin of the
+  outcome-eval ship gate.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - cursor
+  - codex
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+mcp:
+  tool: acceptance_eval
+  # specPath is the only required input. testGlobs/testContent are the (b)
+  # coverage evidence: omitting them degrades coverage findings to
+  # advisory-empty but NEVER affects the (c) measurability gate.
+  input:
+    specPath: 'string (required) — absolute or repo-relative path to the spec markdown to evaluate'
+    testGlobs: 'string[] (optional) — globs locating test files that evidence (b) coverage; omission degrades coverage findings to advisory-empty, never the (c) gate'
+    testContent: 'string (optional) — pre-read test snippets as (b) coverage evidence; an alternative to testGlobs'
+    model: 'string (optional) — model override for the acceptance-eval LLM call'
+type: rigid
+tier: 2
+phases:
+  - name: resolve
+    description: Resolve the judgment section (Success Criteria -> User-Visible Behavior -> Overview), recorded in judgedAgainst
+    required: true
+  - name: gather
+    description: Locate test evidence for (b) coverage via testGlobs/testContent; optional — omission degrades coverage findings, never the (c) gate
+    required: false
+  - name: judge
+    description: Invoke AcceptanceEvaluator; the LLM returns measurability/confidence/criteriaFindings/coverageFindings/rationale; authority is derived in TS via deriveAcceptanceAuthority
+    required: true
+  - name: gate
+    description: Render the verdict; on a blocking verdict (NOT_MEASURABLE + high confidence) HALT before merge
+    required: true
+state:
+  persistent: false