@harness-engineering/cli 2.7.1 → 2.8.0

package/dist/agents/skills/gemini-cli/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
 
@@ -166,14 +186,23 @@ 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:
+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:
+
+   ```bash
+   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md
+   git commit -m "docs(<feature>): add spec"
+   ```
+
+   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.
 
-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 +321,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,9 +332,11 @@ 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.
+- **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.
 - **`emit_interaction`** -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).
 

package/dist/agents/skills/gemini-cli/harness-code-review/SKILL.md

@@ -33,20 +33,22 @@ A reviewer who applies fixes is no longer reviewing — they are editing with re
 The review runs as a 7-phase pipeline. Each phase has a clear input, output, and exit condition.
 
 ```
-Phase 1: GATE --> Phase 2: MECHANICAL --> Phase 3: CONTEXT --> Phase 4: FAN-OUT
-                                                                      |
-Phase 7: OUTPUT <-- Phase 6: DEDUP+MERGE <-- Phase 5: VALIDATE <------+
+Phase 1: GATE --> Phase 2: MECHANICAL --> Phase 3: CONTEXT --> Phase 3.5: CALIBRATE
+                                                                                 |
+                                                                                 v
+Phase 7: OUTPUT <-- Phase 6: DEDUP+MERGE <-- Phase 5: VALIDATE <-- Phase 4: FAN-OUT
 ```
 
-| Phase          | Tier  | Purpose                          | Exit Condition                                    |
-| -------------- | ----- | -------------------------------- | ------------------------------------------------- |
-| 1. GATE        | fast  | Skip ineligible PRs (CI only)    | PR eligible, or exit with reason                  |
-| 2. MECHANICAL  | none  | Lint, typecheck, test, sec scan  | All pass -> continue; any fail -> report and stop |
-| 3. CONTEXT     | fast  | Scope context per review domain  | Context bundles assembled for each subagent       |
-| 4. FAN-OUT     | mixed | Parallel review subagents        | All subagents return ReviewFinding[]              |
-| 5. VALIDATE    | none  | Exclude mechanical dupes, verify | Unvalidated findings discarded                    |
-| 6. DEDUP+MERGE | none  | Group, merge, assign severity    | Deduplicated finding list with merged evidence    |
-| 7. OUTPUT      | none  | Text output or GitHub comments   | Review delivered, exit code set                   |
+| Phase          | Tier  | Purpose                                            | Exit Condition                                    |
+| -------------- | ----- | -------------------------------------------------- | ------------------------------------------------- |
+| 1. GATE        | fast  | Skip ineligible PRs (CI only)                      | PR eligible, or exit with reason                  |
+| 2. MECHANICAL  | none  | Lint, typecheck, test, sec scan                    | All pass -> continue; any fail -> report and stop |
+| 3. CONTEXT     | fast  | Scope context per review domain                    | Context bundles assembled for each subagent       |
+| 3.5. CALIBRATE | none  | Pick depth tier + activate conditional subagents   | DepthCalibration recorded in PipelineContext      |
+| 4. FAN-OUT     | mixed | Parallel review subagents (4 base + N conditional) | All subagents return ReviewFinding[]              |
+| 5. VALIDATE    | none  | Exclude mechanical dupes, verify                   | Unvalidated findings discarded                    |
+| 6. DEDUP+MERGE | none  | Group, merge, assign severity                      | Deduplicated finding list with merged evidence    |
+| 7. OUTPUT      | none  | Text output or GitHub comments                     | Review delivered, exit code set                   |
 
 ### Finding Schema
 
