@harness-engineering/cli 2.8.0 → 3.0.0

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

@@ -0,0 +1,51 @@
+name: outcome-eval
+version: '0.1.0'
+description: >-
+  LLM-judgment skill that produces a structured, confidence-rated verdict on
+  whether an implementation satisfied its spec. Reads the spec's acceptance
+  section, the change diff, and test output; emits an OutcomeVerdict
+  (SATISFIED | NOT_SATISFIED | INCONCLUSIVE) with confidence, rationale, and
+  unmet criteria. Authority is derived in TypeScript, never from the LLM: a
+  high-confidence NOT_SATISFIED blocks ship; every other verdict is advisory.
+  The verdict persists as an execution_outcome node and feeds skill-effectiveness
+  baselines. The harness's first blocking post-execution spec-satisfaction gate.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+mcp:
+  tool: outcome_eval
+  # specPath, diff, and testOutput are ALL required. diff/testOutput are the
+  # evidence the judge reasons over: omitting them degrades the verdict to
+  # INCONCLUSIVE/advisory (never blocking), so the agent MUST supply them.
+  input:
+    specPath: 'string (required) — absolute or repo-relative path to the spec markdown to judge against'
+    diff: 'string (required) — unified diff of the change under judgment (git diff); omission degrades the verdict to INCONCLUSIVE/advisory'
+    testOutput: 'string (required) — captured test-runner stdout+stderr; omission degrades the verdict to INCONCLUSIVE/advisory'
+    model: 'string (optional) — model override for the outcome-eval LLM call'
+    path: 'string (optional) — project root used to resolve the knowledge graph (default cwd)'
+type: rigid
+tier: 2
+phases:
+  - name: gather
+    description: Collect the unified diff (git diff), capture test output, resolve the spec path
+    required: true
+  - name: resolve
+    description: Resolve the judgment section (Success Criteria -> User-Visible Behavior -> Overview)
+    required: true
+  - name: judge
+    description: Invoke OutcomeEvaluator.evaluate(); LLM returns verdict/confidence/rationale/unmetCriteria; authority derived in TS
+    required: true
+  - name: gate
+    description: Render the verdict; on a blocking verdict (NOT_SATISFIED + high confidence) halt before Ship
+    required: true
+state:
+  persistent: false

package/dist/agents/skills/cursor/harness-audit-harness-strength/SKILL.md

