@harness-engineering/cli 2.7.1 → 3.0.0

package/dist/agents/skills/cursor/harness-ideate/references/scoring.md

@@ -0,0 +1,88 @@
+# Harness Ideate — Scoring Reference
+
+Single reference consumed by Phase 4 RANK of `SKILL.md`. The skill never duplicates these numbers inline; it cites this file. Keeping the formula here lets future tweaks land in one place without rewriting every example in `SKILL.md`.
+
+## Base formula
+
+```
+base_score = (impact × confidence) ÷ effort
+```
+
+Each axis is one of `low`, `medium`, `high`, mapped to a small integer:
+
+| Token    | Numeric |
+| -------- | ------- |
+| `low`    | 1       |
+| `medium` | 2       |
+| `high`   | 3       |
+
+The mapping is the SAME for `impact`, `confidence`, and `effort`. Use it everywhere.
+
+### Worked example
+
+```
+impact:     high   (3)
+confidence: medium (2)
+effort:     medium (2)
+
+base_score = (3 × 2) ÷ 2 = 3.0
+```
+
+Range of `base_score`: `[1 × 1 ÷ 3 ≈ 0.33, 3 × 3 ÷ 1 = 9.0]`. Higher is better.
+
+## Strategy-alignment tiebreaker
+
+When `STRATEGY.md` was loaded successfully in Phase 1 GROUND, an alignment bonus is computed per candidate:
+
+```
+alignment_bonus =
+  (premise plausibly advances a Tracks bullet ? 0.5 : 0)
++ (premise/persona references Target problem or Our approach ? 0.25 : 0)
+```
+
+The maximum possible bonus is **`+0.75`** (`0.5 + 0.25`). When `STRATEGY.md` is absent or invalid, `alignment_bonus` is `0` for every candidate and this section is skipped entirely.
+
+### Bounded application
+
+The bonus is a **tiebreaker, not a multiplier**:
+
+- Compute `base_score` for every candidate.
+- Sort by `base_score` descending.
+- For each adjacent pair where `|base_score_n − base_score_{n-1}| ≤ 0.05`, apply the alignment bonus to break the tie:
+  - `final_score = base_score + alignment_bonus` for the candidate whose pair-mate is within `0.05`.
+  - The bonus is added to BOTH candidates in the tie window; the higher final score wins.
+- For pairs where `|Δbase_score| > 0.05`, the base score determines order — the bonus is recorded in the artifact for transparency but does NOT change the rank.
+
+The `0.05` threshold mirrors `harness-roadmap-pilot`'s tiebreaker contract intentionally — same bounded-tiebreaker shape, different domain (ranking ideas vs. ranking roadmap candidates). Aligning the threshold keeps users from learning two different "close enough" rules for two adjacent skills.
+
+### Anti-patterns the bonded cap rejects
+
+| Failure mode                                                                      | Why the cap rejects it                                                                                                                                                      |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| "Idea A scores 2.0, Idea B scores 5.0; B aligns with strategy, A doesn't"         | `                                                                                                                                                                           | 5.0 − 2.0 | = 3.0`, way outside the `0.05` window. No bonus applied. Base score wins. Cap protects rankings from over-fitting to strategy. |
+| "Every idea aligns; I'll add `+0.75` to all and call it ranked"                   | Bonus is only applied within tie windows. Universal alignment yields the same final ordering as the base score. The cap forces ranking to come from the base formula first. |
+| "STRATEGY.md exists but is invalid; I should still apply the bonus heuristically" | Soft-fail: `alignment_bonus = 0` for every candidate when strategy is absent OR invalid. The skill never invents alignment when it cannot read the source.                  |
+| "I'll widen the threshold to `0.5` so more ideas qualify"                         | Threshold is a constant in this file, NOT a parameter. Widening means updating this reference and re-justifying the change in an ADR (mirrors the roadmap-pilot decision).  |
+
+## Persistence — what lands in the artifact
+
+For every candidate the persisted `docs/ideation/<slug>-YYYY-MM-DD.md` records, at minimum:
+
+- `base_score` (always)
+- `alignment_bonus` (records the bonus value; `0` when strategy is absent or no signals matched)
+- `final_score` (equals `base_score + alignment_bonus` IF the bonus was applied for tiebreak; otherwise equals `base_score` — the artifact MUST note which case applies via a one-line rationale)
+- Whichever `Tracks` bullet or `Target problem` / `Our approach` phrase the alignment cited (verbatim) — citations are mandatory when `alignment_bonus > 0`
+
+The artifact's frontmatter records `ranking_formula` verbatim so a future reader reproduces the order without rerunning the skill.
+
+## Boundary with `harness-roadmap-pilot`
+
+| Aspect                  | `harness-ideate`                                                                                            | `harness-roadmap-pilot`                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| What it ranks           | Fresh candidate ideas generated in-skill                                                                    | Existing roadmap entries from `docs/roadmap.md`                         |
+| Base formula            | `(impact × confidence) ÷ effort` (1/2/3 mapping)                                                            | `position × 0.5 + dependents × 0.3 + affinity × 0.2`                    |
+| Tiebreaker threshold    | `0.05`                                                                                                      | `0.05`                                                                  |
+| Max alignment bonus     | `+0.75`                                                                                                     | `+0.75`                                                                 |
+| When STRATEGY is absent | Skip alignment entirely; rank by base score only; record `strategy_grounded: false` in artifact frontmatter | Skip alignment entirely; rank by base score only; no rationale citation |
+
+The two skills share the bounded-tiebreaker contract on purpose. If the threshold or max bonus changes in one, update both — and add an ADR explaining why.

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