@@ -62,19 +64,35 @@ interface ReviewFinding {
   suggestion?: string; // fix, if available
   evidence: string[]; // supporting context from agent
   validatedBy: 'mechanical' | 'graph' | 'heuristic';
+  // Additive — populated by the new conditional subagents only:
+  subagent?:
+    | 'compliance'
+    | 'bug'
+    | 'security'
+    | 'architecture'
+    | 'learnings'
+    | 'adversarial'
+    | 'typescript-strict'
+    | 'frontend-races';
+  confidence?: 'high' | 'medium' | 'low' | 25 | 50 | 75 | 100;
 }
 ```
 
+The two optional fields are additive — existing 4 agents leave them
+undefined. Numeric `confidence` values follow the anchored rubric at
+[references/confidence-rubric.md](references/confidence-rubric.md).
+
 ### Flags
 
-| Flag              | Effect                                                               |
-| ----------------- | -------------------------------------------------------------------- |
-| `--comment`       | Post inline comments to GitHub PR via `gh` CLI or GitHub MCP         |
-| `--deep`          | Pass `--deep` to `harness-security-review` for threat modeling       |
-| `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                 |
-| `--ci`            | Enable eligibility gate, non-interactive output                      |
-| `--fast`          | Skip learnings, fast-tier agents for all fan-out slots               |
-| `--thorough`      | Always load learnings, full roster + meta-judge, learnings in output |
+| Flag              | Effect                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `--comment`       | Post inline comments to GitHub PR via `gh` CLI or GitHub MCP                         |
+| `--deep`          | Pass `--deep` to `harness-security-review` for threat modeling                       |
+| `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                                 |
+| `--ci`            | Enable eligibility gate, non-interactive output                                      |
+| `--fast`          | Skip learnings, fast-tier agents for all fan-out slots                               |
+| `--thorough`      | Always load learnings, full roster + meta-judge, learnings in output                 |
+| `--depth`         | Override Phase 3.5 calibration: `quick`/`standard`/`deep`. `deep` activates all subs |
 
 ### Rigor Levels
 
@@ -254,7 +272,33 @@ git log --oneline -5 -- <affected-file>
 
 Use to determine: **Hotspot?** (3+ changes in last 5 commits) **Recently refactored?** **Multiple authors?** **Last change was bugfix?** (yellow flag)
 
-**Exit:** Context bundles assembled for all four domains. Continue to Phase 4.
+**Exit:** Context bundles assembled for all four domains. Continue to Phase 3.5.
+
+---
+
+### Phase 3.5: CALIBRATE DEPTH
+
+**Tier:** none (mechanical) | **Purpose:** Pick a depth tier (Quick/Standard/Deep) from diff size + risk-keyword detection and decide which conditional subagents activate in Phase 4. The existing 4 agents always run; this phase only gates _additional_ work.
+
+**Inputs:** `DiffInfo`, commit message, optional `--depth quick|standard|deep` override.
+
+**Steps:**
+
+1. **Count changed lines.** Sum `+`/`-` lines per file, excluding test files (`*.test.{ts,tsx,js,jsx}`, `__tests__/**`, `*.spec.{ts,tsx,js,jsx}`), generated files (`*.generated.{ts,tsx,js,jsx}`), lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`), and `dist/` / `build/` directories.
+2. **Detect risk keywords.** Match the canonical keyword list from [references/risk-keywords.md](references/risk-keywords.md) against the diff content, file paths, and commit message (case-insensitive, whole-word for single-word keywords, substring for multi-word keywords like `external API`).
+3. **Compute tier.**
+   - **Quick:** `< 50` lines AND `0` keywords
+   - **Standard:** `50–199` lines OR exactly `1` keyword
+   - **Deep:** `≥ 200` lines OR `≥ 2` keywords
+4. **Compute activation set** (`adversarial`, `typescript-strict`, `frontend-races`):
+   - `adversarial` — active at Standard or Deep
+   - `typescript-strict` — active when the diff contains a non-test `.ts` or `.tsx` (excluding `*.d.ts`)
+   - `frontend-races` — active when `typescript-strict` is active AND the diff contains one of `.tsx`, `useEffect`, `useState`, `setTimeout`, `setInterval`, `addEventListener`, `data-controller=`
+5. **Override (`--depth deep`)** — forces Deep tier and activates all three conditional subagents.
+
+**Output:** `DepthCalibration { depth, changedLines, riskSignals, activations, overridden }` recorded in `PipelineContext`. Phase 7 displays the calibration result at the top of the review.
+
+**Exit:** Calibration complete. Continue to Phase 4.
 
 ---
 
@@ -380,7 +424,48 @@ Reviews architectural violations, dependency direction, and design pattern compl
 
 **Output:** `ReviewFinding[]` with `domain: 'architecture'`
 
-**Exit:** All four agents returned findings. Continue to Phase 5.
+---
+
+#### Conditional Subagents (depth-gated, activated by Phase 3.5)
+
+The dispatcher reads `PipelineContext.depthCalibration.activations` and runs only those listed. Each conditional subagent emits findings under existing domain values (`bug` or `architecture`) and populates `subagent` + `confidence` per the [confidence rubric](references/confidence-rubric.md).
+
+##### Adversarial (strong tier) — activates at Standard or Deep
+
+Constructs failure scenarios that fall _between_ the base 4 agents.
+
+**Hunt categories:**
+
+- **Assumption violation** — invariants the diff depends on but does not enforce (e.g., `JSON.parse` on untrusted input)
+- **Composition failures** — two patterns correct alone that misbehave together (floating Promise chains, optional-chain calls)
+- **Abuse cases** — adversarial input shapes the diff does not anticipate (unbounded `fetch`, accidentally enumerable surfaces)
+- **Cascade chains (Deep only)** — single failures propagating through downstream callers (`new Promise` without `reject`)
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'`, `subagent: 'adversarial'`, `confidence: 50|75|100`.
+
+##### TypeScript-strict (standard tier) — activates when a non-test `.ts`/`.tsx` is in the diff
+
+**Hunt categories:**
+
+- **Type holes that disable the checker** — explicit `any`, `// @ts-ignore`, `as unknown as T`, non-null assertions in non-`process.env` contexts
+- **Refactor regression risk** — removed guards whose call sites have no test coverage
+- **Existing-file complexity** — production TS files growing past 400 lines (Single Responsibility flag)
+- **Five-second rule** — `handle*` / `process*` / `do*` style names that fail to predict behavior at the call site
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'` (type holes / regression) or `domain: 'architecture'` (complexity), `subagent: 'typescript-strict'`, `confidence: 50|75|100`.
+
+##### Frontend-races (standard tier) — activates when TypeScript-strict is active AND an async-UI signal is present
+
+**Hunt categories:**
+
+- **Lifecycle cleanup gaps** — `setInterval` / `setTimeout` / `addEventListener` without matching cleanup in the same module
+- **Hook timing mistakes** — `useEffect` immediately calling `setState` for a render-time-derivable value
+- **Concurrent interactions** — overlapping clicks/requests, impossible-state booleans
+- **Stale work** — `await fetch` followed by `setState` with no `AbortController` / `AbortSignal.timeout`
+
+**Output:** `ReviewFinding[]` with `domain: 'bug'`, `subagent: 'frontend-races'`, `confidence: 50|75|100`.
+
+**Exit:** All base agents + active conditional subagents returned findings. Continue to Phase 5.
 
 ---
 

package/dist/agents/skills/gemini-cli/harness-code-review/references/confidence-rubric.md

@@ -0,0 +1,45 @@
+# Confidence Rubric
+
+> Anchored confidence rubric for `harness-code-review` conditional subagents. Numeric anchors avoid vague "high/medium/low" judgments. New subagents (`adversarial`, `typescript-strict`, `frontend-races`) populate `ReviewFinding.confidence` per this rubric. Existing 4 agents (compliance, bug, security, architecture) are not yet migrated.
+
+## Anchors
+
+| Score | Label                  | Definition                                                                                                                                      |
+| ----- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `100` | Mechanical             | Directly verifiable from the diff. The finding can be reproduced by quoting specific lines. No interpretation required.                         |
+| `75`  | Constructible scenario | The agent can describe a concrete sequence of inputs and observable outputs that triggers the issue. Every step is traceable to specific lines. |
+| `50`  | Judgment-based         | The issue is real but partly judgment. Depends on assumptions about behavior outside the diff.                                                  |
+| `25`  | Speculative            | Not supported by what is in the diff. **Suppress.** Agents must not emit.                                                                       |
+
+A finding with confidence below `25` must be discarded before it leaves the subagent.
+
+## Per-agent worked examples
+
+### `adversarial`
+
+- **100 — Mechanical**: every step in the cascade is traceable to specific lines. _Example: a `useState` updater on line 32 schedules work that the cleanup on line 45 never cancels — both lines are quoted._
+- **75 — Constructible scenario**: given specific input X, execution reaches line Y and produces wrong outcome Z. _Example: "If `parseDate('')` returns `null` (line 18), the chain at line 22 throws because there is no nullable check before `.toISOString()`."_
+- **50 — Judgment-based**: scenario depends on external API behavior assumed but unverified. _Example: "If the remote service occasionally returns `5xx`, the retry loop at line 60 enters a tight spin." — the tight spin is real but the retry condition needs runtime evidence._
+- **25 — Speculative**: "What if the caller ever does X?" with no diff evidence. _Suppress._
+
+### `typescript-strict`
+
+- **100 — Mechanical**: explicit `any`, `// @ts-ignore`, `as unknown as Foo`, or `unknown` assertion in the diff. _Example: `function load(x: any) { ... }` is quoted directly._
+- **75 — Constructible scenario**: a refactor in the diff removes a guard that the type system relied on. _Example: "Removing the `if (user)` check on line 12 means line 14's access `user.id` is now reachable for `null`, but no test exercises this path."_
+- **50 — Judgment-based**: naming or extraction quality calls. _Example: "Function `handleStuff` does three things — the five-second-rule fails for a future reader." — true but discretionary._
+- **25 — Speculative**: "Could be improved someday." _Suppress._
+
+### `frontend-races`
+
+- **100 — Mechanical**: `setInterval` with no `clearInterval` in disconnect/unmount; `addEventListener` with no `removeEventListener`. _Example: `setInterval(tick, 1000)` on line 30 with no cleanup return in the `useEffect`._
+- **75 — Constructible scenario**: race traceable to a specific interaction sequence. _Example: "Double-click on the submit button triggers two parallel network calls because `isSubmitting` is set inside an `await` (line 45) after the button stays clickable."_
+- **50 — Judgment-based**: race depends on timing windows not fully forceable from diff. _Example: "If the server replies before the cleanup runs, the stale callback updates the new component instance." — possible but requires timing assumptions._
+- **25 — Speculative**: "On a slow device this might race." _Suppress._
+
+## How dedup uses confidence
+
+Phase 6 DEDUP+MERGE prefers the higher-`severity` finding when two agents flag the same line. On a severity tie, the finding with explicit `confidence` set wins. When neither has confidence (the existing 4 agents), current dedup behavior is unchanged.
+
+## Compatibility
+
+The legacy security agent uses string values (`'high' | 'medium' | 'low'`). New subagents use numeric anchors (`25 | 50 | 75 | 100`). The `ReviewFinding.confidence` field accepts either. Future migration of the security agent to numeric anchors is opt-in and out of scope here.

package/dist/agents/skills/gemini-cli/harness-code-review/references/risk-keywords.md

@@ -0,0 +1,40 @@
+# Risk keywords for depth calibration
+
+> Used by Phase 3.5 CALIBRATE in `harness-code-review` to elevate a diff's depth tier when sensitive surfaces are touched. The list below is the **single source of truth** — Decisions 7 and 8 of the spec reference this file rather than re-enumerating. Modifications to this list are policy decisions; updates require PR review.
+
+The calibrator matches against the changed-file content, file paths, and the commit message. Matching is case-insensitive and whole-word where possible (substring for path matches like `auth/` directories).
+
+## Canonical list
+
+```
+auth
+authn
+authz
+password
+token
+payment
+billing
+migration
+migrate
+external API
+webhook
+cryptography
+crypto
+session
+cookie
+personally identifiable
+PII
+compliance
+```
+
+## Tier rules (from spec Decision 8)
+
+| Diff size | Keywords matched | Depth tier |
+| --------: | ---------------: | ---------- |
+|    `< 50` |              `0` | Quick      |
+|  `50–199` |              `0` | Standard   |
+|    `< 50` |              `1` | Standard   |
+|       any |            `≥ 2` | Deep       |
+|   `≥ 200` |              any | Deep       |
+
+Author override: `--depth quick|standard|deep` forces the tier and bypasses calibration.

package/dist/agents/skills/gemini-cli/harness-code-review/skill.yaml

@@ -42,6 +42,9 @@ cli:
     - name: --thorough
       description: Maximum rigor — always load learnings, full agent roster + meta-judge
       required: false
+    - name: --depth
+      description: "Override Phase 3.5 depth calibration: quick|standard|deep. 'deep' activates all conditional subagents (adversarial, typescript-strict, frontend-races)."
+      required: false
     - name: session-slug
       description: Session slug for scoped state/handoff (passed by autopilot)
       required: false

package/dist/agents/skills/gemini-cli/harness-compound/SKILL.md

@@ -83,19 +83,22 @@ Read `docs/solutions/references/schema.yaml` for the authoritative track/categor
 ### Phase 5: WRITE (lock-protected)
 
 1. Compute slug: kebab-case from the title; if a file with that slug already exists in the target directory, append `-2`, `-3`, etc.
-2. **Acquire the per-category lock by shelling out.** Run a Node one-liner that imports `acquireCompoundLock` from `@harness-engineering/core`, holds the handle while you write the doc, then releases it. Example: `node -e "import('@harness-engineering/core').then(({ acquireCompoundLock }) => { const h = acquireCompoundLock('<category>'); /* write the doc here */ h.release(); }).catch(err => { console.error(err.message); process.exit(1); })"`. Lock path: `.harness/locks/compound-<category>.lock`. The MCP tool `acquire_compound_lock` is planned for a later phase — **do not attempt to call it yet**; the shell-out is the only supported path right now.
-   - On `CompoundLockHeldError`: report "compound lock for category `<category>` is held by pid `<N>` — wait for it to release or run `/harness:compound` for a different category" and stop. **Do not retry automatically.** A second invocation on the same problem after release will go through Phase 3 and find the doc the first invocation produced.
+2. **Acquire the per-category lock via the harness MCP server.** Call `acquire_compound_lock({ path: process.cwd(), category: '<category>' })`. On success it returns `{ acquired: true, token, lockPath }` — hold the `token` while you write the doc, then call `release_compound_lock({ token })` when finished. The MCP server holds the file handle and registers process-exit cleanup, so an abandoned agent does not leave a dangling lock-with-stale-PID. Lock path: `.harness/locks/compound-<category>.lock`. Fallback for environments without the MCP server (only works when `@harness-engineering/core` is resolvable from the project): `node -e "import('@harness-engineering/core').then(({ acquireCompoundLock }) => { const h = acquireCompoundLock('<category>'); /* write the doc here */ h.release(); })"`.
+   - On `{ acquired: false, error: 'CompoundLockHeldError', holderPid }` (or `CompoundLockHeldError` when invoked directly): report "compound lock for category `<category>` is held by pid `<holderPid>` — wait for it to release or run `/harness:compound` for a different category" and stop. **Do not retry automatically.** A second invocation on the same problem after release will go through Phase 3 and find the doc the first invocation produced.
 3. Re-run a quick Phase 3 overlap-check inside the lock (defends against TOCTOU when the first overlap-check returned "no overlap" but another invocation completed in the meantime; the re-check is cheap).
 4. Write the file at `docs/solutions/<track>/<category>/<slug>.md`.
 5. Validate frontmatter against `SolutionDocFrontmatterSchema` by running `harness validate` (which runs `validateSolutionsDir`).
