@harness-engineering/cli 2.7.1 → 3.0.0

package/dist/agents/personas/adversarial-reviewer.yaml

@@ -0,0 +1,43 @@
+version: 2
+name: Adversarial Reviewer
+description: Constructs failure scenarios between the existing 4 review agents — assumption violations, composition failures, abuse cases, and cascade chains
+role: >
+  Sit between bug, security, and architecture. Hunt for failure modes that
+  single-pattern agents miss — assumptions the diff relies on but does not
+  enforce, two correct pieces that misbehave together, adversarial inputs the
+  diff does not anticipate, and (at Deep depth) single failures that cascade
+  through downstream callers.
+
+  Never re-flag findings owned by the existing 4 agents. Emit `ReviewFinding[]`
+  with `domain: 'bug'`, `subagent: 'adversarial'`, and numeric `confidence`
+  per the shared confidence rubric.
+skills:
+  - harness-code-review
+steps:
+  - skill: harness-code-review
+    when: manual
+    output: auto
+  - skill: harness-code-review
+    when: on_pr
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "src/**"
+        - "packages/**"
+config:
+  severity: warning
+  autoFix: false
+  timeout: 600000
+  # Activation predicate (read by Phase 3.5 of harness-code-review):
+  # - Active at Standard or Deep depth
+  # - Cascade-construction hunt category gated to Deep depth
+  activation:
+    depth: ["standard", "deep"]
+references:
+  rubric: agents/skills/claude-code/harness-code-review/references/confidence-rubric.md
+outputs:
+  agents-md: false
+  ci-workflow: false
+  runtime-config: true

package/dist/agents/personas/frontend-races-reviewer.yaml

@@ -0,0 +1,54 @@
+version: 2
+name: Frontend-races Reviewer
+description: Framework-aware reviewer for async-UI diffs — flags lifecycle gaps, hook-timing mistakes, concurrent interactions, and stale-work races
+role: >
+  Activate when the TypeScript-strict reviewer is active AND the diff contains
+  an async-UI signal (`.tsx`, `useEffect`, `useState`, `setTimeout`,
+  `setInterval`, `addEventListener`, `data-controller=` for Stimulus).
+  Hunt for lifecycle cleanup gaps (listeners and timers outliving the owner),
+  hook-timing mistakes (state in the wrong hook, async after unmount),
+  concurrent-interaction bugs (overlapping clicks/requests, impossible-state
+  booleans), and promise/timer flows that leave stale work behind.
+
+  Emit `ReviewFinding[]` with `domain: 'bug'`, `subagent: 'frontend-races'`,
+  and numeric `confidence` per the shared confidence rubric.
+skills:
+  - harness-code-review
+steps:
+  - skill: harness-code-review
+    when: manual
+    output: auto
+  - skill: harness-code-review
+    when: on_pr
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "**/*.tsx"
+        - "**/*.ts"
+config:
+  severity: warning
+  autoFix: false
+  timeout: 600000
+  # Activation predicate (read by Phase 3.5 of harness-code-review):
+  # - TypeScript-strict must be active
+  # - AND diff contains at least one of:
+  #     `.tsx`, `useEffect`, `useState`, `setTimeout`, `setInterval`,
+  #     `addEventListener`, `data-controller=`
+  activation:
+    depends_on: typescript-strict
+    diff_signals:
+      - ".tsx"
+      - "useEffect"
+      - "useState"
+      - "setTimeout"
+      - "setInterval"
+      - "addEventListener"
+      - "data-controller="
+references:
+  rubric: agents/skills/claude-code/harness-code-review/references/confidence-rubric.md
+outputs:
+  agents-md: false
+  ci-workflow: false
+  runtime-config: true

package/dist/agents/personas/typescript-strict-reviewer.yaml

@@ -0,0 +1,53 @@
+version: 2
+name: TypeScript-strict Reviewer
+description: Framework-aware reviewer for TypeScript diffs — flags type holes, refactor regressions, complexity growth, and five-second-rule names
+role: >
+  Activate when the diff includes a non-test `.ts` or `.tsx` file. Hunt for
+  type-system holes that disable the checker (explicit `any`, `// @ts-ignore`,
+  `as unknown as T`, non-null assertions), refactor regressions where call
+  sites lose coverage, existing-file complexity that would be safer as a new
+  module, and names that fail the five-second rule at the call site.
+
+  Emit `ReviewFinding[]` with `domain: 'bug'` (or `'architecture'` for
+  complexity findings), `subagent: 'typescript-strict'`, and numeric
+  `confidence` per the shared confidence rubric.
+skills:
+  - harness-code-review
+steps:
+  - skill: harness-code-review
+    when: manual
+    output: auto
+  - skill: harness-code-review
+    when: on_pr
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "**/*.ts"
+        - "**/*.tsx"
+config:
+  severity: warning
+  autoFix: false
+  timeout: 600000
+  # Activation predicate (read by Phase 3.5 of harness-code-review):
+  # - Active when the diff contains at least one non-test `.ts` or `.tsx`
+  # - Excludes `*.d.ts`, `*.test.ts(x)`, `*.spec.ts(x)`, `__tests__/**`
+  activation:
+    file_patterns:
+      include:
+        - "**/*.ts"
+        - "**/*.tsx"
+      exclude:
+        - "**/*.d.ts"
+        - "**/*.test.ts"
+        - "**/*.test.tsx"
+        - "**/*.spec.ts"
+        - "**/*.spec.tsx"
+        - "**/__tests__/**"
+references:
+  rubric: agents/skills/claude-code/harness-code-review/references/confidence-rubric.md
+outputs:
+  agents-md: false
+  ci-workflow: false
+  runtime-config: true