@@ -0,0 +1,66 @@
+name: harness-ideate
+version: "0.1.0"
+description: Pre-brainstorm ideation phase. Generates N candidate ideas grounded in STRATEGY.md (when present), critiques each against its strongest objection, ranks by (impact × confidence) ÷ effort with a bounded strategy-alignment tiebreaker, and writes a single ranked Markdown artifact to docs/ideation/[slug]-YYYY-MM-DD.md. Produces ranked ideation — never specs, plans, or code. harness-brainstorming consumes the output.
+stability: static
+cognitive_mode: divergent-generator
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-ideate
+  args:
+    - name: focus
+      description: One-line focus argument that anchors candidate generation (e.g., "onboarding for plugin-only users"). Used as the ideation topic and slug source.
+      required: false
+    - name: count
+      description: Number of candidate ideas to generate (default 10, min 5, max 25).
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-ideate
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: ground
+    description: Read STRATEGY.md if present at repo root (grounding); read the focus argument; confirm the topic with the user.
+    required: true
+  - name: generate
+    description: Produce N candidate ideas with per-idea fields (premise, persona, complexity, key risk, impact, confidence, effort).
+    required: true
+  - name: critique
+    description: For each idea identify the strongest objection; user picks which objections to answer.
+    required: true
+  - name: rank
+    description: Score by (impact × confidence) ÷ effort using a 1/2/3 mapping for low/medium/high; apply strategy-alignment as a bounded tiebreaker bonus when STRATEGY.md is present.
+    required: true
+  - name: write
+    description: Persist the ranked artifact to docs/ideation/[slug]-YYYY-MM-DD.md (kebab-case slug ≤30 chars, 6-char hash suffix on collision).
+    required: true
+state:
+  persistent: true
+  files:
+    - docs/ideation/
+depends_on: []
+related_skills:
+  - harness-strategy
+  - harness-brainstorming
+keywords:
+  - ideation
+  - pre-brainstorm
+  - candidate-generation
+  - impact-confidence-effort
+  - strategic-anchor
+  - compound-engineering

package/dist/agents/skills/cursor/harness-knowledge-pipeline/SKILL.md

@@ -14,6 +14,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every confirmation, drift acknowledgement, and contradiction resolution in this skill is plain text only. Do not elevate to `AskUserQuestion`: source labels and finding descriptions routinely exceed its 4-option / 12-char caps, rendering the call as ERR.
+
 1. **EXTRACT:** Run code signal extractors, diagram parsers, BusinessKnowledgeIngestor, and KnowledgeLinker against the project
 2. **RECONCILE:** Build pre-extraction snapshot (current graph state) and post-extraction snapshot, then run StructuralDriftDetector
 3. **DETECT:** Partition findings by classification (new/stale/drifted/contradicting), generate gap report

package/dist/agents/skills/cursor/harness-planning/SKILL.md

@@ -294,7 +294,16 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 5. **Check failures log.** Read `.harness/failures.md`. If planned approaches match known failures, flag them.
 6. **Run soundness review.** Invoke `harness-soundness-review --mode plan` against the draft. Do not proceed until the review converges with no remaining issues.
 7. **Write the plan to `docs/changes/<topic>/plans/`.** Naming: `YYYY-MM-DD-<feature-name>-plan.md`. Resolve `<topic>` from the spec path — if the spec lives at `docs/changes/<topic>/proposal.md`, the plan goes in the sibling `plans/` directory. If the spec is not under `docs/changes/`, fall back to `docs/plans/` and flag the spec location for human review. Create directories as needed.
-8. **Write handoff.** Write to the session-scoped path when session slug is known, otherwise fall back to global path:
+8. **Commit plan artifact.** Immediately after writing the plan, commit it so the paper trail enters git history at planning time, not after execution:
+
+   ```bash
+   git add docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md
+   git commit -m "docs(<topic>): add plan"
+   ```
+
+   Use `docs/plans/` if the spec is not under `docs/changes/<topic>/`. Do not skip — `harness-execution` commits only implementation files, so a plan uncommitted here stays untracked until someone notices. If a pre-commit hook reformats the file, re-add and re-commit.
+
+9. **Write handoff.** Write to the session-scoped path when session slug is known, otherwise fall back to global path:
    - Session-scoped (preferred): `.harness/sessions/<session-slug>/handoff.json`
    - Global (fallback, **deprecated**): `.harness/handoff.json`
 
@@ -302,11 +311,11 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 
    Fields: `fromSkill`, `phase`, `summary`, `completed`, `pending`, `concerns`, `decisions`, `contextKeywords`.
 
-9. **Write session summary (if session is known).** Call `writeSessionSummary` with skill, status, plan path, keyContext, nextStep. Skip if no session slug.
+10. **Write session summary (if session is known).** Call `writeSessionSummary` with skill, status, plan path, keyContext, nextStep. Skip if no session slug.
 
-10. **Request plan sign-off:** Use `emit_interaction` (type: `confirmation`) with plan path, task count, and time estimate.
+11. **Request plan sign-off:** Use `emit_interaction` (type: `confirmation`) with plan path, task count, and time estimate.
 
-11. **Suggest transition to execution.** After approval, call `emit_interaction` with type: `transition`, `completedPhase: "planning"`, `suggestedNext: "execution"`, `requiresConfirmation: true`. Include `qualityGate` with checks: plan-written, harness-validate, observable-truths-traced, human-approved. If confirmed: invoke harness-execution. If declined: stop (handoff already written).
+12. **Suggest transition to execution.** After approval, call `emit_interaction` with type: `transition`, `completedPhase: "planning"`, `suggestedNext: "execution"`, `requiresConfirmation: true`. Include `qualityGate` with checks: plan-written, harness-validate, observable-truths-traced, human-approved. If confirmed: invoke harness-execution. If declined: stop (handoff already written).
 
 ---
 
@@ -392,6 +401,7 @@ When referencing existing code in task specs, cite evidence using `file:line` fo
 
 - **`harness validate`** — Run in Phase 4 (before writing plan) and included in every task.
 - **`harness check-deps`** — Referenced in tasks adding imports or creating modules.
