@harness-engineering/cli 2.7.1 → 3.0.0

package/dist/agents/skills/cursor/harness-strategy/references/interview.md

@@ -0,0 +1,122 @@
+# Strategy Interview Reference
+
+The first-run interview (and the per-section update flow) converts vague intent ("we want to be the best at X") into a small, concrete `STRATEGY.md`. This document is the rule book the skill quotes when pushing back on input.
+
+The interview is heuristic — the agent reading SKILL.md applies the rules. Nothing in `packages/core` parses the user's natural-language answers. The fixture-driven contract test in `agents/skills/tests/harness-strategy.test.ts` asserts the rule _names_ and the presence of repair-script keywords; rewording surrounding prose is free.
+
+## Pushback Rules
+
+Three rules, each cited verbatim in the skill output when it fires (so the user sees _why_ the answer was rejected, not just _that_ it was). **Each rule fires AT MOST TWICE per section. After the second pushback, capture what the user offered, flag the section, and move on.** The cap is the disable mechanism — there is no flag, no override, no "I know what I'm doing" path. The cap protects users from infinite loops, not from feedback. Round 1 MUST always fire when a rule matches.
+
+### Rule 1: Fluff detection
+
+**What it catches:** Empty modifiers and mission-statement vocabulary that look like answers but state nothing concrete.
+
+| Detection signal                                                              | Example trigger                                     |
+| ----------------------------------------------------------------------------- | --------------------------------------------------- |
+| Empty modifiers: "best", "leading", "world-class", "best-in-class", "premier" | _"We want to be the best at developer experience."_ |
+| Mission-statement verbs: "delight", "empower", "transform", "revolutionize"   | _"Empower engineers to build amazing things."_      |
+| Answers ≤ 5 words with no domain-specific noun                                | _"Deliver value."_ / _"Win the market."_            |
+| Adjective-only diagnoses: "broken", "bad", "slow" without an object           | _"It's slow."_ / _"It's hard."_                     |
+
+**Repair script:**
+
+> Replace `<phrase>` with a concrete diagnosis: _what is broken_, _for whom_, _that we can verify_. "We want to be the best at X" is not a diagnosis — it's an aspiration. Try the next layer down: which _specific_ failure mode are we trying to remove from the world?
+
+### Rule 2: Goal-as-strategy
+
+**What it catches:** Targets, KPIs, and fiscal-year aspirations dressed up as strategy. A goal is a destination; strategy is the bet you're making about how to get there.
+
+| Detection signal                                                         | Example trigger                                          |
+| ------------------------------------------------------------------------ | -------------------------------------------------------- |
+| Numeric targets without an underlying bet                                | _"Grow revenue by 20% this year."_ / _"Get to 10k DAU."_ |
+| Fiscal-year or quarter phrasing under `Target problem` or `Our approach` | _"By Q4 we'll have shipped the new platform."_           |
+| KPI-shape strings: "increase X by Y%", "reduce X to Z"                   | _"Reduce churn to under 5%."_                            |
+| Sentences that name a metric value but not a mechanism                   | _"Hit 99.9% uptime."_                                    |
+
+**Repair script:**
+
+> That's a goal. What is the **bet** — the choice you're making about _how_ to produce it — that goes underneath? Strategy is the coherent action that, if it works, produces the goal. "Grow revenue 20%" is the destination; _how_ you'll do it (which segment, which channel, which product wedge) is the strategy.
+
+### Rule 3: Feature-list-as-strategy
+
+**What it catches:** Roadmap-style enumerations of components dressed up as strategy. Feature lists don't survive contact with reality; the coherent action underneath does.
+
+| Detection signal                                                              | Example trigger                                       |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Multi-item lists (≥3 bullets) of feature/component names under `Our approach` | _"- Dashboard, - Notifications, - Mobile app, - SSO"_ |
+| Noun-heavy lists with no verbs describing the coherent action                 | _"- AI agents - Knowledge graph - Skill registry"_    |
+| Track names that are feature names (e.g., `- Dashboard:`, `- Mobile:`)        | _"- Dashboard: ship the new dashboard"_               |
+| `Our approach` answered as a roadmap rather than a thesis                     | _"First we'll do X, then Y, then Z."_                 |
+
+**Repair script:**
+
+> Feature lists don't survive contact with reality. What's the **coherent action** these features are instances of? The features are downstream of the bet. State the bet, then the features become consequences ("we're betting on agent-orchestrated workflows, so dashboard/SSO/mobile fall out of that"), not the strategy itself.
+
+## The 2-Round Cap
+
+For every section, each rule fires at most twice:
+
+1. **Round 1** — Rule matches → cite the rule, quote the failing answer, offer the repair script. Wait for revised answer.
+2. **Round 2** — Rule matches the revised answer → cite the rule a second time, quote the repair script. Wait for the user's third attempt.
+3. **Cap reached** — Capture whatever the user offered on attempt 3. Emit a section flag in the doc summary:
+
+   > ⚠ <section name>: flagged for revisit — pushback cap reached without <concrete diagnosis | underlying bet | coherent action>.
+
+The flag is informational. It does NOT block the write — STRATEGY.md is the user's commitment, not the skill's gate. The flag lives in the _summary_ shown to the user, not in the on-disk file (the schema rejects unknown content).
+
+If the user explicitly says round 1's pushback is wrong (e.g., _"no, that IS the diagnosis — we really mean it this way"_), capture the answer verbatim after round 1. Do NOT push back twice if the user explicitly disagrees with round 1. This is not a third path around the cap; it's recognition that pushback is an offer, not a gate.
+
+## Separation from `docs/roadmap.md`
+
+The interview MUST refuse to capture tactical phase tracking (phase numbers, blockers, assignees, external IDs) under any section. That belongs in `docs/roadmap.md`. The two artifacts have different lifecycles:
+
+| Artifact          | Cadence            | Owner            | Content                                            |
+| ----------------- | ------------------ | ---------------- | -------------------------------------------------- |
+| `STRATEGY.md`     | Quarterly-ish      | Product / lead   | Target problem, approach, persona, metrics, tracks |
+| `docs/roadmap.md` | Per-phase / weekly | Eng orchestrator | Phase status, blockers, assignees, external-IDs    |
+
+If the user asks "where do I track that we're blocked on X" or "where do I record the assignee for phase 4" → answer: `docs/roadmap.md`, not `STRATEGY.md`. The separation is Decision 1 of the strategic-anchor proposal.
+
+## Section-by-section interview prompts
+
+Phase 1 walks the sections in template order. Each prompt is a single focused question; the rules above govern the response loop.
+
+| Section              | Opening prompt                                                                                                                                                   | Rules to apply                                                                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Target problem       | _"In 2-4 sentences: what is specifically broken in the world that this product addresses? Not the goal — the diagnosis."_                                        | Fluff, Goal-as-strategy                                                                                                                          |
+| Our approach         | _"What is your distinctive bet on how to solve the target problem? The choice you're making about HOW, not WHAT you're building."_                               | Fluff, Goal-as-strategy, Feature-list                                                                                                            |
+| Who it's for         | _"Specific persona — who is the person, what context are they in, what alternatives are they currently using? 'Developers' is not a specific persona."_          | Fluff                                                                                                                                            |
+| Key metrics          | _"What 1-5 metrics, measured where, would tell you the bet is paying off? Each metric is a bullet line: `- <name>: <how measured, where it lives>`."_            | Fluff (per bullet)                                                                                                                               |
+| Tracks               | _"What 1-5 tracks of work are you currently investing in to advance the bet? Each track is a bullet line: `- <track name>: <one-sentence current investment>`."_ | Feature-list (per bullet)                                                                                                                        |
+| Milestones (opt)     | _"What 2-3 dated milestones would mark visible progress on the tracks? Skip if none yet."_                                                                       | Goal-as-strategy (milestones SHOULD be dated targets — accept them here even though Rule 2 rejects them under `Target problem` / `Our approach`) |
+| Not working on (opt) | _"What did you deliberately decide NOT to invest in this cycle? Explicit non-goals reduce future drift."_                                                        | Fluff                                                                                                                                            |
+| Marketing (opt)      | _"What 1-3 sentences describe how you'd pitch this to the persona? Often this is downstream of `Target problem` + `Our approach`."_                              | Fluff                                                                                                                                            |
+
+## Anti-pattern fixtures (referenced by the contract test)
+
+The skill's contract test (`agents/skills/tests/harness-strategy.test.ts`) asserts the rule names and key repair-script phrases appear in this file. The fixtures below are the canonical anti-patterns each rule must catch.
+
+### Fluff detection fixture
+
+> **User answer (Target problem):** _"We want to be the best at developer experience."_
+>
+> **Skill response:** "**Fluff detection** fired. `be the best at` is empty-modifier vocabulary — it states an aspiration, not a diagnosis. Try the next layer down: which _specific_ failure mode in developer experience are we trying to remove from the world?"
+
+### Goal-as-strategy fixture
+
+> **User answer (Our approach):** _"Grow revenue 20% this year and reduce churn to under 5%."_
+>
+> **Skill response:** "**Goal-as-strategy** fired. Those are goals, not approach. What is the **bet** — the choice you're making about _how_ to produce them — that goes underneath?"
+
+### Feature-list-as-strategy fixture
+
+> **User answer (Our approach):** _"- Ship the new dashboard. - Add notifications. - Build the mobile app. - Wire up SSO."_
+>
+> **Skill response:** "**Feature-list-as-strategy** fired. Feature lists don't survive contact with reality. What's the **coherent action** these features are instances of? The features are downstream of the bet."
+
+## Update-flow guidance
+
+Phase 2 of the skill re-interviews ONE user-selected section at a time. The same three rules apply. **Re-running a section does not exempt it from pushback** — "no rubber-stamping" is the proposal Decision 4 phrasing.
+
+When the user revisits a section and the new answer also triggers a rule, the 2-round cap still applies — counted _within that revisit_, not cumulatively across all-time runs.