package/dist/agents/skills/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @harness-engineering/skills
+
+## 1.1.0
+
+### Minor Changes
+
+- af56053: Ship the `harness-strategy` skill and the `writeStrategyDoc` writer (strategic-anchor phase 2 of 8 in the compound-engineering-adoption initiative).
+  - `packages/core/strategy` exports `writeStrategyDoc(doc, { cwd, skipBackup? })` — atomic disk write of `STRATEGY.md` with schema-validation-rejects-disk-write, an idempotent `.bak` on first overwrite, H1 preservation across re-writes, and `tmp-<pid>` + `rename` semantics that mirror `writePulseConfig`. Composes a pure `serializeStrategyDoc(doc, opts?)` (also exported) so the serializer is unit-testable without filesystem fixtures.
+  - `agents/skills/{claude-code,gemini-cli,cursor,codex}/harness-strategy/` ships the rigid skill (Phase 0 file-state routing; Phase 1 first-run interview in template order; Phase 2 per-section update flow; Phase 3 downstream handoff). `references/interview.md` documents the three pushback rules (fluff detection, goal-as-strategy, feature-list-as-strategy) with detection signals, repair scripts, anti-pattern fixtures, and the hard 2-round-per-section cap.
+  - CLI emits `/harness:strategy` via `generate-slash-commands` (and the per-platform plugin generators); the slash command appears in `.claude-plugin/commands/strategy.md`, `.gemini-extension/commands/strategy.toml`, `.cursor-plugin/commands/strategy.md`, plus the `agents/commands/*` mirrors. Skill listed in the auto-generated skills catalog.
+
+  Scope: writer + skill prose only. Init wiring, `harness-ideate`, brainstorming/roadmap-pilot grounding, knowledge-graph integration, and ADRs ship in follow-up PRs (one per phase).

package/dist/agents/skills/claude-code/align-design-system/SKILL.md

@@ -65,6 +65,7 @@ For each finding classified as `suggestion`: emit a human-readable description p
 
 - **`harness align-design-system`** — the CLI entry point. `--dry-run` for preview; `--write` is the default. Standard `--json` / `--verbose` / `--quiet` flags.
 - **`harness align-design-system --mode pipeline`** — orchestrator-driven mode. Reads pre-classified findings from handoff.json; writes outcomes back.
+- **`harness align-design-system --revert`** — inverse-applies the most-recent batch recorded at `.harness/align/last-batch.json`. Skips files edited externally since the apply (content-hash check). Idempotent: a second revert on the same batch is a no-op because the file no longer matches the recorded post-apply text.
 - **`mcp__harness__align_design_system`** — MCP tool for agent consumption. Same input/output shape as the function call.
 - **`detect-design-drift`** — soft dependency. Standalone mode invokes detect internally; pipeline mode trusts the orchestrator to have done it.
 - **`harness check-design`** — composes detect (as 3rd verifier) into a single-pass design check. align is the matching FIX step; together they form the DETECT → FIX cycle that the (future) #5 orchestrator will loop.
@@ -82,6 +83,7 @@ See `docs/changes/design-pipeline/align-design-system/proposal.md` for the full
 - Pipeline mode writes `pipeline.fixesApplied` back to handoff.json
 - `--dry-run` produces identical `FixOutcome` shapes but never writes files
 - Re-running detect after align produces strictly fewer T001/T002/T003 findings
+- `--revert` re-applies the inverse of the most-recent `fixesApplied` batch; no-op when the file has been edited externally since the apply
 
 ## Examples
 
@@ -147,6 +149,21 @@ src/SaveButton.tsx
 
 v1 never auto-applies primitive adoption — prop translation across `<button>` ⇄ `<Button>` is the kind of judgment-call that benefits from a human or LLM review.
 