+- **Plan commit** — After writing the plan (Phase 4 Step 8), commit `docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md` so the paper trail enters git history at planning time. `harness-execution` does not backfill — see issue #487.
 - **Plan location** — `docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md` when the spec lives under `docs/changes/<topic>/proposal.md`; otherwise `docs/plans/` as a fallback.
 - **Handoff** — Once approved, invoke harness-execution for task-by-task implementation.
 - **Session directory** — Session-scoped writes go to `.harness/sessions/<slug>/`. Structure: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and produced file lists). Global `.harness/handoff.json` is deprecated for session-aware invocations.

package/dist/agents/skills/cursor/harness-pulse/SKILL.md

@@ -30,7 +30,7 @@
 
 Read `references/interview.md` for the SMART pushback rules and the READ-WRITE-DB rejection rule. Both are mandatory.
 
-1. **Seed from STRATEGY.md.** Shell out to a Node one-liner that imports `seedFromStrategy` from `@harness-engineering/core`. Capture `{ name, keyMetrics, warnings }`.
+1. **Seed from STRATEGY.md.** Call `seed_pulse_from_strategy({ path: process.cwd() })` on the harness MCP server. Capture `{ name, keyMetrics, warnings }` — the server does the file read and bullet extraction internally. Fallback when the MCP server is unavailable: `node -e "import('@harness-engineering/core').then(m => console.log(JSON.stringify(m.seedFromStrategy({}))))"` — only works when `@harness-engineering/core` is resolvable from the project.
    - Surface `warnings` to the user verbatim.
    - If `name` is non-null, confirm it as the product name; otherwise prompt.
    - For each `keyMetric`, walk it through the SMART bar in step 4.
@@ -56,13 +56,9 @@ Read `references/interview.md` for the SMART pushback rules and the READ-WRITE-D
 
 9. **Confirm the assembled config.** Show the user the proposed `pulse:` block; ask for confirmation.
 
-10. **Write the config.** Shell out to a Node one-liner that imports `writePulseConfig` from `@harness-engineering/core`. Pipe the JSON through stdin so user-supplied event names, qualityDimension, and pendingMetrics never cross the shell tokenizer (quotes, backticks, `$()`, `$VAR` in user input would otherwise break the command or allow injection):
+10. **Write the config.** Call `write_pulse_config({ path: process.cwd(), config })` on the harness MCP server. The `config` argument is the assembled `PulseConfig` JSON. The MCP tool validates against `PulseConfigSchema` and refuses to touch disk on schema failure; passing the config as a JSON parameter (not through a shell) means user-supplied prose never crosses the shell tokenizer — no quoting, backtick, or `$VAR` hazard. The writer preserves all other config keys and writes `harness.config.json.bak` on first call.
 
-    ```bash
-    echo '<json-blob>' | node -e "import('@harness-engineering/core').then(m => m.writePulseConfig(JSON.parse(require('fs').readFileSync(0, 'utf-8')), { configPath: 'harness.config.json' })).catch(err => { console.error(err.message); process.exit(1); })"
-    ```
-
-    The writer preserves all other config keys and writes a `.bak`.
+    Fallback for environments without the MCP server (only works when `@harness-engineering/core` is resolvable from the project): `echo '<json-blob>' | node -e "import('@harness-engineering/core').then(m => m.writePulseConfig(JSON.parse(require('fs').readFileSync(0, 'utf-8')), { configPath: 'harness.config.json' }))"`.
 
 11. **Offer to register the `product-pulse` maintenance task.** Deferred: Phase 6 of the spec wires it. For now, surface "the daily 8am `product-pulse` task will be registered automatically once Phase 6 of the feedback-loops spec ships; you can also run pulse on demand with `/harness:pulse [window]` once Phase 4 ships."
 
@@ -80,12 +76,12 @@ Stub: when `pulse.enabled === true`, this phase will dispatch analytics/tracing/
 
 ## Harness Integration
 
-- **`harness validate`** — Run after `writePulseConfig`; the existing pulse-schema validator catches malformed blocks.
-- **`@harness-engineering/core`** primitives consumed by this skill:
-  - `writePulseConfig(config, { configPath })` — atomic config update with .bak.
-  - `seedFromStrategy({ cwd })` — defensive STRATEGY.md reader.
-  - `getPulseAdapter(name)` / `listPulseAdapters()` — adapter discovery (Phase 4 populates).
-  - `PulseConfigSchema` / `PII_FIELD_DENYLIST` — schema and PII contracts (already shipped Phase 1).
+- **`harness validate`** — Run after `write_pulse_config`; the existing pulse-schema validator catches malformed blocks.
+- **Harness MCP tools consumed by this skill** (canonical execution path — no project-local `@harness-engineering/core` required):
+  - `seed_pulse_from_strategy({ path })` — defensive STRATEGY.md reader; returns `{ name, keyMetrics, warnings }`.
+  - `write_pulse_config({ path, config })` — atomic config update with .bak. Validates against `PulseConfigSchema`.
+- **`@harness-engineering/core`** primitives the MCP tools wrap (only directly relevant when developing inside the monorepo or when the MCP server is unavailable):
+  - `writePulseConfig(config, { configPath })`, `seedFromStrategy({ cwd })`, `getPulseAdapter(name)` / `listPulseAdapters()` (Phase 4 populates), `PulseConfigSchema` / `PII_FIELD_DENYLIST`.
 - **Boundary with `harness-strategy`** — Strategy writes `STRATEGY.md`; pulse reads it to seed. Pulse never writes to `STRATEGY.md`.
 - **Boundary with `harness-observability`** — Observability designs _what_ to instrument; pulse is the read-side companion that surfaces what was instrumented.
 - **Decision 6 (read-only)** — Pulse refuses read-write DB credentials. Documented in `references/interview.md`.
