@harness-engineering/cli 1.24.0 → 1.24.1

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

@@ -11,30 +11,39 @@
 - NOT for rubber-stamping (if you cannot find issues, look harder or state confidence level)
 - NOT for style-only feedback (leave that to linters and mechanical checks)
 
+## Argument Resolution
+
+When invoked by autopilot (or with explicit arguments), resolve paths before starting:
+
+1. **Session slug:** If `session-slug` argument provided, set `{sessionDir} = .harness/sessions/<session-slug>/`. Pass to `gather_context({ session: "<session-slug>" })`. All handoff writes go to `{sessionDir}/handoff.json`.
+2. **Commit range:** If `commit-range` argument provided (e.g., `abc123..HEAD`), use as diff scope in Phase 2 MECHANICAL and Phase 7 OUTPUT. Otherwise, auto-detect from git environment.
+
+When no arguments are provided (standalone invocation), session slug is unknown — omit from `gather_context`, fall back to global `.harness/` paths. Diff scope auto-detected.
+
+---
+
 ## Process
 
 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 4: FAN-OUT
+                                                                      |
+Phase 7: OUTPUT <-- Phase 6: DEDUP+MERGE <-- Phase 5: VALIDATE <------+
 ```
 
-| Phase          | Tier  | Purpose                                            | Exit Condition                                        |
-| -------------- | ----- | -------------------------------------------------- | ----------------------------------------------------- |
-| 1. GATE        | fast  | Skip ineligible PRs (CI mode only)                 | PR is eligible, or exit with reason                   |
-| 2. MECHANICAL  | none  | Lint, typecheck, test, security 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 findings in ReviewFinding schema |
-| 5. VALIDATE    | none  | Exclude mechanical duplicates, verify reachability | Unvalidated findings discarded                        |
-| 6. DEDUP+MERGE | none  | Group, merge, assign final severity                | Deduplicated finding list with merged evidence        |
-| 7. OUTPUT      | none  | Text output or inline 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       |
+| 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                   |
 
 ### Finding Schema
 
-Each review agent produces findings in this common format:
-
 ```typescript
 interface ReviewFinding {
   id: string; // unique, for dedup
@@ -52,30 +61,28 @@ interface ReviewFinding {
 
 ### 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 in the security fan-out slot |
-| `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                                        |
-| `--ci`            | Enable eligibility gate, non-interactive output                                             |
-| `--fast`          | Reduced rigor: skip learnings integration, fast-tier agents for all fan-out slots           |
-| `--thorough`      | Maximum rigor: always load learnings, full agent 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 |
 
 ### Rigor Levels
 
-The `rigorLevel` is set via `--fast` or `--thorough` flags (or passed by autopilot). Default is `standard`. Rigor controls learnings integration, agent tier selection, and output verbosity.
+Set via `--fast` or `--thorough` flags (or passed by autopilot). Default is `standard`.
 
-| Phase      | `fast`                                                            | `standard` (default)                                                                               | `thorough`                                                                                                      |
-| ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| 3. CONTEXT | Skip learnings integration entirely. No `filterByRelevance` call. | Load learnings if `.harness/review-learnings.md` exists. Score and filter via `filterByRelevance`. | Always load learnings. Score and filter via `filterByRelevance`. Fail loudly if learnings file is missing.      |
-| 4. FAN-OUT | All agents run at fast tier. Reduced focus areas.                 | Default tier assignments (see Model Tiers table).                                                  | Full agent roster at default tiers + meta-judge pass that cross-validates findings across domains.              |
-| 7. OUTPUT  | Standard output format.                                           | Standard output format.                                                                            | Include a "Learnings Applied" section listing which learnings influenced the review and their relevance scores. |
-
-When `rigorLevel` is `fast`, the pipeline optimizes for speed: learnings are skipped entirely and all fan-out agents run at fast tier. When `rigorLevel` is `thorough`, the pipeline optimizes for depth: learnings are always scored and included, the full agent roster runs, a meta-judge validates cross-domain findings, and the output includes which learnings were applied.
+| Phase      | `fast`                                        | `standard` (default)                                       | `thorough`                                                                                                                     |
+| ---------- | --------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| 3. CONTEXT | Skip learnings entirely                       | Load learnings if file exists; score via filterByRelevance | Always load learnings; fail loudly if missing                                                                                  |
+| 4. FAN-OUT | All agents at fast tier. Reduced focus areas. | Default tier assignments                                   | Full roster + meta-judge confirms findings cited by multiple agents, flags contradictions, and surfaces cross-cutting concerns |
+| 7. OUTPUT  | Standard format                               | Standard format                                            | Include "Learnings Applied" section with relevance scores                                                                      |
 
 ### Model Tiers
 
-Tiers are abstract labels resolved at runtime from project config. If no config exists, all phases use the current model (no tiering).
+Tiers are abstract labels resolved at runtime from project config. If no config exists, all phases use the current model.
 
 | Tier       | Default      | Used By                              |
 | ---------- | ------------ | ------------------------------------ |
@@ -85,179 +92,122 @@ Tiers are abstract labels resolved at runtime from project config. If no config
 
 ### Review Learnings Calibration
 
-Before starting the pipeline, check for a project-specific calibration file. Learnings integration is gated by rigor level:
+Before starting the pipeline, check for a project-specific calibration file. Behavior by rigor:
 
-- **`fast`:** Skip this section entirely. Do not read or score learnings.
-- **`standard`:** Read learnings if the file exists. Score and filter. If the file does not exist, proceed with default focus areas.
-- **`thorough`:** Always read learnings. If `.harness/review-learnings.md` does not exist, log a warning: "No review-learnings.md found -- thorough mode expects calibration data."
-
-```bash
-cat .harness/review-learnings.md 2>/dev/null
-```
+- **`fast`:** Skip entirely. Do not read or score learnings.
+- **`standard`:** Read if file exists, score and filter. If missing, use default focus areas.
+- **`thorough`:** Always read. If `.harness/review-learnings.md` missing, log warning.
 
 If `.harness/review-learnings.md` exists (and rigor is not `fast`):
 
-1. **Read the Useful Findings section.** Prioritize these categories during review — they have historically caught real issues in this project.
-2. **Read the Noise / False Positives section.** De-prioritize or skip these categories — flagging them wastes the author's time and erodes trust in the review process.
-3. **Read the Calibration Notes section.** Apply these project-specific overrides to your review judgment. These represent deliberate team decisions, not oversights.
+1. **Useful Findings section** — prioritize these categories (historically caught real issues).
+2. **Noise / False Positives section** — de-prioritize or skip (wastes author time).
+3. **Calibration Notes section** — apply as project-specific overrides.
 
 #### Learnings Relevance Scoring
 
-When learnings are loaded (standard or thorough mode), score them against the diff context before applying:
+When learnings are loaded (standard or thorough), score against diff context before applying:
 
-1. **Build the diff context string.** Concatenate: changed file paths (one per line) + diff summary (commit message or PR description).
-2. **Score each learning** using `filterByRelevance(learnings, diffContext, 0.7, 1000)` from `packages/core/src/state/learnings-relevance.ts`.
-   - Each learning is scored against the diff context via Jaccard similarity.
-   - Only learnings scoring >= 0.7 are retained.
-   - Results are sorted by score descending.
-   - Results are truncated to fit within the 1000-token budget.
-3. **Apply filtered learnings** to the review focus areas:
-   - Useful Findings entries that pass the filter: boost priority for those categories.
-   - Noise/False Positive entries that pass the filter: actively suppress those patterns.
-   - Calibration Notes entries that pass the filter: apply as overrides.
-4. **If no learnings pass the 0.7 threshold,** proceed with default focus areas. Do not fall back to unscored inclusion.
+1. **Build diff context string.** Concatenate changed file paths + diff summary.
+2. **Score each learning** via `filterByRelevance(learnings, diffContext, 0.7, 1000)` from `packages/core/src/state/learnings-relevance.ts`. Only learnings >= 0.7 retained, sorted by score, truncated to 1000-token budget.
+3. **Apply filtered learnings:** boost priority for passing Useful Findings, suppress passing Noise entries, apply passing Calibration Notes as overrides.
+4. **If none pass 0.7 threshold,** use default focus areas. No fallback to unscored inclusion.
 
-If the file does not exist and rigor is `standard`, proceed with default review focus areas. After completing the review, consider suggesting that the team create `.harness/review-learnings.md` if you notice patterns that would benefit from calibration.
+After review, consider suggesting `.harness/review-learnings.md` creation if you notice patterns that would benefit from calibration.
 
 ## Pipeline Phases
 
 ### Phase 1: GATE
 
-**Tier:** fast
-**Mode:** CI only (`--ci` flag). When invoked manually, skip this phase entirely.
+**Tier:** fast | **Mode:** CI only (`--ci`). Skip when invoked manually.
 
-Check whether the PR should be reviewed at all. This prevents wasted compute in CI pipelines.
+Checks whether the PR should be reviewed at all, preventing wasted compute in CI.
 
 **Checks:**
 
-1. **PR state:** Is the PR closed or merged? → Skip with reason "PR is closed."
-2. **Draft status:** Is the PR marked as draft? → Skip with reason "PR is draft."
-3. **Trivial change:** Is the diff documentation-only (all changed files are `.md`)? → Skip with reason "Documentation-only change."
-4. **Already reviewed:** Has this exact commit range been reviewed before (check for prior review comment from this tool)? → Skip with reason "Already reviewed at {sha}."
+1. **PR state:** Closed or merged? -> Skip: "PR is closed."
+2. **Draft status:** Draft? -> Skip: "PR is draft."
+3. **Trivial change:** All changed files `.md`? -> Skip: "Documentation-only change."
+4. **Already reviewed:** Same commit range reviewed before? -> Skip: "Already reviewed at {sha}."
 
 ```bash
-# Check PR state
 gh pr view --json state,isDraft,files
-
-# Check if documentation-only
 gh pr diff --name-only | grep -v '\.md$' | wc -l  # 0 means docs-only
 ```
 
-**Exit:** If any check triggers a skip, output the reason and exit with code 0. Otherwise, continue to Phase 2.
+**Exit:** If any check triggers skip, output reason and exit 0. Otherwise continue to Phase 2.
 
 ---
 
 ### Phase 2: MECHANICAL
 
-**Tier:** none (no LLM)
-**Mode:** Skipped if `--no-mechanical` flag is set.
+**Tier:** none (no LLM) | **Mode:** Skipped with `--no-mechanical`.
 
-Run mechanical checks to establish an exclusion boundary. Any issue caught mechanically is excluded from AI review (Phase 4) to prevent duplicate findings.
+Run mechanical checks to establish an exclusion boundary. Issues caught here are excluded from AI review (Phase 4).
 
 **Checks:**
 
-1. **Harness validation:** Use `assess_project` to run all harness health checks in parallel:
-   ```json
-   assess_project({
-     path: "<project-root>",
-     checks: ["validate", "deps", "docs"],
-     mode: "detailed"
-   })
-   ```
-   This runs `harness validate`, `harness check-deps`, and `harness check-docs` in parallel and returns a unified report. Any check failure is reported in the `checks` array with `passed: false`.
-2. **Security scan:** Run `run_security_scan` MCP tool on changed files. Record findings with rule ID, file, line, and remediation.
-3. **Type checking:** Run the project's type checker (e.g., `tsc --noEmit`). Record any type errors.
-4. **Linting:** Run the project's linter (e.g., `eslint`). Record any lint violations.
-5. **Tests:** Run the project's test suite. Record any failures.
-
-**Output:** A set of mechanical findings (file, line, tool, message). This set becomes the exclusion list for Phase 5.
+1. **Harness validation:** `assess_project({ path, checks: ["validate", "deps", "docs"], mode: "detailed" })` — runs checks in parallel.
+2. **Security scan:** `run_security_scan` on changed files. Record findings with rule ID, file, line.
+3. **Type checking:** Run `tsc --noEmit`. Record errors.
+4. **Linting:** Run linter. Record violations.
+5. **Tests:** Run test suite. Record failures.
+
+**Output:** Set of mechanical findings (file, line, tool, message) forming the exclusion list for Phase 5.
 
 #### Evidence Gate (session-aware)
 
-When a `sessionSlug` is available (e.g., via autopilot dispatch or `--session` flag), the pipeline loads evidence entries from the session state and cross-references them with review findings:
+When `sessionSlug` is available, load evidence entries from session state and cross-reference with findings:
 
-1. Load evidence entries: `readSessionSection(projectRoot, sessionSlug, 'evidence')`
-2. For each finding, check if any active evidence entry references the same file:line location
-3. Findings without matching evidence are tagged with `[UNVERIFIED]` prefix in their title
-4. An evidence coverage report is appended to the review output:
-   ```
-   Evidence Coverage:
-     Evidence entries: 12
-     Findings with evidence: 8/10
-     Uncited findings: 2 (flagged as [UNVERIFIED])
-     Coverage: 80%
-   ```
+1. Load: `readSessionSection(projectRoot, sessionSlug, 'evidence')`
+2. Check if evidence entries reference the same file:line as each finding
+3. Unmatched findings tagged `[UNVERIFIED]`
+4. Append coverage report: evidence entries count, findings with evidence, coverage %
 
-When no session is available, evidence checking is skipped silently. This is not an error -- evidence checking enhances reviews but does not gate them.
+When no session is available, skip silently. Evidence checking enhances but does not gate reviews.
 
-**Exit:** If any mechanical check fails (harness validate, typecheck, or tests), report the mechanical failures in Strengths/Issues/Assessment format and stop the pipeline. The code has fundamental issues that must be fixed before AI review adds value. Lint warnings and security scan findings do not stop the pipeline — they are recorded for exclusion only.
+**Exit:** If harness validate, typecheck, or tests fail, report in Strengths/Issues/Assessment format and stop. Lint warnings and security findings do not stop the pipeline -- recorded for exclusion only.
 
 ---
 
 ### Phase 3: CONTEXT
 
-**Tier:** fast
-**Purpose:** Assemble scoped context bundles for each review domain. Each subagent in Phase 4 receives only the context relevant to its domain, not the full diff.
+**Tier:** fast | **Purpose:** Assemble scoped context bundles per review domain. Each subagent receives only domain-relevant context.
 
 #### Change-Type Detection
 
-Before scoping context, determine the change type. This shapes which review focus areas apply.
+Determine change type to shape review focus:
 
-1. **Commit message prefix:** Parse the most recent commit message for conventional commit prefixes:
-   - `feat:` or `feature:` → **feature**
-   - `fix:` or `bugfix:` → **bugfix**
-   - `refactor:` → **refactor**
-   - `docs:` or `doc:` → **docs**
-2. **Diff pattern heuristic:** If no prefix is found, examine the diff:
-   - New files added + tests added → likely **feature**
-   - Small changes to existing files + test added → likely **bugfix**
-   - File renames, moves, or restructuring with no behavior change → likely **refactor**
-   - Only `.md` files or comments changed → likely **docs**
-3. **Default:** If detection is ambiguous, treat as **feature** (the most thorough review).
-
-```bash
-# Parse commit message prefix
-git log --oneline -1 | head -1
-
-# Check for new files
-git diff --name-status HEAD~1 | grep "^A"
-
-# Check if only docs changed
-git diff --name-only HEAD~1 | grep -v '\.md$' | wc -l  # 0 means docs-only
-```
+1. **Commit prefix:** `feat:` -> feature, `fix:` -> bugfix, `refactor:` -> refactor, `docs:` -> docs
+2. **Diff heuristic:** New files + tests -> feature; small changes + test -> bugfix; renames/moves -> refactor; only `.md` -> docs
+3. **Default:** If ambiguous, treat as feature (most thorough review).
 
 #### Context Scoping
 
-Scope context per review domain. When a knowledge graph exists at `.harness/graph/`, use graph queries. Otherwise, fall back to file-based heuristics.
-
-| Domain            | With Graph                                                               | Without Graph (Fallback)                                                                |
-| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| **Compliance**    | Convention files (`CLAUDE.md`, `AGENTS.md`, `.harness/`) + changed files | Convention files + changed files (same — no graph needed)                               |
-| **Bug Detection** | Changed files + direct dependencies via `query_graph`                    | Changed files + files imported by changed files (`grep import`)                         |
-| **Security**      | Security-relevant paths + data flow traversal via `query_graph`          | Changed files + files containing security-sensitive patterns (auth, crypto, SQL, shell) |
-| **Architecture**  | Layer boundaries + import graph via `query_graph` + `get_impact`         | Changed files + `harness check-deps` output                                             |
+| Domain            | With Graph                                                | Without Graph (Fallback)                                  |
+| ----------------- | --------------------------------------------------------- | --------------------------------------------------------- |
+| **Compliance**    | Convention files + changed files                          | Same (no graph needed)                                    |
+| **Bug Detection** | Changed files + dependencies via `query_graph`            | Changed files + imported files (`grep import`)            |
+| **Security**      | Security paths + data flow via `query_graph`              | Changed files + files with auth/crypto/SQL/shell patterns |
+| **Architecture**  | Layer boundaries + imports via `query_graph`/`get_impact` | Changed files + `harness check-deps` output               |
 
 #### 1:1 Context Ratio Rule
 
-For every N lines of diff, gather approximately N lines of surrounding context:
-
-- **Small diffs (<20 lines):** Gather proportionally more context — aim for 3:1 context-to-diff.
-- **Medium diffs (20-200 lines):** Target 1:1 ratio. Read full files containing changes, plus immediate dependencies.
-- **Large diffs (>200 lines):** 1:1 ratio is the floor. Prioritize ruthlessly. Flag large diffs as a review concern.
-
-#### Context Gathering Priority Order
+- **Small diffs (<20 lines):** 3:1 context-to-diff ratio.
+- **Medium diffs (20-200 lines):** 1:1 ratio. Full files + immediate dependencies.
+- **Large diffs (>200 lines):** 1:1 floor. Prioritize ruthlessly. Flag as review concern.
 
-Gather context in this order until the ratio is met:
+#### Context Gathering Priority
 
-1. **Files directly imported/referenced by changed files** — read the modules the changed code calls or depends on.
-2. **Corresponding test files** — find tests for changed code. If tests are missing, note this as a finding.
-3. **Spec/design docs mentioning changed components** — search `docs/changes/`, `docs/design-docs/`, `docs/plans/`.
-4. **Type definitions used by changed code** — read interfaces, types, schemas consumed or produced.
-5. **Recent commits touching the same files** — see Commit History below.
+1. Files directly imported/referenced by changed files
+2. Corresponding test files (note if missing)
+3. Spec/design docs mentioning changed components
+4. Type definitions consumed or produced by changed code
+5. Recent commits touching the same files
 
-#### Graph-Enhanced Context (when available)
+#### Graph-Enhanced Context
 
-When a knowledge graph exists at `.harness/graph/`, use `gather_context` for efficient context assembly:
+When `.harness/graph/` exists, use `gather_context` for efficient assembly:
 
 ```json
 gather_context({
@@ -270,64 +220,44 @@ gather_context({
 })
 ```
 
-This replaces manual `query_graph` + `get_impact` + `find_context_for` calls with a single composite call that assembles review context in parallel, ranked by relevance. Falls back gracefully when no graph is available (`meta.graphAvailable: false`). When `session` is provided (e.g., via autopilot dispatch), learnings and state are scoped to the session directory. If no session is known, omit the parameter — `gather_context` falls back to global files.
-
-For domain-specific scoping (compliance, bug detection, security, architecture), supplement `gather_context` output with targeted `query_graph` calls as needed.
+Replaces manual `query_graph` + `get_impact` + `find_context_for` calls. Falls back gracefully when no graph exists. Supplement with targeted `query_graph` calls for domain-specific scoping.
 
 #### Context Assembly Commands
 
 ```bash
-# 1. Get the diff and measure its size
-git diff --stat HEAD~1          # or the relevant commit range
-git diff HEAD~1 -- <file>       # per-file diff
-
-# 2. Find imports/references in changed files
-grep -n "import\|require\|from " <changed-file>
-
-# 3. Find corresponding test files
-find . -name "*<module-name>*test*" -o -name "*<module-name>*spec*"
-
-# 4. Search for spec/design references
-grep -rl "<component-name>" docs/changes/ docs/design-docs/ docs/plans/
-
-# 5. Find type definitions
+git diff --stat HEAD~1                    # measure diff size
+git diff HEAD~1 -- <file>                 # per-file diff
+grep -n "import\|require\|from " <file>   # find imports
+find . -name "*<module>*test*" -o -name "*<module>*spec*"
+grep -rl "<component>" docs/changes/ docs/design-docs/ docs/plans/
 grep -rn "interface\|type\|schema" <changed-file> | head -20
 ```
 
 #### Commit History Context
 
-Retrieve recent commit history for every affected file:
-
 ```bash
-# Recent commits touching affected files (5 per file)
 git log --oneline -5 -- <affected-file>
 ```
 
-Use commit history to answer:
+Use to determine: **Hotspot?** (3+ changes in last 5 commits) **Recently refactored?** **Multiple authors?** **Last change was bugfix?** (yellow flag)
 
-- **Is this a hotspot?** Changed 3+ times in last 5 commits → volatile, pay extra attention.
-- **Was this recently refactored?** Recent "refactor" commits → check alignment with refactoring direction.
-- **Who has been working here?** Multiple authors → look for conflicting assumptions.
-- **What was the last change?** Bugfix followed by change in same area → yellow flag.
-
-**Exit:** Context bundles are assembled for each of the four review domains. Continue to Phase 4.
+**Exit:** Context bundles assembled for all four domains. Continue to Phase 4.
 
 ---
 
 ### Phase 4: FAN-OUT
 
-**Tier:** mixed (see per-agent tiers below)
-**Purpose:** Run four parallel review subagents, each with domain-scoped context from Phase 3. Each agent produces findings in the `ReviewFinding` schema.
+**Tier:** mixed | **Purpose:** Run four parallel review subagents with domain-scoped context. Each produces `ReviewFinding[]`.
 
 **Rigor overrides:**
 
-- **`fast`:** All four agents run at **fast tier** (haiku-class). Focus areas are unchanged but agents operate with reduced reasoning depth.
-- **`standard`:** Default tier assignments as listed per agent below.
-- **`thorough`:** Default tier assignments + a **meta-judge pass** after all agents return. The meta-judge (strong tier) cross-validates findings across domains: confirms findings cited by multiple agents, flags contradictions, and surfaces cross-cutting concerns that individual agents missed.
+- **`fast`:** All agents at fast tier (haiku-class), reduced reasoning depth.
+- **`standard`:** Default tiers per agent.
+- **`thorough`:** Default tiers + meta-judge pass (strong tier) cross-validating findings, flagging contradictions, surfacing cross-cutting concerns.
 
 #### Compliance Agent (standard tier)
 
-Reviews adherence to project conventions, standards, and documentation requirements.
+Reviews adherence to project conventions, standards, and documentation.
 
 **Input:** Compliance context bundle (convention files + changed files + change type)
 
@@ -335,27 +265,27 @@ Reviews adherence to project conventions, standards, and documentation requireme
 
 _Feature:_
 
-- [ ] **Spec alignment:** Does the implementation match the spec/design doc? Are all specified behaviors present?
-- [ ] **API surface:** Are new public interfaces minimal and well-named? Could any new export be kept internal?
-- [ ] **Backward compatibility:** Does this break existing callers? If so, is the migration path documented?
+- [ ] **Spec alignment:** Implementation matches spec? All specified behaviors present?
+- [ ] **API surface:** New interfaces minimal and well-named? Could exports be kept internal?
+- [ ] **Backward compatibility:** Breaks existing callers? Migration path documented?
 
 _Bugfix:_
 
-- [ ] **Root cause identified:** Does the fix address the root cause, not just the symptom?
-- [ ] **Original issue referenced:** Does the commit or PR reference the bug report or issue number?
-- [ ] **No collateral changes:** Does the fix change only what is necessary?
+- [ ] **Root cause identified:** Addresses root cause, not symptom?
+- [ ] **Original issue referenced:** Commit/PR references bug report?
+- [ ] **No collateral changes:** Only necessary changes?
 
 _Refactor:_
 
-- [ ] **Behavioral equivalence:** Do all existing tests still pass without modification?
-- [ ] **No functionality changes:** Does the refactor introduce any new behavior?
+- [ ] **Behavioral equivalence:** Existing tests pass without modification?
+- [ ] **No functionality changes:** No new behavior introduced?
 
 _Docs:_
 
-- [ ] **Accuracy vs. current code:** Do documented behaviors match what the code actually does?
-- [ ] **Completeness:** Are all public interfaces documented?
-- [ ] **Consistency:** Does new documentation follow existing style and terminology?
-- [ ] **Links valid:** Do all internal links resolve?
+- [ ] **Accuracy:** Documented behaviors match code?
+- [ ] **Completeness:** All public interfaces documented?
+- [ ] **Consistency:** Follows existing style and terminology?
+- [ ] **Links valid:** All internal links resolve?
 
 **Output:** `ReviewFinding[]` with `domain: 'compliance'`
 
@@ -369,14 +299,14 @@ Reviews for logic errors, edge cases, and correctness issues.
 
 **Focus areas:**
 
-- [ ] **Edge cases:** Boundary conditions (empty input, max values, null, concurrent access)
-- [ ] **Error handling:** Errors handled at appropriate level, helpful messages, no silent swallowing
+- [ ] **Edge cases:** Boundary conditions (empty, max, null, concurrent)
+- [ ] **Error handling:** Appropriate level, helpful messages, no silent swallowing
 - [ ] **Logic errors:** Off-by-one, incorrect boolean logic, missing early returns
-- [ ] **Race conditions:** Concurrent access to shared state, missing locks or atomic operations
+- [ ] **Race conditions:** Concurrent shared state access, missing locks/atomics
 - [ ] **Resource leaks:** Unclosed handles, missing cleanup in error paths
-- [ ] **Type safety:** Type mismatches, unsafe casts, missing null checks
-- [ ] **Test coverage:** Tests for happy path, error paths, and edge cases. Coverage meaningful, not just present.
-- [ ] **Regression tests:** For bugfixes — test that would have caught the bug before the fix
+- [ ] **Type safety:** Mismatches, unsafe casts, missing null checks
+- [ ] **Test coverage:** Happy path, error paths, edge cases. Meaningful, not just present.
+- [ ] **Regression tests:** For bugfixes -- test that would have caught the bug
 
 **Output:** `ReviewFinding[]` with `domain: 'bug'`
 
@@ -384,39 +314,33 @@ Reviews for logic errors, edge cases, and correctness issues.
 
 #### Security Agent (strong tier) -- via harness-security-review
 
-Invokes `harness-security-review` in changed-files mode as the security slot in the fan-out.
+Invokes `harness-security-review` in changed-files mode as the security fan-out slot.
 
 **Input:** Security context bundle (security-relevant paths + data flows)
 
-**Invocation:** The pipeline invokes `harness-security-review` with scope `changed-files`. The skill:
-
-- Skips its own Phase 1 (SCAN) -- reads mechanical findings from PipelineContext (Phase 2 already ran `run_security_scan`)
-- Runs Phase 2 (REVIEW) -- OWASP baseline + stack-adaptive on changed files and their direct imports
-- Skips Phase 3 (THREAT-MODEL) unless `--deep` was passed to code review
-- Returns `ReviewFinding[]` with populated security fields (`cweId`, `owaspCategory`, `confidence`, `remediation`, `references`)
+**Invocation:** Pipeline invokes `harness-security-review` with scope `changed-files`:
 
-If `--deep` flag is set on code review, additionally pass `--deep` to `harness-security-review` for threat modeling.
+- Skips Phase 1 (SCAN) -- reads mechanical findings from PipelineContext
+- Runs Phase 2 (REVIEW) -- OWASP baseline + stack-adaptive on changed files
+- Skips Phase 3 (THREAT-MODEL) unless `--deep` was passed
+- Returns `ReviewFinding[]` with security fields (`cweId`, `owaspCategory`, `confidence`, `remediation`, `references`)
 
 **Focus areas:**
 
-1. **Semantic security review** (issues mechanical scanners cannot catch):
-   - User input flowing through multiple functions to dangerous sinks (SQL, shell, HTML)
-   - Missing authorization checks on new or modified endpoints
-   - Sensitive data exposed in logs, error messages, or API responses
-   - Authentication bypass paths introduced by the change
-   - Insecure defaults in new configuration options
+1. **Semantic security review** (beyond mechanical scanners):
+   - Input flowing through multiple functions to dangerous sinks (SQL, shell, HTML)
+   - Missing authorization on new/modified endpoints
+   - Sensitive data in logs, errors, or API responses
+   - Authentication bypass paths
+   - Insecure defaults in new config
 
-2. **Stack-adaptive focus:** Based on the project's tech stack:
-   - Node.js: prototype pollution, ReDoS, path traversal
-   - React: XSS, dangerouslySetInnerHTML, state injection
-   - Go: race conditions, integer overflow, unsafe pointer
-   - Python: pickle deserialization, SSTI, command injection
+2. **Stack-adaptive:** Node.js (prototype pollution, ReDoS, path traversal), React (XSS, dangerouslySetInnerHTML), Go (race conditions, integer overflow, unsafe pointer), Python (pickle, SSTI, command injection)
 
-3. **CWE/OWASP references:** All security findings include `cweId`, `owaspCategory`, and `remediation` fields.
+3. **CWE/OWASP references:** All findings include `cweId`, `owaspCategory`, `remediation`.
 
-Security findings with confirmed vulnerabilities are always `severity: 'critical'`.
+Confirmed vulnerabilities are always `severity: 'critical'`.
 
-**Dedup with mechanical scan:** The pipeline's Phase 5 (VALIDATE) uses the exclusion set from Phase 2 mechanical findings to discard any security-review finding that overlaps with an already-reported mechanical finding. This prevents duplicate reporting of the same issue.
+**Dedup with mechanical scan:** Phase 5 uses the exclusion set from Phase 2 to discard overlapping findings.
 
 **Output:** `ReviewFinding[]` with `domain: 'security'`
 
@@ -424,39 +348,36 @@ Security findings with confirmed vulnerabilities are always `severity: 'critical
 
 #### Architecture Agent (standard tier)
 
-Reviews for architectural violations, dependency direction, and design pattern compliance.
+Reviews architectural violations, dependency direction, and design pattern compliance.
 
 **Input:** Architecture context bundle (layer boundaries + import graph)
 
 **Focus areas:**
 
-- [ ] **Layer compliance:** Does the code respect the project's architectural layers? Are imports flowing in the correct direction?
-- [ ] **Dependency direction:** Do modules depend on abstractions, not concretions? (Dependency Inversion)
-- [ ] **Single Responsibility:** Does each module have one reason to change?
-- [ ] **Open/Closed:** Can behavior be extended without modifying existing code?
-- [ ] **Pattern consistency:** Does the code follow established codebase patterns? If introducing a new pattern, is it justified?
-- [ ] **Separation of concerns:** Business logic separated from infrastructure? Each function/module does one thing?
-- [ ] **DRY violations:** Duplicated logic that should be extracted — but NOT intentional duplication of things that will diverge.
-- [ ] **Performance preserved:** Could restructuring introduce regressions (extra allocations, changed query patterns)?
+- [ ] **Layer compliance:** Imports flowing in correct direction?
+- [ ] **Dependency direction:** Depends on abstractions, not concretions?
+- [ ] **Single Responsibility:** Each module has one reason to change?
+- [ ] **Open/Closed:** Behavior extensible without modifying existing code?
+- [ ] **Pattern consistency:** Follows established patterns? New patterns justified?
+- [ ] **Separation of concerns:** Business logic separated from infrastructure?
+- [ ] **DRY violations:** Duplicated logic to extract -- but NOT intentional duplication that will diverge.
+- [ ] **Performance preserved:** Could restructuring introduce regressions?
 
 **Output:** `ReviewFinding[]` with `domain: 'architecture'`
 
-**Exit:** All four agents have returned their findings. Continue to Phase 5.
+**Exit:** All four agents returned findings. Continue to Phase 5.
 
 ---
 
 ### Phase 5: VALIDATE
 
-**Tier:** none (mechanical)
-**Purpose:** Remove false positives by cross-referencing AI findings against mechanical results and graph reachability.
+**Tier:** none (mechanical) | **Purpose:** Remove false positives via cross-referencing.
 
 **Steps:**
 
-1. **Mechanical exclusion:** For each finding from Phase 4, check if the same file + line range was already flagged by a mechanical check in Phase 2. If so, discard the AI finding — the mechanical check is authoritative and the issue is already reported.
-
-2. **Graph reachability validation (if graph available):** For findings that claim an issue affects other parts of the system (e.g., "this change breaks callers"), verify via `query_graph` that the claimed dependency path exists. Discard findings with invalid reachability claims.
-
-3. **Import-chain heuristic (fallback, no graph):** Follow imports 2 levels deep from the flagged file. If the finding claims impact on a file not reachable within 2 import hops, downgrade severity to `suggestion` rather than discarding.
+1. **Mechanical exclusion:** Discard AI findings where same file + line range already flagged by Phase 2.
+2. **Graph reachability (if available):** Verify claimed dependency paths via `query_graph`. Discard findings with invalid reachability claims.
+3. **Import-chain heuristic (fallback):** Follow imports 2 levels deep. If claimed impact unreachable within 2 hops, downgrade to `suggestion`.
 
 **Exit:** Validated finding set. Continue to Phase 6.
 
@@ -464,100 +385,52 @@ Reviews for architectural violations, dependency direction, and design pattern c
 
 ### Phase 6: DEDUP + MERGE
 
-**Tier:** none (mechanical)
-**Purpose:** Eliminate redundant findings across agents and produce the final finding list.
+**Tier:** none (mechanical) | **Purpose:** Eliminate redundant findings across agents.
 
 **Steps:**
 
-1. **Group by location:** Group findings by `file` + overlapping `lineRange`. Two findings overlap if their line ranges intersect or are within 3 lines of each other.
-
-2. **Merge overlapping findings:** When multiple agents flag the same location:
-   - Keep the highest `severity` from any agent
-   - Combine `evidence` arrays from all agents
-   - Preserve the `rationale` with the strongest justification
-   - Merge `domain` tags (a finding can be both `bug` and `security`)
-   - Generate a single merged `id`
-
+1. **Group by location:** Group by `file` + overlapping `lineRange` (intersecting or within 3 lines).
+2. **Merge overlapping findings:** Keep highest severity, combine evidence arrays, preserve strongest rationale, merge domain tags, generate merged ID.
 3. **Assign final severity:**
-   - **Critical** — Must fix before merge. Bugs, security vulnerabilities, failing harness checks, architectural violations that break boundaries.
-   - **Important** — Should fix before merge. Missing error handling, missing tests for critical paths, unclear naming.
-   - **Suggestion** — Consider for improvement. Style preferences, minor optimizations, alternative approaches. Does not block merge.
+   - **Critical** — Must fix. Bugs, security vulns, failing harness checks, boundary violations.
+   - **Important** — Should fix. Missing error handling, missing critical-path tests, unclear naming.
+   - **Suggestion** — Consider. Style, minor optimizations, alternatives. Does not block merge.
 
-**Exit:** Deduplicated, severity-assigned finding list. Continue to Phase 7.
+**Exit:** Deduplicated, severity-assigned list. Continue to Phase 7.
 
 ---
 
 ### Phase 7: OUTPUT
 
-**Tier:** none
-**Purpose:** Deliver the review in the requested format.
+**Tier:** none | **Purpose:** Deliver review in requested format.
 
 #### Text Output (default)
 
-When rendering the review output, use conventional markdown patterns:
-
-For strengths:
-
 ```
 **[STRENGTH]** Clean separation between route handler and service logic
-```
-
-For issues by severity:
-
-```
-**[CRITICAL]** api/routes/users.ts:12-15 — Direct import from db/queries.ts bypasses service layer
-**[IMPORTANT]** services/user-service.ts:45 — createUser does not handle duplicate email
+**[CRITICAL]** api/routes/users.ts:12-15 -- Direct import from db/queries.ts bypasses service layer
+**[IMPORTANT]** services/user-service.ts:45 -- createUser does not handle duplicate email
 **[SUGGESTION]** Consider extracting validation into a shared utility
 ```
 
-Structure the review as:
-
-**Strengths:** What is done well. Be specific. "Clean separation between X and Y" is useful. "Looks good" is not.
-
-**Issues:** List each finding from Phase 6, grouped by severity:
+**Strengths:** What is done well. Be specific -- "Clean separation between X and Y" not "Looks good".
 
-- **Critical:** [findings with severity 'critical']
-- **Important:** [findings with severity 'important']
-- **Suggestion:** [findings with severity 'suggestion']
+**Issues:** Grouped by severity (Critical / Important / Suggestion). Each includes: location, problem, rationale, suggested fix.
 
-For each issue, provide:
+**Assessment:** Approve (no critical/important), Request Changes (critical/important present), or Comment (observations only).
 
-1. The specific location (file and line range)
-2. What the problem is (title)
-3. Why it matters (rationale)
-4. A suggested fix (if available)
-
-**Assessment:** One of:
-
-- **Approve** — No critical or important issues. Ready to merge.
-- **Request Changes** — Critical or important issues must be addressed.
-- **Comment** — Observations only, no blocking issues.
-
-**Learnings Applied (thorough mode only):** When `rigorLevel` is `thorough`, append a "Learnings Applied" section after the Assessment:
-
-```
-**Learnings Applied:**
-- [0.85] "Useful Finding: Missing error handling in service layer" — boosted priority for error handling checks
-- [0.72] "Noise: Style-only import ordering" — suppressed import order findings
-```
-
-Each entry shows the Jaccard relevance score and how the learning influenced the review. This section is omitted in `fast` and `standard` modes.
+**Learnings Applied (thorough only):** List learnings with Jaccard scores and how they influenced review. Omitted in fast/standard.
 
 **Exit code:** 0 for Approve/Comment, 1 for Request Changes.
 
-#### Inline GitHub Comments (`--comment` flag)
-
-When `--comment` is set, post findings as inline PR comments via `gh` CLI or GitHub MCP:
+#### Inline GitHub Comments (`--comment`)
 
-- **Small fixes** (suggestion is < 10 lines): Post as committable suggestion block using GitHub's suggestion syntax.
-- **Large fixes** (suggestion is >= 10 lines or no concrete suggestion): Post description + rationale as a regular comment.
-- **Summary comment:** Post the Strengths/Issues/Assessment as a top-level PR review comment.
+- **Small fixes** (<10 lines): Committable suggestion block.
+- **Large fixes** (>=10 lines or no concrete suggestion): Description + rationale comment.
+- **Summary:** Top-level PR review comment with Strengths/Issues/Assessment.
 
 ```bash
-# Post a review with inline comments
 gh pr review --event APPROVE|REQUEST_CHANGES|COMMENT --body "<summary>"
-
-# Post inline comment with suggestion
 gh api repos/{owner}/{repo}/pulls/{pr}/comments \
   --field body="<rationale>\n\`\`\`suggestion\n<fix>\n\`\`\`" \
   --field path="<file>" --field line=<line>
@@ -565,8 +438,6 @@ gh api repos/{owner}/{repo}/pulls/{pr}/comments \
 
 ### Review Acceptance
 
-After delivering the review output, request acceptance:
-
 ```json
 emit_interaction({
   path: "<project-root>",
@@ -574,17 +445,20 @@ emit_interaction({
   confirmation: {
     text: "Review complete: <Assessment>. Accept review?",
     context: "<N critical, N important, N suggestion findings>",
-    impact: "Accepting the review finalizes findings. If 'approve', ready for merge. If 'request-changes', fixes are needed.",
-    risk: "<low if approve, high if critical findings>"
+    impact: "Accepting finalizes findings. Approve = ready for merge. Request-changes = fixes needed.",
+    risk: "<low if approve, high if critical>"
   }
 })
 ```
 
 #### Handoff and Transition
 
-After delivering the review output, write the handoff and conditionally transition:
+Write handoff to the session-scoped path when session slug is known, otherwise fall back to global:
 
-Write `.harness/handoff.json`:
+- Session-scoped (preferred): `.harness/sessions/<session-slug>/handoff.json`
+- Global (fallback, **deprecated**): `.harness/handoff.json`
+
+> **[DEPRECATED]** Writing to `.harness/handoff.json` is deprecated. In autopilot sessions, always write to `.harness/sessions/<slug>/handoff.json`.
 
 ```json
 {
@@ -597,25 +471,21 @@ Write `.harness/handoff.json`:
 }
 ```
 
-**Write session summary (if session is known).** If running within a session context, update the session summary:
+**Write session summary (if session known):**
 
 ```json
 writeSessionSummary(projectPath, sessionSlug, {
   session: "<session-slug>",
   lastActive: "<ISO timestamp>",
   skill: "harness-code-review",
-  status: "Review complete. Assessment: <approve|request-changes|comment>. <N> findings.",
   spec: "<spec path if known>",
+  status: "Review complete. Assessment: <type>. <N> findings.",
   keyContext: "<1-2 sentences: review outcome, key findings>",
-  nextStep: "<e.g., Address blocking findings / Ready to merge / Observations delivered>"
+  nextStep: "<Address findings / Ready to merge / Observations delivered>"
 })
 ```
 
-If no session slug is known, skip this step.
-
-**If assessment is "approve":**
-
-Call `emit_interaction`:
+**If "approve":** Emit transition:
 
 ```json
 {
@@ -626,7 +496,7 @@ Call `emit_interaction`:
     "reason": "Review approved with no blocking issues",
     "artifacts": ["<reviewed files>"],
     "requiresConfirmation": true,
-    "summary": "Review approved. <N> suggestions noted. Ready to create PR or merge.",
+    "summary": "Review approved. <N> suggestions. Ready for PR/merge.",
     "qualityGate": {
       "checks": [
         { "name": "mechanical-checks", "passed": true },
@@ -640,144 +510,110 @@ Call `emit_interaction`:
 }
 ```
 
-If the user confirms: proceed to create PR or merge.
-If the user declines: stop. The handoff is written for future invocation.
-
-**If assessment is "request-changes":**
+If user confirms: proceed to create PR or merge. If user declines: stop.
 
-Do NOT emit a transition. Surface the critical and important findings to the user for resolution. After fixes are applied, re-run the review pipeline.
+**If "request-changes":** Do NOT emit transition. Surface critical/important findings for resolution. Re-run after fixes.
 
-**If assessment is "comment":**
-
-Do NOT emit a transition. Observations have been delivered. No further action is implied.
+**If "comment":** Do NOT emit transition. Observations delivered, no further action implied.
 
 ---
 
 ## Role A: Requesting a Review
 
-_This section is not part of the pipeline. It documents the process for requesting a review from others._
-
-When you have completed work and need it reviewed:
+_Not part of the pipeline. Documents the process for requesting reviews._
 
-1. **Prepare the review context:**
-   - Commit range (exact SHAs or branch diff)
-   - Description (WHAT changed and WHY — not a commit-by-commit retelling)
-   - Plan reference (link to spec/plan if applicable)
-   - Test evidence (`harness validate` and test suite results)
-   - Harness check results (`harness validate`, `harness check-deps`)
-
-2. **Dispatch the review:** Identify the right reviewer, provide the context package, state what kind of feedback you want.
-
-3. **Wait.** Do not modify code under review. Note issues but do not push fixes until review is complete.
+1. **Prepare context:** Commit range, description (WHAT and WHY), plan reference, test evidence, harness check results.
+2. **Dispatch:** Identify reviewer, provide context, state what feedback you want.
+3. **Wait.** Do not modify code under review.
 
 ---
 
 ## Role C: Responding to Review Feedback
 
-_This section is not part of the pipeline. It documents the process for responding to review feedback._
-
-1. **Read all feedback first.** Understand the full picture before responding.
-
-2. **Verify before implementing.** For each piece of feedback:
-   - Do you understand it? If not, ask for clarification.
-   - Is it correct? Verify the claim — reviewers make mistakes too.
-   - Is it actionable? Vague feedback requires clarification.
+_Not part of the pipeline. Documents the process for responding to feedback._
 
+1. **Read all feedback first.** Understand full picture before responding.
+2. **Verify before implementing:** Understand it? Is it correct? Is it actionable?
 3. **Technical rigor over social performance:**
-   - Do NOT agree with feedback just to be agreeable. Push back with evidence if wrong.
+   - Do NOT agree just to be agreeable. Push back with evidence if wrong.
    - Do NOT implement every suggestion. Apply YAGNI.
-   - Do NOT make changes you do not understand. Ask for explanation.
-   - DO acknowledge when feedback is correct.
-   - DO push back when feedback contradicts the approved plan/spec.
-
-4. **Implement fixes:** For each accepted piece of feedback: make the change, run tests, run `harness validate` and `harness check-deps`, commit with a message referencing the review feedback.
-
-5. **Re-request review** with summary of changes, which feedback was addressed vs. pushed back on, and fresh harness check results.
+   - Do NOT make changes you do not understand. Ask.
+   - DO acknowledge correct feedback.
+   - DO push back when feedback contradicts approved plan/spec.
+4. **Implement fixes:** Change, test, run `harness validate` and `harness check-deps`, commit referencing feedback.
+5. **Re-request review** with change summary, addressed vs. pushed-back items, fresh harness results.
 
 ---
 
 ## Evidence Requirements
 
-When this skill produces review findings, every finding MUST include evidence citations. The `ReviewFinding.evidence` array field already exists in the finding schema -- this section defines the citation standard for populating it.
+Every `ReviewFinding.evidence` array MUST include citations using one of:
 
-Every review finding MUST cite evidence using one of:
+1. **File reference:** `file:line` format (e.g., `src/api/routes/users.ts:12-15` -- "bypasses service layer")
+2. **Diff evidence:** Before/after code with file path and line numbers
+3. **Dependency chain:** Import path showing violation (e.g., `routes/users.ts:3 imports db/queries.ts`)
+4. **Test evidence:** Test command and output for test-related findings
+5. **Convention reference:** Specific convention file and rule (e.g., `AGENTS.md:45`)
+6. **Session evidence:** Write to `evidence` session section via `manage_state`
 
-1. **File reference:** `file:line` format (e.g., `src/api/routes/users.ts:12-15` -- "direct import from db/queries.ts bypasses service layer")
-2. **Diff evidence:** Before/after code from the PR diff with file path and line numbers
-3. **Dependency chain:** Import path showing the violation (e.g., `routes/users.ts:3 imports db/queries.ts` -- "violates routes -> services -> db layer direction")
-4. **Test evidence:** Include test command and output when findings relate to missing or failing tests
-5. **Convention reference:** Cite the specific convention file and rule (e.g., `AGENTS.md:45` -- "convention requires services layer between routes and db")
-6. **Session evidence:** Write significant findings to the `evidence` session section:
-   ```json
-   manage_state({
-     action: "append_entry",
-     session: "<current-session>",
-     section: "evidence",
-     authorSkill: "harness-code-review",
-     content: "src/api/routes/users.ts:12-15 -- layer violation: direct import from db/queries.ts"
-   })
-   ```
+**When to cite:** Phase 4 (each subagent populates evidence), Phase 5 (evidence verifies reachability), Phase 7 (every issue backed by evidence).
 
-**When to cite:** In Phase 4 (FAN-OUT), each subagent populates the `evidence` array in every `ReviewFinding`. In Phase 5 (VALIDATE), evidence is used to verify reachability claims. In Phase 7 (OUTPUT), every issue in the review includes its file:line location and rationale backed by evidence.
-
-**Uncited claims:** Review findings without evidence in the `evidence` array are discarded during Phase 5 (VALIDATE). Observations that cannot be tied to specific file:line references MUST be prefixed with `[UNVERIFIED]` and downgraded to `severity: 'suggestion'`.
+**Uncited claims:** Findings without evidence discarded in Phase 5. Observations without file:line references prefixed `[UNVERIFIED]` and downgraded to `suggestion`.
 
 ## Harness Integration
 
-- **`assess_project`** — Used in Phase 2 (MECHANICAL) to run `validate`, `deps`, and `docs` checks in parallel. Must pass for the pipeline to continue to AI review. Failures are Critical issues that stop the pipeline.
-- **`gather_context`** — Used in Phase 3 (CONTEXT) for efficient parallel context assembly. The `session` parameter scopes learnings and state to the session directory when provided by autopilot dispatch. Replaces separate graph query calls.
-- **`harness cleanup`** — Optional check during Phase 2 for entropy accumulation in changed files.
-- **Graph queries** — Used in Phase 3 (CONTEXT) for dependency-scoped context and in Phase 5 (VALIDATE) for reachability verification. Graceful fallback when no graph exists.
-- **`emit_interaction`** -- Call after review approval to suggest transitioning to merge/PR creation. Only emitted on APPROVE assessment. Uses confirmed transition (waits for user approval).
-- **Rigor levels** — `--fast` / `--thorough` flags control learnings integration and agent tiers. Fast skips learnings and runs all agents at fast tier. Standard includes learnings if available. Thorough always loads learnings, runs a meta-judge pass, and includes a "Learnings Applied" section in output. See the Rigor Levels table for details.
-- **`filterByRelevance`** — Used in the Review Learnings Calibration section (Phase 3) to score learnings against diff context. Threshold 0.7, token budget 1000. From `packages/core/src/state/learnings-relevance.ts`.
+- **`assess_project`** — Phase 2: run validate/deps/docs in parallel. Failures are Critical and stop pipeline.
+- **`gather_context`** — Phase 3: parallel context assembly. Session parameter scopes to session directory.
+- **`harness cleanup`** — Optional Phase 2 check for entropy in changed files.
+- **Graph queries** — Phase 3 (dependency context) and Phase 5 (reachability verification). Graceful fallback.
+- **`emit_interaction`** — Post-review: suggest merge transition on APPROVE. Confirmed transition.
+- **Rigor levels** — `--fast`/`--thorough` control learnings, agent tiers, output. See Rigor Levels table.
+- **`filterByRelevance`** — Phase 3 learnings scoring. Threshold 0.7, budget 1000 tokens.
+- **Session directory** — `.harness/sessions/<slug>/` contains `handoff.json`, `state.json`, `artifacts.json` (spec/plan paths, reviewed file list). Write handoff to session scope when slug is known. Global `.harness/handoff.json` is deprecated for session-aware invocations.
 
 ## Success Criteria
 
-- The pipeline runs all 7 phases in order when invoked manually (skipping GATE)
-- The pipeline runs all 7 phases including GATE when invoked with `--ci`
-- Mechanical failures in Phase 2 stop the pipeline before AI review (Phase 4)
-- Each Phase 4 subagent receives only its domain-scoped context, not the full diff
-- All findings use the ReviewFinding schema
-- Mechanical findings from Phase 2 are excluded from Phase 4 output in Phase 5
-- Cross-agent duplicate findings are merged in Phase 6
-- Text output uses Strengths/Issues/Assessment format with Critical/Important/Suggestion severity
-- `--comment` posts inline GitHub comments with committable suggestion blocks for small fixes
-- `--deep` adds threat modeling to the Security agent
-- No code merges with Critical issues unresolved
-- No code merges with failing harness checks
-- Response to feedback (Role C) is verified before implementation
-- Pushback on incorrect feedback is evidence-based
-- When `rigorLevel` is `fast`, learnings integration is skipped and all fan-out agents run at fast tier
-- When `rigorLevel` is `thorough`, learnings are always loaded and scored, a meta-judge validates cross-domain findings, and a "Learnings Applied" section appears in the output
-- When `rigorLevel` is `standard`, learnings are included if `.harness/review-learnings.md` exists, scored via `filterByRelevance` at 0.7 threshold
-- When all learnings score below 0.7 threshold, zero learnings are included (no fallback to unscored inclusion)
+- Pipeline runs all 7 phases in order (skipping GATE without `--ci`)
+- Mechanical failures in Phase 2 stop pipeline before AI review
+- Each Phase 4 subagent receives only domain-scoped context
+- All findings use ReviewFinding schema
+- Mechanical findings excluded from Phase 4 output in Phase 5
+- Cross-agent duplicates merged in Phase 6
+- Text output uses Strengths/Issues/Assessment with Critical/Important/Suggestion
+- `--comment` posts inline GitHub comments with committable suggestions
+- `--deep` adds threat modeling to Security agent
+- No code merges with Critical issues or failing harness checks
+- Role C feedback verified before implementation; pushback is evidence-based
+- `fast`: learnings skipped, all agents at fast tier
+- `thorough`: learnings always loaded/scored, meta-judge validates, "Learnings Applied" in output
+- `standard`: learnings included if file exists, scored at 0.7 threshold
+- Zero learnings below threshold means zero included (no unscored fallback)
 
 ## Examples
 
 ### Example: Pipeline Review of a New API Endpoint
 
-**Phase 1 (GATE):** Skipped — manual invocation.
+**Phase 1 (GATE):** Skipped -- manual invocation.
 
-**Phase 2 (MECHANICAL):** `harness validate` passes. `harness check-deps` passes. Security scan finds no issues. `tsc --noEmit` passes. Lint passes.
+**Phase 2 (MECHANICAL):** `harness validate` passes. `harness check-deps` passes. Security scan clean. `tsc --noEmit` passes. Lint passes.
 
-**Phase 3 (CONTEXT):** Change type detected as `feature` (commit prefix `feat:`). Context bundles assembled:
+**Phase 3 (CONTEXT):** Change type: `feature` (prefix `feat:`). Bundles:
 
 - Compliance: `CLAUDE.md` + changed files
 - Bug detection: `api/routes/users.ts`, `services/user-service.ts`, `db/queries.ts`
 - Security: `api/routes/users.ts` (endpoint), `services/user-service.ts` (data flow)
-- Architecture: import graph showing `routes → services → db` layers
+- Architecture: import graph showing `routes -> services -> db` layers
 
-**Phase 4 (FAN-OUT):** Four agents run in parallel:
+**Phase 4 (FAN-OUT):** Four agents in parallel:
 
-- Compliance agent: 0 findings (spec alignment confirmed)
-- Bug detection agent: 1 finding (missing duplicate email handling in createUser)
-- Security agent: 0 findings (no vulnerabilities detected)
-- Architecture agent: 1 finding (routes/users.ts imports directly from db/queries.ts)
+- Compliance: 0 findings (spec alignment confirmed)
+- Bug detection: 1 finding (missing duplicate email handling in createUser)
+- Security: 0 findings
+- Architecture: 1 finding (routes/users.ts imports directly from db/queries.ts)
 
-**Phase 5 (VALIDATE):** No mechanical exclusions apply. Architecture finding validated by `check-deps` output showing layer violation.
+**Phase 5 (VALIDATE):** No mechanical exclusions. Architecture finding validated by `check-deps` showing layer violation.
 
-**Phase 6 (DEDUP+MERGE):** No overlaps — 2 distinct findings in different files.
+**Phase 6 (DEDUP+MERGE):** No overlaps -- 2 distinct findings in different files.
 
 **Phase 7 (OUTPUT):**
 
@@ -791,43 +627,38 @@ Every review finding MUST cite evidence using one of:
 
 **Critical:**
 
-- `api/routes/users.ts:12-15` — Direct import from `db/queries.ts` bypasses service layer. Must route through `services/user-service.ts`. (domain: architecture, validatedBy: heuristic)
+- `api/routes/users.ts:12-15` -- Direct import from `db/queries.ts` bypasses service layer. Must route through `services/user-service.ts`. (domain: architecture, validatedBy: heuristic)
 
 **Important:**
 
-- `services/user-service.ts:45` — `createUser` does not handle duplicate email. Database will throw constraint violation surfacing as 500. Should catch and return 409. (domain: bug, validatedBy: heuristic)
+- `services/user-service.ts:45` -- `createUser` does not handle duplicate email. Database throws constraint violation surfacing as 500. Should catch and return 409. (domain: bug, validatedBy: heuristic)
 
 **Suggestion:** (none)
 
-**Assessment:** Request Changes — one critical layer violation and one important missing error handler.
+**Assessment:** Request Changes -- one critical layer violation and one important missing error handler.
 
 ## Gates
 
-- **Never skip mechanical checks without `--no-mechanical`.** If mechanical checks have not run (in CI or locally), they must run in Phase 2 before AI review.
-- **Never merge with failing harness checks.** `harness validate` and `harness check-deps` must pass. This is a Critical issue, always.
-- **Never implement feedback without verification.** Before changing code based on review feedback, verify the feedback is correct. Run the scenario. Read the code. Do not blindly comply.
-- **Never agree performatively.** "Sure, I'll change that" without understanding why is forbidden. Every change must be understood.
-- **Never skip the YAGNI check.** Every suggestion must answer: "Does this serve a current, concrete need?" Speculative improvements are rejected.
+- **Never skip mechanical checks without `--no-mechanical`.** If not run in CI or locally, they must run in Phase 2 before AI review.
+- **Never merge with failing harness checks.** `harness validate` and `harness check-deps` must pass. Always Critical.
+- **Never implement feedback without verification.** Verify correctness before changing code. Do not blindly comply.
+- **Never agree performatively.** "Sure, I'll change that" without understanding is forbidden.
+- **Never skip the YAGNI check.** Every suggestion must serve a current, concrete need. Speculative improvements rejected.
 
 ## Red Flags
 
 ### Universal
 
-These apply to ALL skills. If you catch yourself doing any of these, STOP.
-
-- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
-  reference. Belief is not evidence.
-- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
-  Search the codebase first. The project may already have a convention.
-- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
-  but do not expand scope beyond the stated task.
+- **"I believe the codebase does X"** -- Stop. Read code, cite file:line. Belief is not evidence.
+- **"Let me recommend [pattern]"** without checking existing patterns -- Stop. Search codebase first.
+- **"While we're here, we should also..."** -- Stop. Flag the idea but do not expand scope.
 
 ### Domain-Specific
 
-- **"The change looks reasonable, approving"** — Stop. Have you read every changed file? Approval without full review is rubber-stamping.
-- **"Let me fix this issue I found"** — Stop. Review identifies issues; it does not fix them. Suggest the fix, do not apply it.
-- **"This is a minor style issue"** — Stop. Is it a style issue or a readability/maintainability concern? Classify accurately before dismissing.
-- **"The author probably meant to..."** — Stop. Do not infer intent. If the code is ambiguous, flag it as a question for the author.
+- **"The change looks reasonable, approving"** -- Stop. Read every changed file. Approval without full review is rubber-stamping.
+- **"Let me fix this issue I found"** -- Stop. Review identifies; it does not fix. Suggest the fix.
+- **"This is a minor style issue"** -- Stop. Style or readability/maintainability? Classify accurately.
+- **"The author probably meant to..."** -- Stop. Do not infer intent. Flag ambiguity as a question.
 
 ## Rationalizations to Reject
 
@@ -839,9 +670,9 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Escalation
 
-- **When reviewers disagree:** If two reviewers give contradictory feedback, escalate to the human or tech lead.
-- **When review feedback changes the plan:** If feedback requires altering the approved plan or spec, pause the review. The plan must be updated first.
-- **When you cannot reproduce a reported issue:** Ask the reviewer for exact reproduction steps.
-- **When review is taking more than 2 rounds:** Something is fundamentally misaligned. Stop and discuss the approach synchronously.
-- **When harness checks fail and you believe the check is wrong:** Do not override or skip. File an issue against the harness configuration.
-- **When the pipeline produces a false positive after validation:** Add the pattern to `.harness/review-learnings.md` in the Noise / False Positives section for future calibration.
+- **When reviewers disagree:** Escalate to the human or tech lead.
+- **When review feedback changes the plan:** Pause review. Plan must be updated first.
+- **When you cannot reproduce a reported issue:** Ask reviewer for exact reproduction steps.
+- **When review takes more than 2 rounds:** Something is fundamentally misaligned. Stop and discuss synchronously.
+- **When harness checks fail and you believe the check is wrong:** Do not override or skip. File an issue against harness config.
+- **When pipeline produces a false positive after validation:** Add pattern to `.harness/review-learnings.md` Noise / False Positives section.