@harness-engineering/cli 2.7.0 → 2.8.0

package/dist/agents/skills/claude-code/harness-ideate/SKILL.md

@@ -0,0 +1,277 @@
+# Harness Ideate
+
+> Pre-brainstorm ideation. Generates candidate ideas, critiques each against its strongest objection, and ranks them by `(impact × confidence) ÷ effort`. Writes a single ranked artifact to `docs/ideation/<slug>-YYYY-MM-DD.md`. **Produces ranked ideation, not specs** — brainstorming consumes the output.
+
+## When to Use
+
+- Before brainstorming, when the feature to design has not yet been selected
+- When the user asks "what should we build next in area X?" and there are several plausible answers
+- When a single domain (auth, pulse reports, onboarding…) has 5–10 candidate ideas worth comparing
+- After updating `STRATEGY.md` and wanting to surface candidates aligned with the new tracks
+- NOT when the feature is already selected — go straight to `harness-brainstorming`
+- NOT for ranking existing roadmap items — that is `harness-roadmap-pilot`'s job
+- NOT for generating specs, plans, or code — this skill writes one ideation artifact and stops
+- NOT for refreshing `STRATEGY.md` — that is `harness-strategy`'s job
+
+## Process
+
+### Iron Law
+
+**The skill produces exactly ONE ranked artifact per run, at `docs/ideation/<slug>-YYYY-MM-DD.md`, and NEVER produces a spec, plan, ADR, or code.** If the user wants a spec from a ranked idea, they invoke `harness-brainstorming` next — that is the contract.
+
+---
+
+### Phase 1: GROUND — Read STRATEGY.md and Confirm the Topic
+
+1. **Resolve the focus argument.** If the user passed `--focus` (or supplied a one-line topic in the conversation), use it verbatim. Otherwise ask:
+
+   ```
+   What is the ideation topic? One short line (e.g., "onboarding for plugin-only users",
+   "lateral review depth", "pulse-report follow-up routing").
+   ```
+
+   Capture the answer; do not proceed without one.
+
+2. **Resolve the count.** Default to 10 if `--count` is unset. Clamp silently to `[5, 25]` (`<5` is too few to rank meaningfully; `>25` loses signal). Proceed with the clamped value.
+
+3. **Read `STRATEGY.md` (grounding).** Call `read_strategy({ path: process.cwd() })` on the harness MCP server — it returns `{ present, valid, doc?, error? }` and runs validation + parsing inside the server so the project does not need `@harness-engineering/core` installed.
+
+   Three cases:
+   - **`{ present: false }`:** print one line — `STRATEGY.md not present — ranking will use impact × confidence ÷ effort only; no strategy-alignment tiebreaker`. Continue.
+   - **`{ present: true, valid: true, doc }`:** capture `doc.sections` for `Target problem`, `Our approach`, `Who it's for`, and `Tracks`. These four sections drive the strategy-alignment tiebreaker in Phase 4.
+   - **`{ present: true, valid: false, error }`:** print `error` verbatim and continue without strategy grounding. Do NOT block; this skill is not the place to repair `STRATEGY.md`. Suggest `/harness:strategy` as a follow-up.
+
+   Fallback for environments without the MCP server: `node -e "import('@harness-engineering/core').then(m => m.validateStrategy(process.cwd()).then(r => console.log(JSON.stringify(r))))"` — only works when `@harness-engineering/core` is resolvable from the project's `node_modules`.
+
+4. **Confirm the topic.** Before generating, surface a 2-line summary:
+
+   ```
+   Topic: <focus>
+   Count: <N>
+   Strategy grounding: <enabled|disabled — reason>
+   ```
+
+   Ask: `Proceed with these inputs? (y/n)`. Wait for confirmation.
+
+---
+
+### Phase 2: GENERATE — Produce Candidate Ideas
+
+Generate exactly N candidate ideas. Each idea is a structured object with the following fields:
+
+| Field        | Type                    | Description                                                                                                              |
+| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `premise`    | string (1 sentence)     | What this idea is, in one declarative sentence. Not aspirational — what the change IS, not what we hope it achieves.     |
+| `persona`    | string (1 sentence)     | Target persona segment (specific, not "developers"). If STRATEGY.md is present, prefer phrasing from its `Who it's for`. |
+| `complexity` | `low \| medium \| high` | Rough engineering complexity estimate.                                                                                   |
+| `key_risk`   | string (1 sentence)     | The single biggest reason this idea might fail or not be worth doing. Used in Phase 3 as the seed for critique.          |
+| `impact`     | `low \| medium \| high` | How much this matters if it works. Mapped to `1/2/3` for ranking.                                                        |
+| `confidence` | `low \| medium \| high` | How confident we are that we can pull it off. Mapped to `1/2/3` for ranking.                                             |
+| `effort`     | `low \| medium \| high` | Engineering effort to deliver. Mapped to `1/2/3` for ranking.                                                            |
+
+**Generation rules:**
+
+- **Spread the complexity surface.** Aim for at least one `low` and one `high` complexity idea; resist clustering everything as `medium`.
+- **Resist near-duplicates.** Two ideas with the same `premise` are one idea. If two ideas only differ by a parameter ("X for web" vs "X for mobile"), collapse them into a single idea with a parametric premise.
+- **Be honest about effort.** A `low`-effort idea must be plausibly implementable in <1 sprint by one engineer. If you find yourself defaulting everything to `medium`, slow down and re-estimate one extreme.
+- **When STRATEGY.md is present**, at least 60% of ideas should plausibly serve a current track in `Tracks`. Stretch ideas outside the tracks are allowed and useful, but the majority anchors in.
+
+Present the N candidates as a numbered list. Each line is 2-3 sentences max:
+
+```
+1. [Premise]. Persona: [...]. Complexity: medium. Key risk: [...]. Impact/Confidence/Effort: M/M/L.
+2. [Premise]. Persona: [...]. Complexity: low.    Key risk: [...]. Impact/Confidence/Effort: H/L/L.
+...
+```
+
+---
+
+### Phase 3: CRITIQUE — Identify and Address Strongest Objections
+
+For each candidate, surface the **single strongest objection** — the best argument against doing this idea. The seed is `key_risk` from Phase 2, but the critique should sharpen it (one paragraph, not one sentence):
+
+```
+Idea 3: [Premise].
+  Strongest objection: [...]. Most likely failure mode: [...]. What would need to be true
+  for this objection to NOT hold: [...].
+```
+
+After all N critiques are presented, ask the user:
+
+```
+Which objections do you want to answer (vs. accept as a downside)?
+Options:
+  - all   — I'll address every objection
+  - none  — accept all critiques as known downsides
+  - <list of numbers, e.g., "1, 3, 7">
+```
+
+For each idea the user elects to answer, ask: `For idea N, what makes the objection wrong or addressable?` Capture the user's one-paragraph answer. If the user cannot answer convincingly, leave the objection standing (this is a signal — it lowers the idea's ranking).
+
+Critique answers do NOT change the impact/confidence/effort scores from Phase 2. They feed into the rationale shown alongside each ranked idea in Phase 5.
+
+---
+
+### Phase 4: RANK — Score and Order
+
+For each candidate, compute `base_score = (impact × confidence) ÷ effort` using the `low|medium|high → 1|2|3` mapping documented in `references/scoring.md`. Higher is better; range is `[≈0.33, 9.0]`.
+
+**Strategy-alignment tiebreaker.** When `STRATEGY.md` was grounded in Phase 1, compute an alignment bonus per candidate:
+
+```
+alignment_bonus =
+  (premise plausibly advances a Tracks bullet ? 0.5 : 0)
++ (premise/persona references Target problem or Our approach ? 0.25 : 0)
+```
+
+Maximum bonus `+0.75`. The bonus is **bounded**: it is applied only when the absolute difference between two adjacent candidates' base scores is `≤ 0.05`. Outside that tie window, the base score wins and the bonus is recorded for transparency but does NOT change rank order. See `references/scoring.md` for the full contract (including the worked example and the boundary with `harness-roadmap-pilot`'s identical tiebreaker shape).
+
+Sort by final score descending. Stable on ties (preserve generation order so the user can find the original list).
+
+---
+
+### Phase 5: WRITE — Persist the Ranked Artifact
+
+1. **Compute the slug.** Kebab-case the focus argument; lowercase; collapse whitespace and `[^a-z0-9-]` into `-`; trim leading/trailing `-`; truncate to **≤30 characters**. Example: `"onboarding for plugin-only users"` → `onboarding-for-plugin-only-use`.
+
+2. **Compute today's date** as `YYYY-MM-DD` (UTC).
+
+3. **Compute the output path.** `docs/ideation/<slug>-<YYYY-MM-DD>.md`. If that path already exists (same focus, same day), append a 6-character lowercase hex suffix derived from `sha1(focus + iso_timestamp).slice(0, 6)`:
+
+   ```
+   docs/ideation/onboarding-for-plugin-only-use-2026-06-02.md         # first run
+   docs/ideation/onboarding-for-plugin-only-use-2026-06-02-a3f9b2.md  # collision
+   ```
+
+4. **Render the artifact.** Frontmatter + ranked list. See ranking math in `references/scoring.md`. Required fields:
+
+   ```markdown
+   ---
+   topic: <focus argument verbatim>
+   generated_at: <ISO 8601 timestamp>
+   strategy_grounded: <true | false>
+   strategy_path: <STRATEGY.md path if grounded, else null>
+   count_requested: <N>
+   count_generated: <N>
+   ranking_formula: '(impact × confidence) ÷ effort; strategy-alignment tiebreaker (max +0.75) applied only when |Δbase_score| ≤ 0.05'
+   ---
+
+   # Ideation: <focus>
+
+   ## Inputs
+
+   - Topic: <focus>
+   - Generated: <ISO timestamp>
+   - Strategy grounding: <enabled | disabled with one-line reason>
+
+   ## Ranked candidates
+
+   ### 1. <premise> — score: <final>
+
+   - Persona: <...>
+   - Complexity: <low|medium|high>
+   - Impact / Confidence / Effort: <H/M/L> — base score <X.XX>
+   - Strategy alignment: <none | +0.25 persona | +0.5 track:<name>> — final score <Y.YY>
+   - Strongest objection: <one paragraph>
+   - Objection answered: <yes/no — if yes, one paragraph rebuttal>
+
+   ### 2. ...
+   ```
+
+5. **Write the file.** Create `docs/ideation/` if it does not exist. Write via the standard `Write` tool — no Node one-liner is required here; the content is generated by the skill, not user-supplied prose with shell-escape hazards.
+
+6. **Print the handoff.** Three lines:
+
+   ```
+   Ideation artifact written: docs/ideation/<slug>-<date>.md
+   Top pick: <#1 premise> — score <Y.YY>
+   Next: invoke /harness:brainstorming <feature> to take a candidate into a spec, OR /harness:roadmap to enqueue picks for later.
+   ```
+
+---
+
+## Harness Integration
+
+- **Harness MCP tools consumed by this skill** (canonical execution path — no project-local `@harness-engineering/core` required):
+  - `read_strategy({ path })` — Phase 1 grounding oracle. Returns `{ present, valid, doc?, error? }` (the server runs `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` internally).
+- **`@harness-engineering/core`** (only directly relevant when the MCP server is unavailable):
+  - `validateStrategy(cwd)`, `parseStrategyDoc(raw)` + `asStrategyDoc(parsed)`, `StrategyDocSchema`, `REQUIRED_STRATEGY_SECTIONS`.
+- **Boundary with `harness-strategy`** — strategy WRITES `STRATEGY.md`; ideate READS it. Ideate never modifies `STRATEGY.md` and never offers to repair an invalid one (suggest `/harness:strategy` and continue without grounding).
+- **Boundary with `harness-brainstorming`** — ideate produces a ranked artifact at `docs/ideation/`; brainstorming produces a spec at `docs/changes/<feature>/proposal.md`. They have non-overlapping output locations (Decision 5 of the strategic-anchor proposal). Ideate's artifact may be cited as an input in a brainstorming spec; brainstorming's spec is NEVER auto-derived from ideate's artifact.
+- **Boundary with `harness-roadmap-pilot`** — ideate generates fresh candidates; roadmap-pilot prioritizes existing roadmap entries. If a user wants ranking-only over the existing roadmap, that is roadmap-pilot, not ideate.
+
+## Success Criteria
+
+- Exactly one artifact is written per run, at `docs/ideation/<slug>-<YYYY-MM-DD>.md`. No spec, plan, ADR, or code is produced.
+- The artifact contains exactly the number of candidates the user requested (after clamping to `[5, 25]`).
+- Every candidate has all 7 fields populated (premise, persona, complexity, key_risk, impact, confidence, effort).
+- Each candidate has a strongest-objection paragraph; objections the user elected to answer have a rebuttal paragraph.
+- Ranking is by `(impact × confidence) ÷ effort` with the 1/2/3 mapping. Strategy-alignment bonus is applied only when STRATEGY.md is present AND the absolute base-score delta is ≤ 0.05.
+- When `STRATEGY.md` is absent or invalid, the skill completes without error and the artifact's frontmatter records `strategy_grounded: false`.
+- The output filename collision rule (6-char hex suffix on same-day re-run for the same focus) produces a stable, deterministic suffix from `sha1(focus + iso_timestamp)`.
+- The artifact's frontmatter explicitly states the ranking formula so a future reader can reproduce the order.
+
+## Examples
+
+### Example: With STRATEGY.md (grounded, 10 candidates)
+
+```
+User: /harness:ideate --focus "pulse-report follow-up routing"
+
+Phase 1:
+  Topic confirmed: "pulse-report follow-up routing"
+  Count: 10
+  STRATEGY.md detected — grounding enabled.
+  Tracks read: ["pulse-reports", "compound-engineering", "feedback-loops"]
+  Who-it's-for read: "engineering teams adopting harness"
+
+Phase 2 (excerpt):
+  1. Auto-assign followups to the on-call rotation. Persona: on-call engineer.
+     Complexity: medium. Key risk: rotation data may be stale. I/C/E: H/M/M.
+  ...
+  10. Email-digest weekly pulse for distributed teams. Persona: async-first eng.
+     Complexity: low. Key risk: duplicates Slack. I/C/E: M/L/L.
+
+Phase 3:
+  User selects "answer 1, 4, 7"; provides three one-paragraph rebuttals.
+
+Phase 4 (ranking, excerpt):
+  - Idea 1 base score: (H=3 × M=2) ÷ M=2 = 3.00
+    Idea 7 base score: 2.97 (|Δ| = 0.03 ≤ 0.05 — alignment window applies)
+    Idea 1 alignment: track match "pulse-reports" (+0.5) + persona match (+0.25) = +0.75 → final 3.75
+    Idea 7 alignment: track match "feedback-loops" (+0.5) → final 3.47
+    Idea 4 base score: 2.50 (|Δ vs idea 1| = 0.50 > 0.05 — alignment recorded but not applied)
+
+Phase 5:
+  Write docs/ideation/pulse-report-follow-up-routin-2026-06-02.md
+  Top pick: "Auto-assign followups to the on-call rotation" — score 3.50
+  Next: invoke /harness:brainstorming "Pulse Followup Routing" to take this into a spec.
+```
+
+### Example: Without STRATEGY.md (no grounding, 5 candidates)
+
+- Phase 1: `read_strategy` returns `{ present: false }`. Strategy grounding disabled; skill prints the one-line note and continues.
+- Phase 2: 5 candidates generated. No track-alignment guidance applies; coverage of complexity surface remains a rule.
+- Phase 4: ranking uses `(impact × confidence) ÷ effort` only. No tiebreaker bonus is added.
+- Phase 5: artifact frontmatter has `strategy_grounded: false` and `strategy_path: null`. Handoff still routes the user to brainstorming.
+
+### Example: Slug collision (same focus, same day)
+
+- Run 1: writes `docs/ideation/onboarding-for-plugin-only-use-2026-06-02.md`.
+- Run 2 (same `--focus`, same day): destination collides. Skill computes `sha1("onboarding for plugin-only users" + "2026-06-02T15:21:04Z").slice(0,6)` → `a3f9b2`. Writes `docs/ideation/onboarding-for-plugin-only-use-2026-06-02-a3f9b2.md`. Both files coexist.
+
+## Gates
+
+- **One artifact per run, exactly.** A second write on the same run violates the Iron Law.
+- **Never modify `STRATEGY.md`.** Even on present-but-invalid: surface the error and continue without grounding. Repair is `/harness:strategy`'s job.
+- **Never derive a spec from ideate's artifact automatically.** Brainstorming is human-confirmed; ideate's output is an INPUT to brainstorming, not a replacement.
+- **Never produce 0 ideas.** Clamping enforces `N ≥ 5`. If the model would generate near-duplicates to reach N, prefer fewer-but-distinct over more-but-redundant — re-prompt within the skill to diversify.
+- **The strategy-alignment tiebreaker is bounded.** Maximum bonus is `+0.75` (`0.5 + 0.25`) and only applies when `|Δbase_score| ≤ 0.05`. The bonus must NEVER override a clear base-score winner.
+
+## Escalation
+
+- **User wants the artifact converted to a spec automatically.** Refuse; cite the Iron Law. Offer `/harness:brainstorming "<top-pick title>"` as the next step.
+- **STRATEGY.md is present but invalid.** Print the validation error verbatim; do not block. Suggest `/harness:strategy` and continue with `strategy_grounded: false`.
+- **User insists on `N > 25`.** Clamp to 25 and inform; offer to chain a second run with a different focus argument.
+- **User insists every idea is `medium` on all three axes.** Push back once: "If everything is medium, ranking is uninformative — what is your highest-impact vs. highest-confidence outlier?" If they decline to differentiate, write the artifact anyway with a frontmatter `quality_flag: undifferentiated` note.
+- **Output directory cannot be created.** Surface the filesystem error verbatim. Do not silently write to a fallback path.

package/dist/agents/skills/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/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
@@ -166,6 +190,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 +203,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