-6. Release the lock.
+6. Release the lock via `release_compound_lock({ token })` (or `handle.release()` on the fallback shell-out path).
 7. Surface to chat: file path created (or updated), category, and a one-sentence summary.
 
 ## Harness Integration
 
 - **`harness validate`** — Run after writing the doc; the solutions validator catches frontmatter errors before commit.
 - **`harness check-deps`** — Not required (no new module imports introduced by writing a doc).
-- **`@harness-engineering/core` lock primitive** — `acquireCompoundLock(category, { cwd })` returns a release handle; throws `CompoundLockHeldError` on contention. See `packages/core/src/locks/compound-lock.ts`.
+- **Harness MCP tools consumed by this skill** (canonical execution path — no project-local `@harness-engineering/core` required):
+  - `acquire_compound_lock({ path, category })` — returns `{ acquired: true, token, lockPath }` on success or `{ acquired: false, error: 'CompoundLockHeldError', holderPid, lockPath }` on contention.
+  - `release_compound_lock({ token })` — releases the lock; idempotent on repeat calls with the same token.
+- **`@harness-engineering/core` lock primitive** (only directly relevant when the MCP server is unavailable) — `acquireCompoundLock(category, { cwd })` returns a release handle; throws `CompoundLockHeldError` on contention. See `packages/core/src/locks/compound-lock.ts`.
 - **Schema authority** — `packages/core/src/solutions/schema.ts` is the single source of truth for tracks and categories. `docs/solutions/references/schema.yaml` mirrors it for human reading.
 - **Boundary with `harness-knowledge-pipeline`** — Knowledge-pipeline extracts structural facts FROM CODE. Compound captures post-mortem playbooks WRITTEN AFTER A FIX. Compound's knowledge-track output is a _candidate input_ to the pipeline (Phase 7 of the spec wires this).
 - **Boundary with `.harness/learnings.md`** — The file remains for ephemeral session notes. It is no longer the canonical sink for compounding knowledge — that's `docs/solutions/`.