@@ -0,0 +1,188 @@
+# Harness Audit: Harness Strength
+
+> Mechanically audit whether a project's harness is load-bearing. Orchestrates the deterministic check-harness-strength engine; interprets results. Not a deep/AI review.
+
+## When to Use
+
+- On a milestone gate, to confirm the harness still constrains rather than merely decorates the project
+- When adding the strength audit as a required CI check, so the seven STRENGTH patterns block the merge instead of being prose advice
+- When validating a harness-distribution (toolkit) repo before shipping templates downstream — to catch a default that would weaken every adopter
+- When a reviewer suspects a gate "passes" without doing anything (a snapshot that asserts `passed: true` for a check it never ran)
+- NOT for deep security review — use `harness-security-review` (semantic, AI-assisted)
+- NOT for design-system drift — use `detect-design-drift`
+- NOT for reimplementing pattern detection by hand — the engine (`HarnessStrengthAuditor`) owns detection. This skill runs it and interprets the output.
+
+## Process
+
+This skill ORCHESTRATES `harness check-harness-strength`. It never re-greps configs, never re-parses hooks, and never re-derives findings. The engine reads the project once and returns a structured `AuditResult`; the skill's job is to run it with the right mode/severity and turn the JSON into an actionable report.
+
+### Phase 1: SCAN — Run the engine
+
+1. **Resolve the project root.** Use the provided `path` argument, else the current working directory.
+
+2. **Resolve the mode.**
+   - If `--toolkit` or `--adopter` (or `--mode toolkit|adopter`) is supplied, honor it. Explicit mode wins.
+   - Otherwise auto-detect: treat the repo as **toolkit** when it is a harness distribution — both `templates/` and `agents/skills/` exist at the root. Otherwise **adopter**.
+   - Do not inspect config files to "double-check" the mode. The engine resolves and reports the mode it used.
+
+3. **Invoke the command** via Bash, requesting JSON:
+
+   ```bash
+   harness check-harness-strength [--mode <adopter|toolkit>] [--severity <error|warning|info>] [--report-only] --json
+   ```
+
+   The `--json` payload is the raw structured `AuditResult` (score, tier, mode, findings with `id`, `gearPiece`, `severity`, `message`, `remediation`, and file:line evidence). Parse this — do not re-derive it.
+
+4. **Do NOT inspect config files by hand.** The engine reads `harness.config.json`, hook profiles, baselines, snapshots, and tier defaults exactly once. Hand-grepping `.husky/pre-commit` or `harness.config.json` to "confirm" a finding reimplements detection and violates the core decision behind this skill (ADR 0039 / spec D1).
+
+### Phase 2: DETECT — Interpret findings
+
+1. **Map each finding to its STRENGTH pattern** using the JSON `id` and `gearPiece` fields. Every finding the engine emits corresponds to exactly one of the seven patterns below. Do not invent findings the engine did not emit, and do not silence findings it did.
+
+2. **The seven STRENGTH patterns** (the engine's rule registry — for interpretation only; the engine, not the skill, decides which fire):
+
+   | ID           | Gear piece              | Pattern                                                              | Default |
+   | ------------ | ----------------------- | -------------------------------------------------------------------- | ------- |
+   | STRENGTH-001 | blocking-gate           | Hook documented "never blocks"/"always exits 0" in an active profile | error   |
+   | STRENGTH-002 | regression-baseline     | Pre-commit auto-updates baselines/thresholds on regression           | error   |
+   | STRENGTH-003 | skip-discipline         | `--skip` list > 2 categories without inline justification            | warning |
+   | STRENGTH-004 | architecture-thresholds | `layers` defined but `architecture.thresholds` empty/absent          | error   |
+   | STRENGTH-005 | tier-default            | Init/config defaults to lowest tier (`basic`)                        | warning |
+   | STRENGTH-006 | review-gate             | Baseline-update PR auto-approved without independent review          | error   |
+   | STRENGTH-007 | snapshot-honesty        | `passed:true` in health snapshot whose `signals[]` names that check  | error   |
+
+3. **Attach evidence.** Each finding carries a `file:line` (or config-key) reference and a remediation string from the engine. Surface them verbatim — do not paraphrase the remediation.
+
+### Phase 3: SCORE/REPORT
+
+1. **Surface the score and tier.** The engine returns a 0-100 strength score and a tier label:
+   - `solid` — score >= 85
+   - `at-risk` — score 50-84
+   - `theatre` — score < 50
+
+2. **Report format** (mirror of the security-scan report block):
+
+   ```
+   Harness Strength: [PASS/FAIL] — tier: <solid|at-risk|theatre> (score N/100, mode <adopter|toolkit>)
+   Findings: <count>  (Errors: N | Warnings: N | Info: N)
+
+   [STRENGTH-00N] <gearPiece> <file:line> (severity)
+     <message>
+     Remediation: <engine remediation string>
+   ```
+
+3. **PASS/FAIL.** FAIL if any error-severity finding survives the severity threshold, unless `--report-only` was passed (then exit softens to PASS but findings are still listed). Otherwise PASS.
+
+## Gates
+
+- **Error-severity findings are blocking.** The report is FAIL and the exit is non-zero when any error-severity finding survives filtering — unless `--report-only` was explicitly requested. Do not report PASS over an unsuppressed error finding.
+- **No reimplementation.** The skill must run `harness check-harness-strength` and interpret its JSON. It must never hand-grep hooks, hand-parse `harness.config.json`, or re-derive a score. Reimplementing detection violates ADR 0039.
+- **"Not evaluable" is not a pass.** When an input the engine needs is absent (e.g., no hook profile, no snapshot), the engine reports that state. Surface it as-is. Do not convert "could not evaluate" into "passed."
+- **Mechanical only.** No AI judgment about whether a weakness "really matters." The patterns are deterministic; the engine decides what fires.
+
+## Escalation
+
+- **Disputed finding / false positive:** Do not suppress by editing files or skipping the rule in the skill. Adjust severity via config — `audit.harnessStrength.severities` in `harness.config.json` (e.g., downgrade STRENGTH-003 to `info` for a justified wide `--skip`). Document the rationale alongside the override.
+- **Engine misses a known weakness:** This skill cannot add detection. A missing pattern is engine work — file a new `StrengthRule` (`{ id, gearPiece, defaultSeverity, appliesIn(mode), evaluable?(ctx), detect(ctx) }`) in `packages/core/src/harness-strength/`. Out of scope for the skill.
+- **Mode mis-detected:** If auto-detection picks the wrong mode (e.g., a repo with `templates/` that is not a distribution), pass `--mode adopter` (or `--toolkit`) explicitly. Do not work around it by hand-editing detection.
+- **Engine throws or the build is stale:** If `harness check-harness-strength` errors (command not found / not in the built CLI), the dist may be stale. Rebuild the CLI and re-run. Do not substitute a manual config read for the engine.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Run the engine and cite the result.
+- **"This is best practice"** — Best practice in what context? Cite the source and confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now with a concrete follow-up plan.
+
+### Domain-Specific
+
+| Rationalization                                            | Reality                                                                                                                                                       |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The config looks fine when I read it"                     | The engine exists because manual reading misses these patterns — that is the whole point of D1. Reading is not running. Run `harness check-harness-strength`. |
+| "It only warns, not errors, so it's fine"                  | A gate that warns but does not stop IS STRENGTH-001 — this is the recursion item the audit was built to catch. Do not normalize "warns but doesn't block."    |
+| "I'll re-grep the hooks myself to double-check the engine" | Reimplementing detection violates ADR 0039 / spec D1. The engine is the single source of truth — trust and interpret its output, do not shadow it.            |
+| "Score is 70, that's a passing grade"                      | 70 is `at-risk`, not `solid`. Tier labels are thresholds, not letter grades. Below 85 means the harness has load-bearing gaps.                                |
+| "No error findings, so I can skip reading the warnings"    | Warnings (STRENGTH-003, -005) are erosion signals — a `basic` tier default or an unjustified wide `--skip` weakens every future run. Surface them.            |
+
+## Success Criteria
+
+- The engine (`harness check-harness-strength`) ran and produced a score, tier label, and findings (or a clean result).
+- Every finding is interpreted against the seven-pattern table, with the engine's file:line evidence and remediation surfaced verbatim.
+- The exit code / PASS-FAIL reflects the gate (error-severity findings fail unless `--report-only`).
+- No manual config inspection was substituted for the engine — the report is derived entirely from the command's `--json` output.
+- "Not evaluable" states are surfaced as-is, never converted to passes.
+
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior, it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `.husky/pre-commit:12`) — taken from the engine's finding, not re-derived.
+2. **Code pattern reference:** `file` with description (e.g., `harness.config.json` — "architecture.layers defined, thresholds absent").
+3. **Test/command output:** Inline or referenced output from the `harness check-harness-strength --json` run.
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`.
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with `[UNVERIFIED]`. Example: `[UNVERIFIED] The pre-commit hook auto-updates baselines`.
+
+## Harness Integration
+
+- **`harness check-harness-strength`** — The CLI command this skill runs and interprets. Options: `--mode <adopter|toolkit>`, `--toolkit`/`--adopter` shortcuts, `--severity <error|warning|info>` (default `warning`), `--report-only`, `--json`.
+- **`HarnessStrengthAuditor`** — Core class from `@harness-engineering/core` that builds a `ProjectContext` once, runs the applicable `StrengthRule`s, and aggregates the score/tier/findings. The skill never instantiates it directly; it goes through the command.
+- **`harness.config.json` → `audit.harnessStrength.severities`** — Per-pattern severity overrides. The supported escalation path for false positives — never suppress by editing source.
+- **`docs/standard/article-failure-patterns.md`** — Narrative companion documenting the seven patterns (forthcoming — downstream item; may not exist yet).
+
+## Examples
+
+### Example: Clean toolkit-mode run
+
+**Input:** A harness-distribution repo (`templates/` and `agents/skills/` present), run at a milestone gate. `harness check-harness-strength --toolkit --json`.
+
+**Output:**
+
+```
+Harness Strength: PASS — tier: solid (score 100/100, mode toolkit)
+Findings: 0  (Errors: 0 | Warnings: 0 | Info: 0)
+```
+
+Every gear piece is load-bearing: no "never blocks" hook, baselines are not auto-updated on regression, architecture thresholds are set, the init default is not `basic`, baseline-update PRs require independent review, and no snapshot claims a check passed that it never ran.
+
+### Example: Findings detected (adopter mode)
+
+**Input:** An adopter repo, run with default severity. `harness check-harness-strength --json`.
+
+**Output:**
+
+```
+Harness Strength: FAIL — tier: at-risk (score 62/100, mode adopter)
+Findings: 2  (Errors: 2 | Warnings: 0 | Info: 0)
+
+[STRENGTH-001] blocking-gate .husky/pre-commit:12 (error)
+  Active pre-commit profile documents "always exits 0" — the gate reports but never blocks.
+  Remediation: Remove the unconditional `exit 0`; let failing checks return a non-zero status.
+
+[STRENGTH-004] architecture-thresholds harness.config.json (error)
+  architecture.layers is defined but architecture.thresholds is empty — layer rules cannot be enforced.
+  Remediation: Set architecture.thresholds (e.g. maxModuleLines, maxDependencyDepth) so the layer
+               definitions become enforceable, or remove the unused layers block.
+```
+
+Two error-severity findings → FAIL. STRENGTH-001 is the recursion item: a hook that runs but cannot block. Run with `--report-only` only when you explicitly want to surface findings without failing the build (e.g., a first baseline-capture run) — and never to normalize the weakness.
+
+## Skill Test Scenarios
+
+### Scenario 1: Red Flag — "I'll re-grep the hooks myself to double-check the engine"
+
+Input: The agent has the `harness check-harness-strength --json` output in hand but is about to open `.husky/pre-commit` and grep it by hand to "confirm" the STRENGTH-001 finding.
+Expected: Agent stops, cites the no-reimplementation gate (ADR 0039 / spec D1), and interprets the engine's JSON instead of hand-grepping the hook.
+
+### Scenario 2: Rationalization — "it only warns, not errors, so it's fine"
+
+Input: The engine reports a documented "never blocks" pre-commit profile, and the agent is tempted to treat it as acceptable because nothing currently fails the build.
+Expected: Agent rejects the rationalization, recognizes that "warns but doesn't stop" IS STRENGTH-001 (the recursion item), and surfaces it as a finding rather than normalizing it.
+
+### Scenario 3: Gate — error-severity STRENGTH-001 finding present without `--report-only`
+
+Input: The `--json` output contains an error-severity STRENGTH-001 finding, `--report-only` was not passed, and the agent is about to summarize the run as PASS.
+Expected: Agent halts, reports FAIL with a non-zero exit, lists the finding with its file:line evidence and remediation, and does not proceed past the gate.

package/dist/agents/skills/cursor/harness-audit-harness-strength/skill.yaml

@@ -0,0 +1,54 @@
+name: harness-audit-harness-strength
+version: '0.1.0'
+description: Mechanically audit a project's own harness setup against the seven STRENGTH failure patterns; reports per-pattern findings, a 0-100 strength score, and a tier label (solid/at-risk/theatre). Orchestrates harness check-harness-strength; never reimplements detection.
+stability: draft
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+cli:
+  command: harness skill run harness-audit-harness-strength
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: 'adopter (default) or toolkit (auto-detected in a harness-distribution repo)'
+      required: false
+    - name: severity
+      description: Minimum severity threshold (error, warning, info)
+      required: false
+    - name: report-only
+      description: Soften exit to 0 even when error-severity findings exist
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-audit-harness-strength
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Resolve mode and run harness check-harness-strength against the target repo
+    required: true
+  - name: detect
+    description: Interpret the 7 STRENGTH pattern findings with file-line evidence
+    required: true
+  - name: score_report
+    description: Surface the 0-100 score, tier label, and per-pattern remediation
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -213,6 +213,8 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 ## Process
 
+**Prompt the human in plain text** — every phase-continue and human-decision interaction in this skill is plain text only. Do not elevate to `AskUserQuestion`: natural headers like "Continue phase" exceed its 12-char cap, rendering the call as ERR.
+
 1. **INIT** — Resolve spec, derive session slug, check for existing state, parse phases.
 2. **ASSESS** — Route by complexity: low/medium auto-plans, high pauses for interactive planning.
 3. **PLAN → APPROVE** — Dispatch harness-planner, check approval signals, auto-approve or pause.

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

@@ -136,7 +136,7 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
    - **Entry Points** -- Which system entry points does this feature touch or create? (e.g., new CLI command, new MCP tool, new skill, new API route, new barrel export)
    - **Registrations Required** -- What registrations are needed for the feature to be discoverable? (e.g., barrel export regeneration, skill tier assignment, route registration)
    - **Documentation Updates** -- What docs need updating to reflect the new capability? (e.g., AGENTS.md section, API docs, README, guides)
-   - **Architectural Decisions** -- What decisions warrant ADRs? List the decision and a one-line rationale. Only for medium/large tier changes -- omit for small changes.
+   - **Architectural Decisions** -- Which decisions from the **Decisions made** section rise to a standalone ADR? Reference each by name with a one-line note on _why_ it warrants an ADR. Do **not** restate the decisions here -- this subsection points back to the canonical **Decisions made** section; duplicating them creates two sources that drift (spec-craft flags this as SPEC-R004). Only for medium/large tier changes -- "None" for small changes.
    - **Knowledge Impact** -- What domain concepts, patterns, or relationships should enter the knowledge graph?
 
    If the feature is a small change (bug fix, config tweak, < 3 files), the section may contain only Entry Points and Registrations Required with "None" for the others. The section must still be present.
@@ -186,21 +186,35 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
 
    The human must explicitly approve before this skill is complete.
 
-7. **Commit spec artifacts.** After approval, commit the spec and skill recommendations so the paper trail enters git history at sign-off rather than retroactively:
+7. **Promote the roadmap row.** If `docs/roadmap.md` exists, transition the named row to `planned` and link the spec in a single structured call (steps 7 and 8 are intentionally ordered so the commit captures the roadmap mutation). Skip silently only when no roadmap exists.
+   - Derive the lookup key from the slash-command `ARGUMENTS` string (D1). Derive the summary from the spec title (the H1 heading).
+   - Call `manage_roadmap` with action `promote`, `feature: "<ARGUMENTS>"`, `spec: "docs/changes/<feature>/proposal.md"`, and `summary: "<H1>"`.
+   - Branch on the returned `PromoteResult` envelope:
+
+     | Envelope                                    | Skill behavior                                                                                                                                                     |
+     | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+     | `ok: true, transitioned: 'backlog→planned'` | Log "Promoted `<feature>`: backlog → planned". Continue to step 8.                                                                                                 |
+     | `ok: true, transitioned: 'spec-updated'`    | Log "Updated spec link for `<feature>` (status preserved)". Continue to step 8.                                                                                    |
+     | `ok: true, transitioned: 'noop'`            | Log "No change — `<feature>` already promoted with this spec". Continue to step 8.                                                                                 |
+     | `ok: false, reason: 'in-progress'`          | **STOP.** Surface: "Refused to promote `<feature>`: an agent is currently dispatched against this row. Stop the agent or use a different feature name."            |
+     | `ok: false, reason: 'done'`                 | **STOP.** Surface: "Refused to promote `<feature>`: row is already 'done'. To revise a shipped feature, use a new name."                                           |
+     | `ok: false, reason: 'not-found'`            | If no row was expected to exist, fall through to a `created` outcome. Otherwise surface `closestMatches` as a typo hint and **STOP**.                              |
+     | `ok: false, reason: 'ambiguous'`            | **STOP.** Surface: "Refused to promote `<feature>`: matches multiple rows across milestones. Re-invoke with one of: `<matches>`." Matches are milestone-qualified. |
+     | `ok: false, reason: 'write-failed'`         | **STOP.** Surface `detail` verbatim. The brainstorm is not considered complete.                                                                                    |
+
+   - The `not-found` create path: when the row genuinely does not exist yet, call `manage_roadmap` action `add` with `status: "planned"`, `milestone: "Current Work"`, the spec path, and the H1 summary (unchanged from the legacy behavior), then continue to step 8.
+   - "STOP" cases skip step 8 (no commit) and step 9 (no handoff/transition). The spec file written in step 3 stays on disk; the user re-runs the skill after resolving the conflict.
+   - If `manage_roadmap` is unavailable, fall back to `parseRoadmap`/`promoteFeature`/`serializeRoadmap` from core. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored."
+   - If no roadmap exists, skip silently (no envelope) and continue to step 8; the commit then contains only the spec files.
+
+8. **Commit spec artifacts and roadmap promotion.** After a successful promote (or a silent skip when no roadmap exists), commit the spec, skill recommendations, and the roadmap mutation together so the promotion ships atomically with the spec:
 
    ```bash