package/dist/agents/skills/cursor/harness-strategy/skill.yaml

@@ -0,0 +1,54 @@
+name: harness-strategy
+version: "0.1.0"
+description: First-run interview and update flow for STRATEGY.md — the durable upstream product anchor read by harness-brainstorming, harness-ideate, and harness-roadmap-pilot. Enforces three pushback rules (fluff, goal-as-strategy, feature-list-as-strategy) with a 2-round-per-section cap. Phase 2 ships the skill; downstream wiring (init, brainstorming, roadmap-pilot, ideate, knowledge graph) ships in spec Phases 3-7.
+stability: static
+cognitive_mode: configuration-interviewer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-strategy
+  args: []
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-strategy
+type: rigid
+tier: 2
+phases:
+  - name: route
+    description: Route by STRATEGY.md presence and validity (absent → first-run; valid → update; invalid → repair offer)
+    required: true
+  - name: first-run-interview
+    description: Walk sections in template order with pushback; cap at 2 rounds per section; write via writeStrategyDoc
+    required: true
+  - name: update
+    description: Re-interview a single user-selected section; bump version and last_updated; preserve untouched sections
+    required: false
+  - name: handoff
+    description: Note which downstream skills (harness-brainstorming, harness-ideate, harness-roadmap-pilot, BusinessKnowledgeIngestor) will pick up STRATEGY.md as grounding
+    required: true
+state:
+  persistent: true
+  files:
+    - STRATEGY.md
+    - STRATEGY.md.bak
+depends_on: []
+keywords:
+  - strategy
+  - strategic-anchor
+  - product-anchor
+  - upstream-grounding
+  - compound-engineering
+  - rumelt