+### Example: Revert the last batch
+
+After a write run, the applied diffs (plus a SHA-256 of each post-apply file) are persisted to `.harness/align/last-batch.json`. Running `harness align-design-system --revert` reads that batch and inverse-applies each diff:
+
+```
+src/Card.tsx
+  ✓ DRIFT-T001:2 — Hex color "#0066cc" should use a token reference instead of a raw literal
+     before: const styles = { color: tokens.color.brand.primary };
+     after:  const styles = { color: "#0066cc" };
+
+Summary: 1 reverted, 0 suggestions, 0 skipped, 0 failed (1 files modified, 4ms)
+```
+
+If the file has been edited externally between apply and revert (the SHA-256 doesn't match), every entry for that file is skipped with `skipped-unsafe / reason: file changed externally since apply`. A second revert on the same batch is a no-op for the same reason — the file's post-revert content no longer matches the recorded post-apply text.
+
 ## Gates
 
 - **No autofix without classifier approval.** Every codemod application goes through `classifyFinding`. If the classifier returns `suggestion`, NO file write occurs — even for the same finding code in the same file.
@@ -162,6 +179,7 @@ v1 never auto-applies primitive adoption — prop translation across `<button>`
 - **When the codemod corrupts a file (rare):** every application includes a structured diff. Recover via `git checkout <file>`. If the same input repeatedly corrupts, report the case — pre-flight classifier rules are conservative by design.
 - **When pipeline-mode run finds no `pipeline.driftFindings` field:** align exits cleanly with empty outcomes. The orchestrator's contract is to write the field BEFORE invoking align.
 - **When `--dry-run` shows fixes you don't want applied:** scope with `--files <glob>` to apply only specific files, or invoke align in pipeline mode with a curated `pipeline.fixBatch` list.
+- **When you want to undo an apply:** run `harness align-design-system --revert`. It reads `.harness/align/last-batch.json`, content-hash-checks each file, and inverse-applies. Files edited since the apply are skipped (no silent corruption); recover via `git checkout <file>` if the content-hash check blocks revert and the prior commit is still in history.
 - **When you want primitive-adoption fixes today:** apply the suggestion manually. The v1.x sub-project will add prop-translation tables + import resolution + revert-on-test-fail.
 - **When align is invoked without detect having run first (standalone mode):** standalone mode runs detect internally — no manual ordering needed. Pipeline mode trusts the orchestrator to populate findings.
 

package/dist/agents/skills/claude-code/align-design-system/skill.yaml

@@ -31,6 +31,9 @@ cli:
     - name: mode
       description: standalone (default) or pipeline (read findings from handoff.json)
       required: false
+    - name: revert
+      description: Inverse-apply the most-recent batch persisted at .harness/align/last-batch.json
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/claude-code/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/claude-code/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/claude-code/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/claude-code/harness-brainstorming/SKILL.md

@@ -35,7 +35,26 @@ When no arguments are provided (standalone invocation), the skill operates exact
 
 ### Phase 1: EXPLORE -- Gather Context
 
-1. **Load project context.** Call `gather_context({ path: "<project-root>", intent: "<feature description>", skill: "harness-brainstorming", session: "<session-slug-if-known>", include: ["graph", "businessKnowledge", "sessions", "validation"] })`. The `graph` context surfaces `business_fact` nodes relevant to the feature domain. The `businessKnowledge` context loads documented domain knowledge from `docs/knowledge/`. Use both to ground exploration in verified facts rather than assumptions.
+0a. **Read STRATEGY.md if present at repo root (upstream grounding).** Strategy is the durable product anchor that ranks above feature-level context — read it first so the rest of EXPLORE can cross-reference. Call `read_strategy({ path: "<project-root>" })` 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.
+
+    Fallback for environments without the MCP server (only works when core is resolvable from the project):
+
+    ```bash
+    node -e "import('@harness-engineering/core').then(async m => {
+      const v = await m.validateStrategy(process.cwd());
+      if (!v.ok || !v.value.present) { console.log(JSON.stringify({ grounded: false, reason: 'absent' })); return; }
+      const raw = require('fs').readFileSync('STRATEGY.md', 'utf-8');
+      console.log(JSON.stringify({ grounded: true, doc: m.asStrategyDoc(m.parseStrategyDoc(raw)) }));
+    })"
+    ```
+
+    Three cases:
+
+    - **Absent or invalid:** soft-fail silently. Do not block and do not warn in the spec — the skill works exactly as before when there is no strategic anchor.
+    - **Present and valid:** capture the `Target problem`, `Our approach`, `Who it's for`, and `Tracks` section bodies. Treat them as grounding context alongside `gather_context` outputs. The captured strategy is cited as evidence in step 1's `[evidence]` annotations of the spec output.
+    - **Contradiction with the user's feature description:** do NOT auto-resolve. Carry the contradiction forward as an open question into Phase 2 EVALUATE — surface it explicitly so the human can decide whether to refine the feature or update strategy via `/harness:strategy`.
+
+1. **Load project context.** Call `gather_context({ path: "<project-root>", intent: "<feature description>", skill: "harness-brainstorming", session: "<session-slug-if-known>", include: ["graph", "businessKnowledge", "sessions", "validation"] })`. The `graph` context surfaces `business_fact` nodes relevant to the feature domain. The `businessKnowledge` context loads documented domain knowledge from `docs/knowledge/`. Use both to ground exploration in verified facts rather than assumptions. When `STRATEGY.md` was loaded in step 0a, treat its sections as a higher-tier grounding source than `businessKnowledge` — strategy reflects an explicit human commitment, knowledge is observation.
 2. **Read the existing codebase.** Understand architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
 3. **Identify the problem boundary.** What exactly needs solving? What is out of scope? Write both down. Cross-reference `businessKnowledge` domains — if documented business rules constrain the problem, note them.
 4. **Check for prior art.** Has this been partially solved elsewhere? Are there patterns to follow or deliberately break?
@@ -66,7 +85,8 @@ When no arguments are provided (standalone invocation), the skill operates exact
 2. **Prefer multiple choice over open-ended questions.** Give 2-4 concrete options with brief tradeoff notes.
 3. **Acknowledge answers and build on them.** Do not re-ask clarified points. Track decisions as they accumulate.
 4. **Apply YAGNI ruthlessly.** For every proposed capability, ask: "Do we need this for the stated goal, or is this speculative?" If speculative, cut it. If the human insists, note it as a future consideration.
-5. **Continue until you have enough clarity** to propose concrete approaches. Typically 3-7 questions suffice. If you need >10, the scope is too large -- decompose.
+5. **Surface strategy contradictions.** If Phase 1 step 0a captured a contradiction between the feature description and `STRATEGY.md`, ask the human about it explicitly as one of the first few EVALUATE questions. Frame it as a choice — refine the feature to align, or refine strategy via `/harness:strategy` — never auto-resolve. Skip this when STRATEGY.md was absent or no contradiction was detected.
+6. **Continue until you have enough clarity** to propose concrete approaches. Typically 3-7 questions suffice. If you need >10, the scope is too large -- decompose.
 
 ### Context Keywords
 
@@ -116,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.
@@ -166,14 +186,37 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
 
    The human must explicitly approve before this skill is complete.
 
-7. **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.
+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 docs/roadmap.md
+   git commit -m "docs(<feature>): add spec and promote to planned"
+   ```
+
+   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.
 
-8. **Write handoff and suggest transition.** After approval:
+9. **Write handoff and suggest transition.** After approval:
 
    Write handoff to the session-scoped path when a session slug is known, otherwise fall back to the global path:
    - Session-scoped (preferred): `.harness/sessions/<session-slug>/handoff.json`
@@ -292,7 +335,8 @@ Technical claims about existing code, architecture, or tradeoffs MUST cite evide
 1. **File reference:** `file:line` (e.g., `src/services/auth.ts:42` -- "existing JWT middleware")
 2. **Prior art:** `file` with description (e.g., `src/utils/email.ts` -- "reusable for notifications")
 3. **Docs:** `docs/path` (e.g., `docs/changes/user-auth/proposal.md` -- "established OAuth2 standard")
-4. **Session evidence:** Write via `manage_state` `append_entry` to `evidence` section.
+4. **Strategy grounding:** `STRATEGY.md` with section reference (e.g., `STRATEGY.md#tracks` -- "advances the 'pulse-reports' track"). Cite when Phase 1 step 0a loaded a valid strategy AND the decision is informed by it. Mandatory when the spec extends, narrows, or contradicts a strategy section.
+5. **Session evidence:** Write via `manage_state` `append_entry` to `evidence` section.
 
 **When to cite:** Phase 1 (existing code/patterns), Phase 3 (tradeoff justifications), Phase 4 (spec referencing existing implementation).
 
@@ -302,10 +346,12 @@ Technical claims about existing code, architecture, or tradeoffs MUST cite evide
 
 - **`harness validate`** -- Run after writing the spec. Verifies project health and spec placement.
 - **`harness check-docs`** -- Verify spec does not conflict with existing docs.
+- **`STRATEGY.md` grounding (Phase 1 step 0a)** -- When present at repo root and valid, loaded via the `read_strategy` MCP tool (which the harness MCP server backs with `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` from `@harness-engineering/core` — projects do not need core installed). Soft-fails when absent or invalid; cites strategy sections in the spec's evidence annotations when present. Boundary with `harness-strategy`: brainstorming READS; `harness-strategy` WRITES. Never modify `STRATEGY.md` from this skill.
 - **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.
-- **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