-   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md
-   git commit -m "docs(<feature>): add spec"
+   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md docs/roadmap.md
+   git commit -m "docs(<feature>): add spec and promote to planned"
    ```
 
-   Do not skip this step. `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats either file, re-add and re-commit.
-
-8. **Add feature to roadmap.** If `docs/roadmap.md` exists:
-   - Derive feature name from the spec title (the H1 heading).
-   - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path.
-   - If the feature already exists, skip silently.
-   - If `manage_roadmap` is unavailable, fall back to `parseRoadmap`/`serializeRoadmap` from core. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored."
-   - If no roadmap exists, skip silently.
+   Include `docs/roadmap.md` in `git add` only when it exists; omit it when the project has no roadmap. Do not skip this step — `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats a file, re-add and re-commit.
 
 9. **Write handoff and suggest transition.** After approval:
 
@@ -336,8 +350,8 @@ Technical claims about existing code, architecture, or tradeoffs MUST cite evide
 - **Spec location** -- `docs/changes/<feature>/proposal.md`.
 - **Handoff** -- Once approved, invoke harness-planning to create the implementation plan.
 - **Session directory** — When session slug is known, handoff goes to `.harness/sessions/<slug>/handoff.json`. The session directory structure is: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and file lists). Do not write to `.harness/handoff.json` in session context.
-- **Spec commit** -- After sign-off (Phase 4 Step 7), commit `docs/changes/<feature>/proposal.md` and `docs/changes/<feature>/SKILLS.md` so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
-- **Roadmap sync** -- After approval, call `manage_roadmap` action `add` to register as `planned`. Skip silently if no roadmap. Duplicates ignored.
+- **Spec commit** -- After sign-off, the Phase 4 step 8 commit captures `docs/changes/<feature>/proposal.md`, `docs/changes/<feature>/SKILLS.md`, and the promoted `docs/roadmap.md` together so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
+- **Roadmap promotion** -- After approval (Phase 4 step 7), call `manage_roadmap` action `promote` to transition the named row to `planned` and link the spec atomically with the spec commit. Falls back to `add` (create new row) when the row does not exist; refuses on `in-progress`/`done`/`ambiguous`. Skip silently if no roadmap.
 - **`emit_interaction`** -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).
 
 #### Requirement Phrasing

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

@@ -56,7 +56,7 @@ When no arguments are provided (standalone invocation), discover plan from `docs
 4. **Load session summary for cold start.** If resuming (session slug known):
    - Call `listActiveSessions()` to read the session index.
    - Call `loadSessionSummary()` for the target session.