@@ -106,7 +102,7 @@ Stub: when `pulse.enabled === true`, this phase will dispatch analytics/tracing/
 - Phase 0: route to Phase 1.
 - Phase 1.1: `seedFromStrategy` returns `{ name: null, keyMetrics: [], warnings: ['STRATEGY.md not found'] }`.
 - Phase 1.2-7: prompt user; collect `lookbackDefault: '24h'`, `primaryEvent: 'session_started'`, `valueEvent: 'plan_completed'`, `sources.analytics: 'posthog'` (with adapter-availability warning), `sources.db.enabled: false`.
-- Phase 1.10: `writePulseConfig` writes the block; `.bak` saved.
+- Phase 1.10: `write_pulse_config` writes the block; `.bak` saved.
 - Phase 1.12: `harness validate` passes.
 
 ### Example: STRATEGY.md present with 3 Key metrics
@@ -127,7 +123,7 @@ Stub: when `pulse.enabled === true`, this phase will dispatch analytics/tracing/
 
 - **READ-WRITE-DB rejection is non-negotiable.** No flag, no override, no "I know what I'm doing" path. Refuse and document.
 - **SMART pushback is mandatory on every proposed metric/event.** Silently accepting a vague name pollutes the corpus.
-- **`writePulseConfig` is the only sanctioned write path.** Do not hand-edit `harness.config.json`. The writer is the layer that preserves non-pulse keys and writes the .bak.
+- **`write_pulse_config` (or `writePulseConfig` when invoked directly) is the only sanctioned write path.** Do not hand-edit `harness.config.json`. The writer is the layer that preserves non-pulse keys and writes the .bak.
 - **`harness validate` must pass before exit.** A malformed `pulse:` block silently breaks the daily task once Phase 4 ships.
 
 ## Escalation
@@ -135,4 +131,4 @@ Stub: when `pulse.enabled === true`, this phase will dispatch analytics/tracing/
 - **User insists on read-write DB credentials:** Refuse. Set `sources.db.enabled: false`. Stop.
 - **Adapter not registered for a chosen provider:** Warn, record the choice, continue. The runtime gate (Phase 4) refuses to run until the adapter ships.
 - **STRATEGY.md frontmatter is malformed but H1 is present:** Use H1 as `name` and surface a warning. If neither is parseable, prompt the user.
-- **`writePulseConfig` throws:** Report the validator error verbatim. Do not retry without user fix.
+- **`write_pulse_config` returns `{ written: false, error }` (or `writePulseConfig` throws directly):** Report the validator error verbatim. Do not retry without user fix.

package/dist/agents/skills/cursor/harness-roadmap/SKILL.md

@@ -9,6 +9,7 @@
 - When adding a new feature to an existing roadmap (`--add <feature-name>`)
 - When roadmap statuses may be stale and need updating from plan execution state (`--sync`)
 - When features need reordering, moving between milestones, or blocker updates (`--edit`)
+- When the roadmap needs tidying -- completed work archived, dead `planned` rows demoted (`--groom`)
 - When user asks about project status and no roadmap exists -- suggest `--create`
 - NOT for programmatic CRUD (use `manage_roadmap` MCP tool directly)
 
@@ -20,6 +21,8 @@
 
 If the human has not seen and approved the milestone groupings and feature list, do not write the file. Present. Wait. Confirm. Then write.
 
+**Prompt the human in plain text — every `(y/n)`, "which feature?", and similar prompt in this skill is plain text only.** Do not elevate them to `AskUserQuestion`: feature lists routinely exceed its 4-option cap, and natural header choices ("Pick feature", "Remove feature") exceed its 12-char cap, causing the call to render as ERR.
+
 ---
 
 ### Command: `--create` -- Bootstrap Roadmap
@@ -428,12 +431,67 @@ Choice?
 
 ---
 
+### Command: `--groom` -- Tidy the Roadmap
+
+Keeps the roadmap manageable over time. **Milestones are themes; statuses are lifecycle stages** -- grooming enforces that separation so the backlog never decays back into an undifferentiated dump.
+
+#### Phase 1: SCAN -- Detect Untidiness
+
+1. Check if `docs/roadmap.md` exists. If missing: error and direct the user to `--create`.
+2. Run `manage_roadmap` (`action: "groom"`) in a dry-run frame, or call `checkRoadmapHealth` from `@harness-engineering/core`, to surface the four health signals:
+   - **RMH001** -- completed (`done`) features still sitting in an active milestone.
+   - **RMH002** -- `planned` rows with neither a spec nor a plan (the orchestrator cannot auto-execute these; it escalates them to a human).
+   - **RMH003** -- lifecycle catch-all milestones (`Backlog`, `Current Work`) that should not exist.
+   - **RMH004** -- active milestones that have grown past the size cap (a mini-dump).
+
+#### Phase 2: PROPOSE -- Present the Plan
+
+Show the human exactly what grooming will do, in plain text:
+
+```
+GROOM PLAN
+
+Demote to backlog (planned with no spec/plan):
+  - Feature A (Theme X)
+  - Feature B (Theme Y)
+
+Archive to docs/roadmap-archive.md (completed):
+  - Feature C (Theme X)
+
+Flagged for manual routing (not auto-changed):
+  - Intake lane has 3 items awaiting a theme
+  - "Theme Z" has 28 features (cap 25) -- consider splitting
+
+Apply? (y/n)
+```
+
+Wait for confirmation. The mechanical changes (demote, archive) are safe and automated; **draining the Intake lane into themed milestones and splitting oversized milestones are human decisions** -- propose, do not auto-apply.
+
+#### Phase 3: WRITE -- Apply
+
+1. Run `manage_roadmap` (`action: "groom"`). It demotes unactionable `planned` rows to `backlog` and moves `done` features into `docs/roadmap-archive.md` under a `Shipped` milestone, returning the list of changes.
+2. For Intake-draining or milestone-splitting the human approved, follow up with `--edit` (move features between milestones).
+
+#### Phase 4: VALIDATE -- Verify
+
+1. Run `harness validate` and confirm the `roadmapHealth` check passes (no RMH003 errors; RMH001/002/004 warnings cleared or acknowledged).
+2. Summarize:
+
+   ```
+   Groom complete.
+   Demoted: N | Archived: N -> docs/roadmap-archive.md | Flagged for manual routing: N
+   harness validate (roadmapHealth): passed
+   ```
+
+---
+
 ## Harness Integration
 