package/dist/agents/skills/cursor/harness-test-advisor/SKILL.md

@@ -8,8 +8,9 @@
 - In CI — optimize test suite execution order
 - When a test fails — understand which changes could have caused it
 - When `on_pr` triggers fire
-- NOT for writing tests (use harness-tdd)
-- NOT for test quality analysis (out of scope)
+- **Coverage Audit mode** — when no diff is available and the user asks for "coverage gaps", "deep dive", "coverage plan", or "what's untested", run project-wide gap analysis instead of test selection
+- NOT for writing tests (use harness-tdd, or `canary:canary-write-test` for uncovered files surfaced by Coverage Audit)
+- NOT for test quality analysis at the test-selection level (Coverage Audit mode does include a capped quality review via `canary:canary-review-test`)
 
 ## Prerequisites
 
@@ -112,6 +113,83 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes/login.test.ts tests/middleware/verify.test.ts tests/integration/auth-flow.test.ts
 ```
 
+## Coverage Audit Mode
+
+Activates when `--audit` is passed, OR when no diff is available AND the user's
+language matches audit intent ("coverage gaps", "deep dive", "coverage plan",
+"what's untested"). When this mode is selected, skip Phases 1–3 above and run
+the audit phases below instead.
+
+### Audit Phase 0: PROBE — Detect canary CLI availability
+
+Call the `canary_probe` MCP tool once at the start of the audit. It returns
+`{ status: "available" | "degraded", version?, reason? }` and never errors.
+
+- **`available`** — the deterministic canary CLI is usable; use `canary_recommend_framework`
+  for framework selection in Phase 3 (GAP REPORT).
+- **`degraded`** — the CLI is not usable (reason: `not-installed`, `binary-missing`,
+  `exec-failed`, or `bad-output`). Print one line:
+
+  > canary CLI unavailable (`<reason>`) — install `canary-test-cli` for deterministic
+  > framework recommendations. Proceeding; framework picks fall back to the plugin.
+
+  Then skip `canary_recommend_framework` calls for the rest of the run. This does **not**
+  affect the plugin-based Quality Review in Phase 2 (`canary:canary-review-test` is a
+  separate Claude Code plugin, installed independently of the CLI).
+
+### Audit Phase 1: INVENTORY — Build the Source-to-Test Map
+
+1. **Enumerate source files**: glob for `.ts`, `.tsx`, `.js`, `.jsx` under the
+   project's source roots (e.g., `src/`, `packages/*/src/`). Skip `node_modules`,
+   `dist`, build outputs, and fixtures.
+2. **Enumerate test files**: glob for `*.test.*`, `*.spec.*`, and files under
+   `__tests__/` and parallel `tests/` directories.
+3. **Map source → test**: for each source file, find its test file using the
+   Tier 1 / Tier 2 / Tier 3 strategies described in `Phase 2: DISCOVER`. With a
+   graph, prefer `get_impact`; without one, use naming conventions and import
+   parsing.
+4. **Split**: produce two lists — `covered` (source files with at least one
+   matching test) and `uncovered` (source files with no matching test).
+
+### Audit Phase 2: QUALITY REVIEW — Critique Covered Test Files
+
+1. **Cap at 10 files per run**: a deep quality review is expensive. Pick the
+   top 10 covered files prioritized by size (lines of code) and criticality
+   (depth in the graph / co-change frequency). The remaining covered files are
+   accepted as-is for this run.
+2. **For each of the 10**: dispatch `canary:canary-review-test` against the
+   test file. Collect its findings (missing edge cases, anti-patterns,
+   brittleness, oracle gaps).
+3. **Aggregate**: bin findings by severity (high / medium / low) and by file.
+
+### Audit Phase 3: GAP REPORT — Synthesize a Unified Coverage Plan
+
+Emit a single report with three sections:
+
+```
+## Coverage Audit Report
+
+### Uncovered Files (no test found)
+| File | Lines | Priority | Suggested Action |
+|------|-------|----------|------------------|
+| src/services/billing.ts | 412 | high | canary:canary-write-test |
+| src/utils/format.ts     | 38  | low  | canary:canary-write-test |
+
+### Quality Gaps (from Quality Review, capped at 10 reviewed)
+| Test File | Severity | Top Gap |
+|-----------|----------|---------|
+| tests/services/auth.test.ts | high | no failure-path assertions |
+| tests/utils/date.test.ts    | med  | mock leaks across cases |
+
+### Recommended Next Steps
+- Generate tests for high-priority uncovered files via `canary:canary-write-test`.
+- Resolve high-severity quality gaps via `canary:canary-review-test` follow-ups.
+- For uncovered files, pick a framework first: when Phase 0 reported `available`, call
+  the `canary_recommend_framework` MCP tool with a prompt describing the file's purpose
+  (deterministic, no LLM round-trip) and put its `framework` in the Suggested Action.
+  When `degraded`, fall back to the `canary:canary-pick-framework` plugin.
+```
+
 ## Harness Integration
 
 - **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.

package/dist/agents/skills/cursor/harness-test-advisor/skill.yaml

@@ -1,6 +1,6 @@
 name: harness-test-advisor
 version: "1.0.0"
-description: Graph-based test selection — answers "what tests should I run?"
+description: Graph-based test selection and project-wide coverage audit — answers "what tests should I run?" or "what's untested?"
 stability: static
 cognitive_mode: advisory-guide
 triggers:
@@ -25,6 +25,9 @@ cli:
     - name: files
       description: Comma-separated list of changed files
       required: false
+    - name: audit
+      description: Run Coverage Audit mode (project-wide gap analysis) instead of test selection
+      required: false
 mcp:
   tool: run_skill
   input:

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

@@ -29,6 +29,8 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
 ## Process
 
+**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 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.
@@ -96,7 +98,7 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
    - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
    - **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 yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+   - **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`:
 
@@ -136,10 +138,64 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
     Based on the answer:
     - **Yes:** Ask a follow-up: "Which platforms? `web`, `mobile`, or both?" Write `design.enabled: true` and `design.platforms: [...]` (a non-empty array of `web` and/or `mobile`) to `harness.config.json`. Inform the user: "Design tokens will be generated when you start your first design-touching feature — `harness-design-system` fires automatically via `on_new_feature`."
     - **No:** Write `design.enabled: false` to `harness.config.json`. Do not write `design.platforms`. The `on_new_feature` trigger respects this flag and will not fire `harness-design-system`.
-    - **Not sure yet:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.
+    - **Not sure:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.
 
     **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
@@ -249,7 +305,7 @@ This phase closes the parity gap that the marketplace plugin install does not co
 
    Based on the answer:
    - **Yes:** Invoke `harness-roadmap` (skill) or run `/harness:roadmap --create` to create `docs/roadmap.md`. Verify the file exists. The `manage_roadmap` MCP tool is for managing entries in an existing roadmap, not for creating one.
-     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Current Work"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
+     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Intake"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
    - **No:** Skip silently. The user can still run `/harness:roadmap --create` later — that informational fallback remains valid.
 
 2. **Commit the initialization.** All generated, configured, and instrumentation files in a single commit. Include `harness.config.json`, `AGENTS.md`, `.harness/arch/baselines.json`, `.harness/telemetry.json` (if created), updates to project `.mcp.json` (if Tier-0 integrations were wired), and any roadmap files.
@@ -269,9 +325,11 @@ 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.
 - **`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 `Current Work` with a summary describing the deferred work.
+- **`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.
 
 ## Success Criteria
 
@@ -284,25 +342,29 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - The adoption level matches what was agreed upon with the human
 - 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.
+- 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.
 - **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 `Current Work` with a summary describing the deferred work. The entry is absent in all other answer combinations.
+- 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.
 - For test suites: `initialize-test-suite-project` ran to completion and its Success Criteria are also met
 - For plugin-only invocations: every CLI invocation in this skill ran successfully via `npx @harness-engineering/cli <cmd>` without requiring a global install. If any invocation failed because the npx download failed, the human was prompted to retry or `npm install -g @harness-engineering/cli` instead.
 
 ## Rationalizations to Reject
 
-| Rationalization                                                          | Why It Is Wrong                                                                                                                                                                                                                                                                 |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The generated AGENTS.md template looks fine -- no need to customize it" | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                               |
-| "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`. |
-| "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.                                      |
-| "This is a test suite, we'll configure layers in this skill"             | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                       |
+| Rationalization                                                              | Why It Is Wrong                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The generated AGENTS.md template looks fine -- no need to customize it"     | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                                                                                                                 |
+| "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.                                                                                                                       |
+| "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.                                                                                                                        |
+| "This is a test suite, we'll configure layers in this skill"                 | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                                                                                                         |
 
 ## Examples
 
@@ -377,6 +439,11 @@ 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).
 ```
 
@@ -393,7 +460,7 @@ Step 4 (roadmap): "Set up a project roadmap now?"
   design.enabled === true detected → manage_roadmap action: add
     feature: "Set up design system"
     status: planned
-    milestone: Current Work
+    milestone: Intake
     summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens..."
   Result: docs/roadmap.md contains the planned design item.
 
@@ -405,7 +472,7 @@ git add harness.config.json .harness/ AGENTS.md docs/roadmap.md
 git commit -m "feat: initialize harness project with design and roadmap"
 ```
 
-**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Current Work`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.
+**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Intake`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.
 
 ### Example: Migrating Existing Project from Basic to Intermediate
 
@@ -482,6 +549,7 @@ npx @harness-engineering/cli init  # auto-detects framework
 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/cursor/initialize-harness-project/skill.yaml

@@ -35,3 +35,4 @@ state:
 depends_on:
   - initialize-test-suite-project
   - harness-design-system
+  - harness-roadmap

package/dist/agents/skills/cursor/outcome-eval/SKILL.md

@@ -0,0 +1,97 @@
+# Outcome Eval
+
+> Post-execution LLM-judgment: did the implementation actually satisfy its spec? Reads the spec's acceptance section, the change diff, and test output, and emits a confidence-rated `OutcomeVerdict` (`SATISFIED | NOT_SATISFIED | INCONCLUSIVE`) with a rationale and unmet criteria. Ship authority is derived in TypeScript, never trusted from the LLM: a high-confidence `NOT_SATISFIED` blocks ship; every other verdict is advisory. The harness's first blocking post-execution spec-satisfaction gate (the roadmap's named #1 gap). Each verdict persists as an `execution_outcome` node, compounding into skill-effectiveness baselines.
+
+## When to Use
+
+- At orchestrator step 6.5 — after Code Review, before Ship — on every change with a spec.
+- When you need a durable, structured answer to "did this code do what the spec said?"
+- NOT for pre-execution risk simulation (use PESL).
+- NOT for rule-based floors (lint/architecture/entropy) or craft ceilings (naming/spec/security) — those run elsewhere.
+- NOT for auto-remediation. outcome-eval judges; it does not fix.
+- NOT when no judgable spec section exists — the verdict degrades to INCONCLUSIVE/advisory and never blocks.
+
+## Process
+
+### Phase 1: GATHER — Collect inputs
+
+1. Capture the change under judgment as a unified diff: `git diff` (or `git diff <base>...HEAD` for a branch). Record it as `diff`.
+2. Capture test-runner output. If a test command is known, run it and capture stdout+stderr as `testOutput`; otherwise pass the most recent captured output. Empty/unparseable test output is tolerated (degrades to advisory).
+3. Resolve the spec path. Prefer the spec under `docs/changes/<feature>/proposal.md` for the current change. Record as `specPath`.
+
+### Phase 2: RESOLVE — Find the judgment section
+
+The evaluator resolves the section internally via the fallback chain `## Success Criteria` -> `## User-Visible Behavior` -> `## Overview`, recording the match in `judgedAgainst`. No manual action — pass `specPath` and let `OutcomeEvaluator` resolve. If no section is judgable, the verdict is INCONCLUSIVE/advisory.
+
+### Phase 3: JUDGE — Invoke the evaluator
+
+1. Invoke the MCP tool `mcp__harness__outcome_eval` with `{ specPath, diff, testOutput }` (optional `model`). The tool constructs `OutcomeEvaluator` cli-side and calls `evaluate({ specPath, diff, testOutput })`; the supported v1 provider is the anthropic analysis provider (`ANTHROPIC_API_KEY`).
+2. **`diff` and `testOutput` are required inputs and the agent MUST supply them** from the session (`git diff` + captured test-runner output). They are the evidence the judge reasons over — passing an empty `diff` or empty `testOutput` is the degradation path, not the normal path: the verdict degrades to INCONCLUSIVE/advisory (never blocking), which defeats the gate. Do not invoke the tool without real diff/test content.
+3. The LLM returns ONLY `verdict / confidence / rationale / unmetCriteria`. `authority` is computed in TypeScript from `(verdict, confidence)` and is never read from the LLM — do not attempt to override it. The tool returns the verdict exactly as the evaluator derives it.
+4. The call is degrade-safe: provider failure (incl. no `ANTHROPIC_API_KEY`), empty diff, empty test output, or missing judgable section yields INCONCLUSIVE/low/advisory. It never throws and never blocks.
+
+### Phase 4: GATE — Render and (conditionally) halt
+
+1. Render the verdict: `verdict`, `confidence`, `judgedAgainst`, `rationale`, and `unmetCriteria`.
+2. Authority rule (must match `deriveAuthority`): authority is `blocking` **iff** `verdict === 'NOT_SATISFIED' && confidence === 'high'`; every other combination — including all `INCONCLUSIVE` and `SATISFIED` cases, and all `medium`/`low` `NOT_SATISFIED` — is `advisory`.
+3. **On a blocking verdict: HALT before the Ship step.** Report the unmet criteria and stop; do not proceed to step 7. Resolution requires fixing the implementation (or the spec) and re-running outcome-eval.
+4. On an advisory verdict: report it and proceed. Advisory `NOT_SATISFIED` is surfaced for human attention but does not stop the workflow.
+
+## Harness Integration
+
+- **`mcp__harness__outcome_eval`** — MCP tool (the invocation surface). Inputs: `specPath` (required), `diff` (required), `testOutput` (required), `model` (optional), `path` (optional project root for graph persistence). The agent supplies `diff` and `testOutput` from the session; omitting them degrades the verdict to INCONCLUSIVE/advisory (never blocking). The handler builds the cli `AnalysisProvider` + a `GraphStore`, constructs `OutcomeEvaluator`, and returns the `OutcomeVerdict` with authority exactly as derived in TypeScript.
+- **Evaluator surface:** `OutcomeEvaluator`, `deriveAuthority`, `verdictSchema`, `OutcomeVerdict` are exported from `@harness-engineering/intelligence`.
+- **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`.
+
+## Known Limitations
+
+- **INCONCLUSIVE persistence:** the persisted node maps `INCONCLUSIVE -> result: 'failure'` for type-validity, but it OMITS `agentPersona` and writes `affectedSystemNodeIds: []`. The effectiveness scorer (`gatherOutcomes`) ignores any node missing `agentPersona` or `outcome_of` edges, so outcome-eval nodes are **scorer-non-counting** in v1 — the INCONCLUSIVE-as-failure mapping is therefore harmless and does not punish any persona. If a future change attaches persona/affected-system attribution, it MUST first change INCONCLUSIVE modeling (do not persist INCONCLUSIVE, or use a distinct result value the scorer excludes) before the node becomes scorer-counted.
+- **openai-compatible strict mode:** `zodToJsonSchema` does not emit `additionalProperties: false`, which OpenAI strict structured output requires. The v1 supported path is claude-cli / anthropic. Follow-up tracked.
+- **CI required-check wiring:** deferred to roadmap #540 (unbuilt CI workflow template).
+
+## Success Criteria
+
+See `docs/changes/outcome-eval/proposal.md` for the full 9 criteria. This skill satisfies SC8 (orchestrator step 6.5 + blocking halt) and SC9 (introduces no new `harness validate` findings; layer rules respected).
+
+## Examples
+
+### Example: NOT_SATISFIED with high confidence (blocks)
+
+**Input:** spec Success Criteria require `GET /api/users/:id` to return 404 with `{ error: 'User not found' }`; the diff implements the happy path only, no 404 branch; test output shows the 404 test failing.
+
+**Verdict:**
+
+```
+verdict:        NOT_SATISFIED
+confidence:     high
+judgedAgainst:  success-criteria
+authority:      blocking
+unmetCriteria:
+  - "404 path for nonexistent user is unimplemented; the failing test asserts { error: 'User not found' }."
+rationale:      "The diff adds the lookup but returns 200 with an empty body when the user is missing."
+```
+
+**Action:** HALT before Ship. Report unmet criteria; do not open the PR.
+
+### Example: partial implementation (advisory)
+
+**Input:** the diff meets most criteria; one acceptance item is ambiguous in the diff.
+
+**Verdict:** `NOT_SATISFIED confidence: medium authority: advisory` — surfaced for review, workflow proceeds.
+
+## Gates
+
+- **Authority is never read from the LLM.** The verdict's `authority` is always `deriveAuthority(verdict, 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_SATISFIED.** `authority === 'blocking'` iff `verdict === 'NOT_SATISFIED' && confidence === 'high'`. Every other combination — all `SATISFIED`, all `INCONCLUSIVE`, and every `medium`/`low` `NOT_SATISFIED` — is advisory. Do not halt the workflow on an advisory verdict.
+- **Always supply `diff` and `testOutput`.** Omitting them degrades the verdict to INCONCLUSIVE/advisory (a silent false-negative at the ship gate). Gather them from the session before invoking the tool.
+- **Never block on infrastructure noise.** A provider failure, an unparseable response, or a missing spec 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.
+- **Do not skip step 6.5.** The gate runs after Code Review and before Ship. A blocking verdict halts before step 7; it is not optional.
+
+## Escalation
+
+- **Blocking verdict the author disputes:** the resolution is to fix the implementation (or amend the spec's Success Criteria if they were wrong) and re-run outcome-eval — not to override the gate. If the spec itself is wrong, that is a spec change, reviewed on its own merits.
+- **Repeated INCONCLUSIVE on a real change:** usually means `diff`/`testOutput` were not supplied, or no judgable section exists in the spec. Confirm inputs and that 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, diff, and verdict, and route to the maintainers; do not loosen the conservative-confidence prompt ad hoc.