-   - If ambiguous, present the index and ask which session to resume.
+   - If ambiguous, present the index and ask which session to resume. Ask in plain text — do not elevate this to `AskUserQuestion` (the session index can exceed its 4-option cap and a natural header like "Pick session" can exceed its 12-char cap, rendering the call as ERR).
 
 5. **Check for known dead ends.** Review `learnings` tagged `[outcome:failure]`. Warn if any match current plan approaches.
 

package/dist/agents/skills/cursor/harness-git-workflow/SKILL.md

@@ -13,6 +13,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every choice and destructive confirmation in this skill (worktree location, discard-experiment, etc.) is plain text only. Do not elevate to `AskUserQuestion`: option labels like the A/B/C worktree-location choices and natural headers like "Discard commits" routinely exceed its 4-option / 12-char caps and render as ERR.
+
 ### Part A: Worktree Creation
 
 #### Step 1: Choose Worktree Location

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

@@ -15,6 +15,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every confirmation and selection in this skill (`Proceed? (y/n)`, post-critique selection, etc.) is plain text only. Do not elevate to `AskUserQuestion`: natural headers like "Confirm inputs" exceed its 12-char cap and option lists routinely exceed its 4-option cap, rendering the call as ERR.
+
 ### 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.

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-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

@@ -126,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.

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

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

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

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