-- **`manage_roadmap` MCP tool** -- Primary read/write interface for roadmap operations. Supports `show`, `add`, `update`, `remove`, and `query` actions. Use this when MCP is available for structured CRUD.
-- **`harness validate`** -- Run after any roadmap modification to verify project health. Mandatory in the VALIDATE phase of both `--create` and `--add`.
-- **Core `parseRoadmap`/`serializeRoadmap`** -- Fallback when MCP is unavailable. These functions in `packages/core/src/roadmap/` handle parsing and serializing the roadmap markdown format directly.
-- **Roadmap file** -- Always at `docs/roadmap.md`. This is the single source of truth for the project roadmap.
+- **`manage_roadmap` MCP tool** -- Primary read/write interface for roadmap operations. Supports `show`, `add`, `update`, `remove`, `query`, `sync`, `promote`, and `groom` actions. Use this when MCP is available for structured CRUD.
+- **`harness validate`** -- Run after any roadmap modification to verify project health. Mandatory in the VALIDATE phase of `--create`, `--add`, and `--groom`. The `roadmapHealth` check enforces the maintenance rules (RMH001-RMH004) as a regression guard.
+- **Core `checkRoadmapHealth`/`groomRoadmap`** -- Maintenance engine in `packages/core/src/roadmap/health.ts`. `checkRoadmapHealth` is read-only diagnostics; `groomRoadmap` is the pure transform (demote unactionable planned, archive done). Both are surfaced via `manage_roadmap` and `harness validate`.
+- **Core `parseRoadmap`/`serializeRoadmap`** -- Fallback when MCP is unavailable. These functions in `packages/core/src/roadmap/` handle parsing and serializing the roadmap markdown format directly. Note: the serializer only preserves frontmatter, milestones, features, and the Assignment History table -- never add convention prose or comments to `docs/roadmap.md`, they are dropped on the next write.
+- **Roadmap files** -- Live work in `docs/roadmap.md` (the orchestrator's source of truth); completed work archived to `docs/roadmap-archive.md` by `--groom`. Milestones are themes, not lifecycle stages -- promoted items land in the `Intake` lane and are groomed into themes.
 
 ## Success Criteria
 

package/dist/agents/skills/cursor/harness-roadmap-pilot/SKILL.md

@@ -58,6 +58,30 @@ Top candidates (scored by position 50%, dependents 30%, affinity 20%):
    - Read the spec's Success Criteria section
    - Assess effort and impact from the spec content
 
+1a. **Read `STRATEGY.md` if present at repo root (strategy-alignment input).** Use a Node one-liner that calls `validateStrategy` from `@harness-engineering/core`, then (when valid) `parseStrategyDoc` + `asStrategyDoc`:
+
+```bash
+node -e "import('@harness-engineering/core').then(async m => {
+  const v = await m.validateStrategy(process.cwd());
+  if (!v.present || !v.valid) { console.log(JSON.stringify({ grounded: false })); return; }
+  const raw = require('fs').readFileSync('STRATEGY.md', 'utf-8');
+  console.log(JSON.stringify({ grounded: true, doc: m.asStrategyDoc(m.parseStrategyDoc(raw)) }));
+})"
+```
+
+When `grounded: true`, capture the `Target problem`, `Our approach`, and `Tracks` section bodies. For each top-3 candidate, compute a strategy-alignment score:
+
+- `+0.5` if the candidate's feature name or spec keywords plausibly advance one of the `Tracks` (case-insensitive substring or paraphrase match)
+- `+0.25` if the candidate's spec Overview cites the `Target problem` or `Our approach` verbatim or near-verbatim
+- `0` otherwise
+
+The alignment score is a **tiebreaker bonus**, NEVER a hard filter:
+
+- Apply only when the absolute difference between two candidates' base scores is `≤ 0.05` (items score similarly on `position × 0.5 + dependents × 0.3 + affinity × 0.2`).
+- Never let the bonus override a meaningful base-score difference.
+- When alignment is applied, cite it in the recommendation rationale ("Tiebreaker: aligned with track 'pulse-reports' from STRATEGY.md").
+- When `STRATEGY.md` is absent or invalid, skip this step silently; the recommendation proceeds without a strategy tiebreaker.
+
 1b. Read the most recent pulse report (if any):
 
 - List entries in `docs/pulse-reports/` and **filter to those matching the
@@ -102,6 +126,8 @@ Proceed with Feature A? (y/n/pick another)
 
 ### Phase 3: CONFIRM -- Human Decision
 
+Ask the human in plain text (matching the `y/n/pick another` example above). Do not elevate this confirmation to an `AskUserQuestion` tool call — candidate labels and natural header choices ("Pick candidate", etc.) exceed its 12-char `header` cap and the prompt is rejected as ERR.
+
 1. Wait for human confirmation.
    - If **yes**: proceed to Phase 4.
    - If **pick another**: ask which candidate number, then proceed with that pick.
@@ -166,6 +192,7 @@ Proceed with Feature A? (y/n/pick another)
 - **`scoreRoadmapCandidates`** -- Underlying file-backed scoring algorithm. Prefer `scoreRoadmapCandidatesForMode` from the skill; direct callers in file-backed-only code paths can still use this.
 - **`manage_roadmap update`** -- Used for assignment. Supports `assignee` field which delegates to `assignFeature` internally, handles history tracking, and automatically triggers external sync (GitHub Issues). In file-less mode, `manage_roadmap` dispatches through the tracker; the skill flow is unchanged.
 - **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
+- **`STRATEGY.md` alignment (Phase 2 step 1a)** -- When present at repo root and valid, loaded via `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` from `@harness-engineering/core`. Applied as a bounded tiebreaker bonus (max `+0.75`) only when candidates score within `0.05` on the base formula. Boundary: roadmap-pilot READS; `harness-strategy` WRITES. Never modify `STRATEGY.md` from this skill.
 - **`harness validate`** -- Run after assignment is written.
 
 ## Success Criteria
@@ -178,15 +205,18 @@ Proceed with Feature A? (y/n/pick another)
 6. Reassignment produces two history records (unassigned + assigned)
 7. Transition routes to brainstorming (no spec) or autopilot (spec exists)
 8. When a pulse report exists, the recommendation rationale cites pulse signal for any top-3 candidate whose area is referenced in the pulse Headlines or Followups.
-9. `harness validate` passes after all changes
+9. When `STRATEGY.md` is present and valid AND two candidates score within `0.05` on the base formula, the recommendation rationale cites strategy-alignment as the tiebreaker. The bonus never overrides a meaningful base-score difference.
+10. When `STRATEGY.md` is absent or invalid, the skill completes without error and no strategy-alignment rationale appears in the output.
+11. `harness validate` passes after all changes
 
 ## Rationalizations to Reject
 
-| Rationalization                                                                                                         | Reality                                                                                                                                 |
-| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| "The top-scored candidate is obviously correct, so I can assign it without asking the human"                            | The Iron Law: never assign or transition without the human confirming the recommendation first.                                         |
-| "Affinity data is not available so the scoring is degraded -- I should just pick the first planned item"                | Proceed without affinity scoring by zeroing out the affinity weight. Position and dependents signals still produce meaningful rankings. |
-| "The feature has no spec, but I can skip brainstorming and jump straight to planning since the summary is clear enough" | No spec routes to brainstorming, spec exists routes to autopilot. A one-line roadmap summary is not a spec.                             |
+| Rationalization                                                                                                         | Reality                                                                                                                                                                          |
+| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The top-scored candidate is obviously correct, so I can assign it without asking the human"                            | The Iron Law: never assign or transition without the human confirming the recommendation first.                                                                                  |
+| "Affinity data is not available so the scoring is degraded -- I should just pick the first planned item"                | Proceed without affinity scoring by zeroing out the affinity weight. Position and dependents signals still produce meaningful rankings.                                          |
+| "The feature has no spec, but I can skip brainstorming and jump straight to planning since the summary is clear enough" | No spec routes to brainstorming, spec exists routes to autopilot. A one-line roadmap summary is not a spec.                                                                      |
+| "STRATEGY.md exists, so I should let it override the top-scored candidate when alignment is clear"                      | The alignment bonus is bounded (max `+0.75`) and only fires when base scores are within `0.05`. It is a tiebreaker, not a hard filter — a clearly higher-scored item still wins. |
 
 ## Examples
 

package/dist/agents/skills/cursor/harness-strategy/SKILL.md

@@ -0,0 +1,152 @@
+# Harness Strategy
+
+> Repo-root strategic anchor. **Phase 2 of the strategic-anchor spec ships the skill**: a first-run interview that writes a valid `STRATEGY.md`, plus an update flow that re-interviews one section at a time with pushback against fluff, goals-as-strategy, and feature-lists-as-strategy. Downstream wiring (init, brainstorming, roadmap-pilot, ideate, knowledge graph) ships in spec Phases 3-7.
+
+## When to Use
+
+- Manually, when a project wants a durable upstream product anchor that survives across milestones and phases
+- When `STRATEGY.md` is absent and the user invokes `/harness:strategy`
+- When `STRATEGY.md` exists and the user wants to update one section (the user picks which one; nothing is auto-rewritten)
+- NOT for tactical phase tracking — that's `docs/roadmap.md` (kept deliberately separate; see proposal Decision 1)
+- NOT for generating strategy from code or commit history — strategy is a human commitment, never a derived artifact (proposal Decision 8)
+- NOT for producing specs/plans/code — those are `harness-brainstorming`'s job; this skill only writes `STRATEGY.md`
+
+## Process
+
+### Iron Law
+
+**The skill never writes `STRATEGY.md` without explicit user confirmation of the assembled doc, and never silently accepts an answer that fails a pushback rule on the FIRST round.** The 2-round cap is the _capitulation_ point, not the _bypass_ point — round 1 must always fire when a rule matches.
+
+---
+
+### Phase 0: ROUTE BY FILE STATE
+
+1. **Locate `STRATEGY.md` at repo root.** Use `path.join(process.cwd(), 'STRATEGY.md')`.
+2. **Call `validate_strategy({ path: process.cwd() })` via the harness MCP server.** It returns `{ present, valid, error? }`. The MCP server already has `@harness-engineering/core` loaded, so the project does not need it installed.
+   - **`{ present: false }`** → proceed to Phase 1 (first-run interview).
+   - **`{ present: true, valid: true }`** → proceed to Phase 2 (update run).
+   - **`{ present: true, valid: false, error }`** → surface `error` verbatim, then offer three paths via `emit_interaction` (or numbered chat options when MCP is unavailable):
+     - **a)** Fix the offending section now via the update flow → proceed to Phase 2 with the broken section pre-selected.
+     - **b)** Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run Phase 1 fresh.
+     - **c)** Exit; user repairs manually. No further action.
+
+The skill MUST NOT auto-overwrite a present-but-invalid STRATEGY.md — that's the user's prior work, even if broken. The three-path offer is the contract.
+
+---
+
+### Phase 1: FIRST-RUN INTERVIEW
+
+Read `references/interview.md` for the three pushback rules and the 2-round cap. Both are mandatory.
+
+Walk sections in **template order** — never out of order, because each section informs the next:
+
+1. **Target problem.** Open with: _"In 2-4 sentences: what is specifically broken in the world that this product addresses? Not the goal — the diagnosis."_ Capture. Apply `Fluff detection` and `Goal-as-strategy` rules.
+2. **Our approach.** Open with: _"What is your distinctive bet on how to solve the target problem? The choice you're making about HOW, not WHAT you're building."_ Apply all three rules (`Fluff`, `Goal-as-strategy`, `Feature-list-as-strategy`) — this is where feature-list answers live.
+3. **Who it's for.** Open with: _"Specific persona — who is the person, what context are they in, what alternatives are they currently using? 'Developers' is not a specific persona."_ Apply `Fluff detection`.
+4. **Key metrics.** Open with: _"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>`."_ Apply `Fluff detection` per bullet.
+5. **Tracks.** Open with: _"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>`."_ Apply `Feature-list-as-strategy` per bullet (a "track" should be an investment direction, not a feature name).
+6. **Optional sections.** Ask once whether to add `Milestones`, `Not working on`, and/or `Marketing`. If yes, walk each with the same rules. If no, skip — they remain absent (the schema allows omission).
+7. **Assemble.** Show the full proposed doc. Ask explicitly: _"Write this to STRATEGY.md?"_ Wait for yes/no.
+8. **Write.** Call `write_strategy({ path: process.cwd(), doc })` via the harness MCP server. The `doc` argument is the assembled `StrategyDoc` shape: `{ frontmatter: { name, last_updated, version }, sections: [{ name, body }, ...] }`. Set `last_updated` to today's ISO date; `version` to `1` for first run. The MCP tool validates against `StrategyDocSchema` and refuses to touch disk on schema failure. Passing the doc as a JSON parameter (not through a shell) means user-supplied prose never crosses the shell tokenizer — no quoting, backtick, or `$VAR` hazard. Fallback for environments without the MCP server: shell out to `node -e "import('@harness-engineering/core').then(m => m.writeStrategyDoc(JSON.parse(require('fs').readFileSync(0, 'utf-8')), { cwd: process.cwd() }))"` with the doc piped on stdin — but only when `@harness-engineering/core` is resolvable from the project's `node_modules`.
+
+9. **Validate.** Run `harness validate` to confirm the file passes `StrategyDocSchema`. On failure, surface the error and stop (do not retry).
+
+---
+
+### Phase 2: UPDATE RUN
+
+1. **Re-read the existing file** via `read_strategy({ path: process.cwd() })` on the harness MCP server. It returns `{ present: true, valid: true, doc }` with the parsed `StrategyDoc` shape; the server runs `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` internally so the project does not need `@harness-engineering/core` installed.
+2. **Summarize current state** in 3-5 lines: frontmatter (`name`, `last_updated`, `version`), then the first sentence of each present section. This is the "what's there now" view the user needs to choose what to revisit.
+3. **Ask which section to revisit.** Present the section names as numbered options. Allow `none` (exit) or `multiple` (sequential re-interviews).
+4. **Re-interview each selected section** with the same pushback rules and 2-round cap from Phase 1. Do not re-ask sections the user did not select.
+5. **Bump frontmatter.** Set `last_updated` to today's ISO date. Increment `version` by 1.
+6. **Confirm and write.** Show the diff between the parsed doc and the new doc (added/changed sections). Ask explicitly: _"Write the update?"_ Wait for yes/no. Call `write_strategy` (same pattern as Phase 1.8). The writer preserves the user's H1 line and writes a `.bak` only if no `.bak` exists yet (idempotent — the original pre-strategy file is the rollback target).
+7. **Validate.** Run `harness validate`.
+
+---
+
+### Phase 3: DOWNSTREAM HANDOFF
+
+After Phase 1 or Phase 2 completes successfully, print this short note (3-5 lines):
+
+```
+STRATEGY.md written. Downstream skills that pick this up as grounding:
+  - harness-brainstorming     (Phase 5 of strategic-anchor spec — reads STRATEGY.md in Phase 1 EXPLORE)
+  - harness-ideate            (Phase 4 of spec — generates ranked candidates grounded in STRATEGY.md)
+  - harness-roadmap-pilot     (Phase 6 of spec — strategy-alignment tiebreaker)
+  - BusinessKnowledgeIngestor (Phase 7 of spec — strategy domain → business_fact nodes)
+Soft-fail when absent; no downstream skill blocks on STRATEGY.md's presence.
+```
+
+The handoff exists to set the user's expectation about _why_ they just answered those questions. It is short by design — this is not a section to grow.
+
+## Harness Integration
+
+- **`harness validate`** — Run after `write_strategy`; the existing `validateStrategy` helper (Phase 1 of this spec) catches schema violations.
+- **Harness MCP tools consumed by this skill** (canonical execution path — works without `@harness-engineering/core` in the project's `node_modules`):
+  - `validate_strategy({ path })` — Phase 0's routing oracle. Returns `{ present, valid, error? }`.
+  - `read_strategy({ path })` — Phase 2's read path. Returns `{ present, valid, doc?, error? }`.
+  - `write_strategy({ path, doc, skipBackup? })` — atomic disk write with `.bak` on first overwrite. Validates against `StrategyDocSchema` before touching disk.
+- **`@harness-engineering/core`** primitives the MCP tools wrap (only directly relevant when developing inside the monorepo or when the MCP server is unavailable):
+  - `validateStrategy(cwd)`, `parseStrategyDoc(raw)` + `asStrategyDoc(parsed)`, `writeStrategyDoc(doc, { cwd, skipBackup? })`, `serializeStrategyDoc(doc, opts?)`, `StrategyDocSchema`.
+- **Boundary with `harness-pulse`** — Pulse reads `STRATEGY.md` to seed metric names; strategy writes it. Pulse NEVER writes to `STRATEGY.md` (Decision 6 of the feedback-loops spec). Strategy NEVER touches `harness.config.json`.
+- **Boundary with `harness-brainstorming`** — Brainstorming consumes `STRATEGY.md` as grounding context; this skill produces it. Phase 5 of the strategic-anchor spec wires the brainstorming read path.
+- **Decision 1 (separation from roadmap.md)** — `docs/roadmap.md` is tactical phase tracking; `STRATEGY.md` is the strategic anchor. They never merge. Documented in `references/interview.md`.
+- **Decision 2 (placeholder rejection)** — A STRATEGY.md with the template placeholder text (e.g., `<2-4 sentences. ...>`) still in it FAILS validation. The skill never writes placeholder text; the writer validates before touching disk.
+
+## Success Criteria
+
+- On a project with no `STRATEGY.md`, the first-run interview produces a valid `STRATEGY.md` ≤ 100 lines that passes `harness validate`.
+- Re-running the skill on a project with a valid `STRATEGY.md` enters Phase 2 (update), preserves sections the user did not touch verbatim, bumps `version`, and updates `last_updated`.
+- All three pushback rules (`Fluff detection`, `Goal-as-strategy`, `Feature-list-as-strategy`) fire on at least one canonical anti-pattern fixture in `references/interview.md`.
+- After Phase 1 or 2, `harness validate` passes.
+- A `STRATEGY.md.bak` is written on the _first_ overwrite of an existing file, but NOT clobbered on subsequent overwrites (idempotency).
+- A present-but-invalid STRATEGY.md surfaces the validation error and offers the three repair paths from Phase 0; the skill never auto-overwrites a present-but-invalid file.
+
+## Examples
+
+### Example: greenfield (no STRATEGY.md)
+
+- Phase 0: `validate_strategy` returns `{ present: false, valid: true }`; route to Phase 1.
+- Phase 1.1: ask Target problem. User answers `"engineering teams want to be the best at shipping"`. **Fluff detection** fires: "be the best at" is empty-modifier vocabulary. Repair suggestion: "Replace `be the best at shipping` with a concrete diagnosis." User revises: `"engineering teams ship without a strategic anchor; brainstorming starts mid-stream"`. Accepted.
+- Phase 1.2-5: walk Our approach, Who it's for, Key metrics, Tracks with the same pushback discipline.
+- Phase 1.6: user declines optional sections.
+- Phase 1.7: show full doc; user confirms.
+- Phase 1.8: `write_strategy` writes the file; no `.bak` written (fresh create).
+- Phase 1.9: `harness validate` passes.
+- Phase 3: handoff note printed.
+
+### Example: update existing STRATEGY.md (one section)
+
+- Phase 0: `validate_strategy` returns `{ present: true, valid: true }`; route to Phase 2.
+- Phase 2.1-2: parse and summarize. Current state shows `name: Acme, last_updated: 2026-05-01, version: 3` and 5 required sections.
+- Phase 2.3: user selects `Tracks` for revisit.
+- Phase 2.4: re-interview Tracks. User answers `"add features X, Y, Z to the dashboard"`. **Feature-list-as-strategy** fires: 3+ feature names. Repair suggestion: "What's the coherent action these features are instances of?" User revises: `"- Dashboard track: collapse 3 separate widgets into one explorable surface"`. Accepted.
+- Phase 2.5: frontmatter bumped to `last_updated: 2026-06-02, version: 4`.
+- Phase 2.6: show diff; user confirms. `write_strategy` writes the file; `.bak` already exists from a prior overwrite — NOT clobbered.
+- Phase 2.7: `harness validate` passes.
+
+### Example: present-but-invalid STRATEGY.md
+
+- Phase 0: `validate_strategy` returns an error like `section "Key metrics": unfilled template placeholder detected (- <metric 1>: <how it's measured, where it lives>)`. Surface verbatim.
+- User picks **a) Fix now**: skill enters Phase 2 with `Key metrics` pre-selected. User answers; skill writes the file.
+
+### Example: pushback gives up after the cap
+
+- Phase 1.1: ask Target problem. User answers `"deliver value"`. **Fluff detection** fires. Round 1: suggest repair. User answers `"deliver maximum value"`. Round 2: suggest repair again. User answers `"deliver excellent value"`. **Cap reached** — skill captures the answer verbatim AND emits a flag in the doc summary: `"⚠ Target problem: flagged for revisit — pushback cap reached without concrete diagnosis."` Continue to the next section.
+
+## Gates
+
+- **The 2-round pushback cap is non-negotiable.** No flag, no override, no "I know what I'm doing" path — the cap is the disable mechanism (proposal §Risks).
+- **The skill MUST NEVER write to `STRATEGY.md` without explicit user confirmation** of the assembled or updated doc.
+- **`write_strategy` (or `writeStrategyDoc` when invoked directly) is the only sanctioned write path.** Do not hand-edit `STRATEGY.md`. The writer is the layer that validates against the schema, preserves the H1, writes the `.bak`, and does the atomic rename.
+- **`harness validate` must pass before exit** of Phase 1 or Phase 2. A malformed STRATEGY.md silently breaks the downstream grounding reads (Phases 5/6/7 of the spec).
+- **Round 1 pushback MUST always fire when a rule matches.** The cap protects users from infinite loops, not from feedback. Skipping round 1 violates the Iron Law.
+
+## Escalation
+
+- **User insists pushback is wrong:** Capture the answer verbatim after round 1 (do not push back twice if the user explicitly disagrees with round 1). Surface a one-line flag in the doc summary. Continue.
+- **`write_strategy` returns `{ written: false, error }` (or `writeStrategyDoc` throws a schema error directly):** Report the error verbatim. Do not retry without user fix. The most common cause is a section body that's empty or still contains template placeholder text.
+- **STRATEGY.md frontmatter is malformed (Phase 2):** Treat as present-but-invalid; route through Phase 0's three-path offer.
+- **User wants to add a section name not in the documented schema:** Refuse and cite Decision 2 of the proposal ("schema validation rejects unknown sections; expansion requires a separate ADR"). Offer to file the proposal ADR as a follow-up.
+- **Atomic rename fails (e.g., permission denied):** Surface the filesystem error verbatim. The temp file is cleaned up by the writer; no partial STRATEGY.md is left behind.