@harness-engineering/cli 1.24.3 → 1.25.1

package/dist/agents/skills/codex/harness-skill-authoring/SKILL.md

@@ -273,6 +273,40 @@ metadata: # Provenance and authorship metadata
 
 3. **Test by running the skill:** `harness skill run <name>`. Verify it loads correctly and the process instructions make sense in context.
 
+### Phase 5B: TDD FOR SKILLS — Test Before Signing Off
+
+Apply test-driven thinking to skill authoring. A skill is not complete until it has been tested against scenarios that exercise its discipline sections.
+
+1. **Write a test scenario.** Before declaring the skill complete, define 2-3 concrete scenarios that should trigger the skill's discipline mechanisms:
+   - One scenario that should trigger a Red Flag (if the skill has Red Flags)
+   - One scenario that should trigger a Rationalization rejection
+   - One scenario that should trigger a Gate (for rigid skills)
+
+   ```markdown
+   ## Skill Test Scenarios
+
+   ### Scenario 1: Red Flag — [quoted phrase from Red Flags section]
+
+   Input: [describe the situation]
+   Expected: Agent stops, cites the Red Flag, and takes corrective action
+
+   ### Scenario 2: Rationalization — [quoted phrase from Rationalizations section]
+
+   Input: [describe the tempting shortcut]
+   Expected: Agent rejects the rationalization and follows the prescribed process
+
+   ### Scenario 3: Gate — [gate condition]
+
+   Input: [describe a state that violates the gate]
+   Expected: Agent halts and does not proceed past the gate
+   ```
+
+2. **Mentally execute each scenario.** Walk through the skill's process with the test input. Does the skill's prose clearly direct the agent to the correct behavior? If not, the skill needs revision — not the test.
+
+3. **Check for gaps.** If you cannot construct a scenario that triggers a discipline section, the section may be too abstract. Revise it to include a concrete quoted phrase or condition.
+
+4. **Document test scenarios** in a comment block at the end of SKILL.md or in a companion `tests.md` file. These serve as regression tests for future skill edits.
+
 ### Skill Quality Checklist
 
 Evaluate every skill along two dimensions:
@@ -312,13 +346,14 @@ Use this checklist as a final quality gate before declaring a skill complete.
 
 ## Rationalizations to Reject
 
-| Rationalization                                                         | Reality                                                                                                                                  |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| "This skill is too simple to need all required sections"                | Every section exists for a reason. A short section is fine; a missing section means the skill was not fully thought through.             |
-| "The process section covers it — no need for explicit success criteria" | Process describes what to do. Success criteria describe how to know it worked. They serve different purposes.                            |
-| "Rationalizations to Reject is meta — this skill does not need it"      | This section is required for all user-facing skills, including this one. No exceptions.                                                  |
-| "I will add examples later once the skill is proven"                    | Examples are a required section. A skill without examples forces the agent to guess at correct behavior. Write at least one example now. |
-| "The When to Use section is obvious from the name"                      | Negative conditions (when NOT to use) prevent misapplication. The skill name conveys nothing about boundary conditions.                  |
+| Rationalization                                                         | Reality                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This skill is too simple to need all required sections"                | Every section exists for a reason. A short section is fine; a missing section means the skill was not fully thought through.                                                                             |
+| "The process section covers it — no need for explicit success criteria" | Process describes what to do. Success criteria describe how to know it worked. They serve different purposes.                                                                                            |
+| "Rationalizations to Reject is meta — this skill does not need it"      | This section is required for all user-facing skills, including this one. No exceptions.                                                                                                                  |
+| "I will add examples later once the skill is proven"                    | Examples are a required section. A skill without examples forces the agent to guess at correct behavior. Write at least one example now.                                                                 |
+| "The When to Use section is obvious from the name"                      | Negative conditions (when NOT to use) prevent misapplication. The skill name conveys nothing about boundary conditions.                                                                                  |
+| "The skill works — I tested it by running it once"                      | A single happy-path run does not test discipline sections. Write scenarios that trigger Red Flags, Gates, and Rationalizations. A skill that passes happy path but fails discipline scenarios is a trap. |
 
 ## Examples
 

package/dist/agents/skills/codex/harness-verification/SKILL.md

@@ -259,6 +259,31 @@ Every verification claim MUST use one of:
 
 **Uncited claims:** Any verification assertion without direct evidence is a verification failure. This skill does not use `[UNVERIFIED]` -- if evidence cannot be produced, verdict is FAIL or INCOMPLETE.
 
+## Rubric Compression
+
+Verification checklists passed to subagents or used internally MUST use compressed single-line format. Each check is one line with pipe-delimited fields:
+
+```
+level|check-name|pass-criterion
+```
+
+**Example (Level 2 SUBSTANTIVE rubric):**
+
+```
+L2|no-stubs|No TODO/FIXME/throw-not-implemented in production code
+L2|no-empty-bodies|No empty function bodies, () => {}, or return null as sole logic
+L2|spec-complete|All behaviors specified in spec have corresponding implementation
+L2|real-logic|Functions contain meaningful logic, not just hardcoded returns
+```
+
+**Why:** Verbose checklist prose inflates verification context without improving accuracy. Dense single-line rubrics give the same signal in fewer tokens, leaving more budget for reading and analyzing actual file content.
+
+**Rules:**
+
+- Level prefix must be L1 (EXISTS), L2 (SUBSTANTIVE), or L3 (WIRED)
+- Maximum 80 characters per criterion text
+- Rubric entries are guidance — the verification levels define the authoritative checks
+
 ## Non-Determinism Tolerance
 
 Mechanical checks (tests, lint, types) are binary pass/fail. No tolerance.

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

@@ -47,7 +47,9 @@ Store answers in: .harness/architecture/<topic>/discovery.md
 
 ---
 
-### Phase 2: ANALYZE — Research the Codebase
+### Phase 2: ANALYZE — Research the Codebase (Read-Only)
+
+**Read-only research constraint:** This phase is discovery, not solution design. You may read files, search patterns, trace dependencies, and record observations. You may NOT propose solutions, recommend approaches, or evaluate trade-offs. If you catch yourself writing "we could..." or "one option is...", STOP — you have left research mode. Save solutions for Phase 3.
 
 Read the codebase to understand the current state. Do not propose solutions yet — gather facts.
 
@@ -272,6 +274,7 @@ Also link from the project's ADR index if one exists.
 - **Always 2-3 options.** Never present 1 option (that is a directive, not advice). Never present more than 3 (that causes paralysis).
 - **No implementation in this skill.** If you write production code, you have broken the advisory boundary. Stop and return to presenting options.
 - **Trade-offs must be honest.** Every option has downsides. If you cannot articulate the cons of an option, you do not understand it well enough to recommend it.
+- **No solutions in Phase 2.** Phase 2 is read-only research. Observations and facts only. Solutions belong in Phase 3. Mixing discovery with solution design anchors on the first idea found.
 
 ## Evidence Requirements
 
@@ -309,11 +312,12 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
-| Rationalization                   | Reality                                                                                             |
-| --------------------------------- | --------------------------------------------------------------------------------------------------- |
-| "This will be easier to maintain" | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase. |
-| "It's the modern approach"        | Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.            |
-| "Other teams do it this way"      | Other teams have different constraints. Evaluate the option on this codebase's specific merits.     |
+| Rationalization                                              | Reality                                                                                                                                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This will be easier to maintain"                            | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase.                                                                       |
+| "It's the modern approach"                                   | Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.                                                                                  |
+| "Other teams do it this way"                                 | Other teams have different constraints. Evaluate the option on this codebase's specific merits.                                                                           |
+| "I can see the solution already, no need to finish research" | Premature convergence anchors on the first viable option. Complete Phase 2 research before proposing anything in Phase 3. The best option may not be the first one found. |
 
 ## Escalation
 

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

@@ -24,6 +24,12 @@ When no arguments are provided (standalone invocation), session slug is unknown
 
 ## Process
 
+### Iron Law
+
+**Review identifies issues. Review never fixes them.**
+
+A reviewer who applies fixes is no longer reviewing — they are editing with reviewer authority and no review. Suggest the fix in the finding. Do not apply it. If you catch yourself writing production code during review, STOP. You have crossed the boundary.
+
 The review runs as a 7-phase pipeline. Each phase has a clear input, output, and exit condition.
 
 ```
@@ -560,6 +566,32 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 
 **Uncited claims:** Findings without evidence discarded in Phase 5. Observations without file:line references prefixed `[UNVERIFIED]` and downgraded to `suggestion`.
 
+## Rubric Compression
+
+Review rubrics passed to subagents in Phase 4 MUST use compressed single-line format to minimize token consumption. Each rubric entry is one line with pipe-delimited fields:
+
+```
+domain|check-name|severity|one-sentence-criterion
+```
+
+**Example (Compliance Agent rubric):**
+
+```
+compliance|spec-alignment|critical|Implementation matches all behaviors specified in the approved spec
+compliance|api-surface|important|New exports are minimal and well-named; internal symbols stay unexported
+compliance|backward-compat|critical|No breaking changes to existing callers without documented migration path
+compliance|naming|suggestion|Names follow project conventions (check AGENTS.md or .eslintrc)
+```
+
+**Why:** Verbose rubric prose inflates context by 2-5x without improving review accuracy. Dense single-line rubrics give the agent the same signal in fewer tokens, leaving more budget for actual code analysis.
+
+**Rules:**
+
+- Maximum 80 characters per criterion text
+- Domain must match the subagent's scope (compliance, bug, security, architecture)
+- Severity must be one of: critical, important, suggestion
+- Rubric entries are guidance, not exhaustive — agents may surface findings outside the rubric
+
 ## Harness Integration
 
 - **`assess_project`** — Phase 2: run validate/deps/docs in parallel. Failures are Critical and stop pipeline.
@@ -644,6 +676,7 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 - **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.
+- **Never apply fixes during review.** Review output is findings, not code changes. Suggest fixes in finding text; never edit production code. Iron Law violation.
 
 ## Red Flags
 
@@ -659,14 +692,16 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 - **"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.
+- **Comment replacing code** -- If a diff removes functional code and adds a comment (e.g., `// removed`, `// TODO: re-add`, `// no longer needed`), flag as Critical. Comments are not fixes. The code was either needed (removal is a bug) or not (remove silently). A comment replacing code is technical debt disguised as a change.
 
 ## Rationalizations to Reject
 
-| Rationalization                                     | Reality                                                                                     |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| "The tests pass, so the logic must be correct"      | Tests can be incomplete. Review the logic independently of test results.                    |
-| "This is how it was done elsewhere in the codebase" | Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent. |
-| "It's just a refactor, low risk"                    | Refactors change behavior surfaces. Review them with the same rigor as feature changes.     |
+| Rationalization                                     | Reality                                                                                                                      |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| "The tests pass, so the logic must be correct"      | Tests can be incomplete. Review the logic independently of test results.                                                     |
+| "This is how it was done elsewhere in the codebase" | Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent.                                  |
+| "It's just a refactor, low risk"                    | Refactors change behavior surfaces. Review them with the same rigor as feature changes.                                      |
+| "The fix is trivial, I'll just apply it inline"     | Trivial fixes still skip review when applied by the reviewer. Suggest the fix; let the author apply and re-review. Iron Law. |
 
 ## Escalation
 

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

@@ -139,7 +139,14 @@ git branch -d <branch-name>
 ```bash
 cd <worktree-path>
 git push -u origin <branch-name>
-gh pr create --title "<title>" --body "<description>"
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<PR body with real newlines — never use \n escape sequences>
+
+## Test plan
+<checklist>
+EOF
+)"
 # Report the PR URL to the user
 # Leave worktree in place until PR is merged
 ```
@@ -158,6 +165,14 @@ git worktree remove <worktree-path>
 git branch -D <branch-name>
 ```
 
+#### Step 3.5: Cross-Reference Conventions for Commit Messages and PR Bodies
+
+GitHub auto-links any `#N` token in commit messages, PR titles, and PR bodies to the issue or PR with that number. Treat `#N` as a reserved sigil — never use it for non-issue references.
+
+- **Do not** use `#N` for proposal success criteria, list ordinals, footnote refs, table rows, or any other in-document numbering. Write "criterion 9", "item 9", "step 3" instead. Using `#9` to mean "criterion 9" will silently cross-reference issue #9 — which is almost certainly an unrelated issue — and add a misleading back-reference to that issue's timeline.
+- **Do** reference the actual roadmap/tracker issue when finishing work tied to one. Use `Refs #<issue>` for context-only links and `Closes #<issue>` / `Fixes #<issue>` only when the merge should auto-close that issue.
+- **Before pushing or opening the PR**, scan the commit messages and PR body for stray `#N` tokens. For each one, confirm it points to the intended issue/PR — or rewrite it as plain text.
+
 #### Step 4: Clean Up
 
 1. **Remove the worktree** (unless keeping as-is or waiting for PR merge):
@@ -192,13 +207,14 @@ git branch -D <branch-name>
 
 ## Rationalizations to Reject
 
-| Rationalization                                                                                                                                       | Reality                                                                                                                                                                                                                                                        |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The tests are probably fine on the fresh branch — they were passing on main when I last checked. I'll skip baseline verification and start working." | Baseline verification is the condition that makes branch work trustworthy. A test failure discovered at finish time is ambiguous — it could be pre-existing or introduced by the work. Skipping baseline removes the only clean comparison point.              |
-| "The user said 'just merge it' — I'll merge without checking if the base branch has advanced since the worktree was created."                         | The pre-finish check for base branch divergence is mandatory before any finishing strategy. Merging without rebasing first can produce a merge that silently breaks tests that were passing on the branch but conflict with new commits on main.               |
-| "The worktree directory isn't gitignored, but it's inside a nested folder that's unlikely to be committed accidentally."                              | The `.gitignore` check is not about likelihood — it is about preventing accidental commits of worktree state that would corrupt the repository. If the worktree directory is not gitignored, add it before creating the worktree. No exceptions.               |
-| "The user chose to discard — I'll delete the branch and worktree immediately without showing the commits that will be lost."                          | The discard path requires showing the commit list from `git log main..HEAD --oneline` and receiving explicit confirmation before running `git worktree remove` and `git branch -D`. Work is being permanently deleted; the user must see what they are losing. |
-| "There's already a worktree for this branch at a different path — I'll create a second one since the user asked for a fresh setup."                   | Git does not allow two worktrees checked out to the same branch. Attempting to create a duplicate will fail. Instead, ask the user whether to use the existing worktree or create a new branch. Never assume a second worktree is the right answer.            |
+| Rationalization                                                                                                                                       | Reality                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The tests are probably fine on the fresh branch — they were passing on main when I last checked. I'll skip baseline verification and start working." | Baseline verification is the condition that makes branch work trustworthy. A test failure discovered at finish time is ambiguous — it could be pre-existing or introduced by the work. Skipping baseline removes the only clean comparison point.                                           |
+| "The user said 'just merge it' — I'll merge without checking if the base branch has advanced since the worktree was created."                         | The pre-finish check for base branch divergence is mandatory before any finishing strategy. Merging without rebasing first can produce a merge that silently breaks tests that were passing on the branch but conflict with new commits on main.                                            |
+| "The worktree directory isn't gitignored, but it's inside a nested folder that's unlikely to be committed accidentally."                              | The `.gitignore` check is not about likelihood — it is about preventing accidental commits of worktree state that would corrupt the repository. If the worktree directory is not gitignored, add it before creating the worktree. No exceptions.                                            |
+| "The user chose to discard — I'll delete the branch and worktree immediately without showing the commits that will be lost."                          | The discard path requires showing the commit list from `git log main..HEAD --oneline` and receiving explicit confirmation before running `git worktree remove` and `git branch -D`. Work is being permanently deleted; the user must see what they are losing.                              |
+| "There's already a worktree for this branch at a different path — I'll create a second one since the user asked for a fresh setup."                   | Git does not allow two worktrees checked out to the same branch. Attempting to create a duplicate will fail. Instead, ask the user whether to use the existing worktree or create a new branch. Never assume a second worktree is the right answer.                                         |
+| "I'll use `#9` in the commit message to refer to 'success criterion 9' in the proposal — it's obviously an in-document reference."                    | `#N` is GitHub's reserved syntax for issue/PR links in commits and PR bodies. It will auto-link to issue/PR #9 regardless of intent and post a misleading back-reference on that unrelated issue. Write "criterion 9" (no `#`) and cite the real roadmap issue separately with `Refs #<n>`. |
 
 ## Examples
 
@@ -251,9 +267,14 @@ npm test                # still passes after rebase
 
 # User chooses: Push and create PR
 git push -u origin feat/notifications
-gh pr create --title "feat(notifications): email and in-app notifications" \
-  --body "Implements notification service with create, list, and expiry.
-  16 new tests. All passing."
+gh pr create --title "feat(notifications): email and in-app notifications" --body "$(cat <<'EOF'
+## Summary
+Implements notification service with create, list, and expiry.
+
+## Test plan
+- [x] 16 new tests, all passing
+EOF
+)"
 
 # Report: "PR created: https://github.com/org/repo/pull/42
 #  Worktree at .worktrees/notifications kept until PR merges."

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

@@ -61,6 +61,22 @@ Work backward from the goal. Start with "what must be true when we are done?"
 4. **Identify key links.** How do artifacts connect? What imports what? What calls what?
 5. **Apply YAGNI.** For every artifact: "Is this required for an observable truth?" If not, cut it.
 
+6. **Surface uncertainties.** Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:
+   - **Blocking:** Cannot decompose tasks without resolving this. Escalate to user.
+   - **Assumption:** Can proceed with a stated assumption. Document it. If wrong, specific tasks will need revision.
+   - **Deferrable:** Does not affect task decomposition. Note for execution phase.
+
+   Format:
+
+   ```
+   ## Uncertainties
+   - [BLOCKING] How should the API handle partial failures? (Spec does not define.)
+   - [ASSUMPTION] Database supports transactions. (If not, Task 3 needs redesign.)
+   - [DEFERRABLE] Exact error message wording. (Can be finalized during implementation.)
+   ```
+
+   **Read-only constraint:** Steps 1-5 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
+
    When scope is ambiguous, use `emit_interaction`:
 
    ```json
@@ -335,6 +351,8 @@ Only apply when modifying existing documented behavior. When `docs/changes/` exi
 | "Tests for this task can be added in a follow-up task since the implementation is straightforward"            | No skipping TDD in tasks. Every code-producing task must start with writing a test. "Add tests later" is explicitly forbidden.                                          |
 | "The spec does not cover this edge case, but I can fill in the gap during planning"                           | When the spec is missing information, do not fill in the gaps yourself. Escalate. Filling gaps silently creates undocumented design decisions that no one reviewed.     |
 | "I discovered we need an additional file during decomposition, but updating the file map is just bookkeeping" | The file map must be complete. Every file that will be created or modified must appear in the file map before task decomposition.                                       |
+| "There are no real uncertainties — the spec is clear enough"                                                  | Every plan has unknowns. If you listed zero uncertainties, you skipped the step. Re-read the spec and list what is assumed but not stated.                              |
+| "I already know how to structure this, no need to finish scoping"                                             | Premature decomposition anchors on the first approach found. Complete SCOPE (observable truths + uncertainties) before proposing any task structure.                    |
 
 ## Examples
 
@@ -399,6 +417,7 @@ Files: src/types/notification.ts
 - **No plan without observable truths.** Must start with goal-backward acceptance criteria.
 - **No implementation during planning.** Write the plan, get approval, then use harness-execution.
 - **File map must be complete.** Every file to create or modify must appear before task decomposition.
+- **Uncertainties must be surfaced.** Phase 1 must produce an uncertainties list. Zero uncertainties means the step was skipped. Blocking uncertainties must be resolved before Phase 2.
 
 ## Escalation
 

package/dist/agents/skills/cursor/harness-skill-authoring/SKILL.md

@@ -273,6 +273,40 @@ metadata: # Provenance and authorship metadata
 
 3. **Test by running the skill:** `harness skill run <name>`. Verify it loads correctly and the process instructions make sense in context.
 
+### Phase 5B: TDD FOR SKILLS — Test Before Signing Off
+
+Apply test-driven thinking to skill authoring. A skill is not complete until it has been tested against scenarios that exercise its discipline sections.
+
+1. **Write a test scenario.** Before declaring the skill complete, define 2-3 concrete scenarios that should trigger the skill's discipline mechanisms:
+   - One scenario that should trigger a Red Flag (if the skill has Red Flags)
+   - One scenario that should trigger a Rationalization rejection
+   - One scenario that should trigger a Gate (for rigid skills)
+
+   ```markdown
+   ## Skill Test Scenarios
+
+   ### Scenario 1: Red Flag — [quoted phrase from Red Flags section]
+
+   Input: [describe the situation]
+   Expected: Agent stops, cites the Red Flag, and takes corrective action
+
+   ### Scenario 2: Rationalization — [quoted phrase from Rationalizations section]
+
+   Input: [describe the tempting shortcut]
+   Expected: Agent rejects the rationalization and follows the prescribed process
+
+   ### Scenario 3: Gate — [gate condition]
+
+   Input: [describe a state that violates the gate]
+   Expected: Agent halts and does not proceed past the gate
+   ```
+
+2. **Mentally execute each scenario.** Walk through the skill's process with the test input. Does the skill's prose clearly direct the agent to the correct behavior? If not, the skill needs revision — not the test.
+
+3. **Check for gaps.** If you cannot construct a scenario that triggers a discipline section, the section may be too abstract. Revise it to include a concrete quoted phrase or condition.
+
+4. **Document test scenarios** in a comment block at the end of SKILL.md or in a companion `tests.md` file. These serve as regression tests for future skill edits.
+
 ### Skill Quality Checklist
 
 Evaluate every skill along two dimensions:
@@ -312,13 +346,14 @@ Use this checklist as a final quality gate before declaring a skill complete.
 
 ## Rationalizations to Reject
 
-| Rationalization                                                         | Reality                                                                                                                                  |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| "This skill is too simple to need all required sections"                | Every section exists for a reason. A short section is fine; a missing section means the skill was not fully thought through.             |
-| "The process section covers it — no need for explicit success criteria" | Process describes what to do. Success criteria describe how to know it worked. They serve different purposes.                            |
-| "Rationalizations to Reject is meta — this skill does not need it"      | This section is required for all user-facing skills, including this one. No exceptions.                                                  |
-| "I will add examples later once the skill is proven"                    | Examples are a required section. A skill without examples forces the agent to guess at correct behavior. Write at least one example now. |
-| "The When to Use section is obvious from the name"                      | Negative conditions (when NOT to use) prevent misapplication. The skill name conveys nothing about boundary conditions.                  |
+| Rationalization                                                         | Reality                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This skill is too simple to need all required sections"                | Every section exists for a reason. A short section is fine; a missing section means the skill was not fully thought through.                                                                             |
+| "The process section covers it — no need for explicit success criteria" | Process describes what to do. Success criteria describe how to know it worked. They serve different purposes.                                                                                            |
+| "Rationalizations to Reject is meta — this skill does not need it"      | This section is required for all user-facing skills, including this one. No exceptions.                                                                                                                  |
+| "I will add examples later once the skill is proven"                    | Examples are a required section. A skill without examples forces the agent to guess at correct behavior. Write at least one example now.                                                                 |
+| "The When to Use section is obvious from the name"                      | Negative conditions (when NOT to use) prevent misapplication. The skill name conveys nothing about boundary conditions.                                                                                  |
+| "The skill works — I tested it by running it once"                      | A single happy-path run does not test discipline sections. Write scenarios that trigger Red Flags, Gates, and Rationalizations. A skill that passes happy path but fails discipline scenarios is a trap. |
 
 ## Examples
 

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

@@ -259,6 +259,31 @@ Every verification claim MUST use one of:
 
 **Uncited claims:** Any verification assertion without direct evidence is a verification failure. This skill does not use `[UNVERIFIED]` -- if evidence cannot be produced, verdict is FAIL or INCOMPLETE.
 
+## Rubric Compression
+
+Verification checklists passed to subagents or used internally MUST use compressed single-line format. Each check is one line with pipe-delimited fields:
+
+```
+level|check-name|pass-criterion
+```
+
+**Example (Level 2 SUBSTANTIVE rubric):**
+
+```
+L2|no-stubs|No TODO/FIXME/throw-not-implemented in production code
+L2|no-empty-bodies|No empty function bodies, () => {}, or return null as sole logic
+L2|spec-complete|All behaviors specified in spec have corresponding implementation
+L2|real-logic|Functions contain meaningful logic, not just hardcoded returns
+```
+
+**Why:** Verbose checklist prose inflates verification context without improving accuracy. Dense single-line rubrics give the same signal in fewer tokens, leaving more budget for reading and analyzing actual file content.
+
+**Rules:**
+
+- Level prefix must be L1 (EXISTS), L2 (SUBSTANTIVE), or L3 (WIRED)
+- Maximum 80 characters per criterion text
+- Rubric entries are guidance — the verification levels define the authoritative checks
+
 ## Non-Determinism Tolerance
 
 Mechanical checks (tests, lint, types) are binary pass/fail. No tolerance.

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

@@ -47,7 +47,9 @@ Store answers in: .harness/architecture/<topic>/discovery.md
 
 ---
 
-### Phase 2: ANALYZE — Research the Codebase
+### Phase 2: ANALYZE — Research the Codebase (Read-Only)
+
+**Read-only research constraint:** This phase is discovery, not solution design. You may read files, search patterns, trace dependencies, and record observations. You may NOT propose solutions, recommend approaches, or evaluate trade-offs. If you catch yourself writing "we could..." or "one option is...", STOP — you have left research mode. Save solutions for Phase 3.
 
 Read the codebase to understand the current state. Do not propose solutions yet — gather facts.
 
@@ -272,6 +274,7 @@ Also link from the project's ADR index if one exists.
 - **Always 2-3 options.** Never present 1 option (that is a directive, not advice). Never present more than 3 (that causes paralysis).
 - **No implementation in this skill.** If you write production code, you have broken the advisory boundary. Stop and return to presenting options.
 - **Trade-offs must be honest.** Every option has downsides. If you cannot articulate the cons of an option, you do not understand it well enough to recommend it.
+- **No solutions in Phase 2.** Phase 2 is read-only research. Observations and facts only. Solutions belong in Phase 3. Mixing discovery with solution design anchors on the first idea found.
 
 ## Evidence Requirements
 
@@ -309,11 +312,12 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
-| Rationalization                   | Reality                                                                                             |
-| --------------------------------- | --------------------------------------------------------------------------------------------------- |
-| "This will be easier to maintain" | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase. |
-| "It's the modern approach"        | Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.            |
-| "Other teams do it this way"      | Other teams have different constraints. Evaluate the option on this codebase's specific merits.     |
+| Rationalization                                              | Reality                                                                                                                                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This will be easier to maintain"                            | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase.                                                                       |
+| "It's the modern approach"                                   | Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.                                                                                  |
+| "Other teams do it this way"                                 | Other teams have different constraints. Evaluate the option on this codebase's specific merits.                                                                           |
+| "I can see the solution already, no need to finish research" | Premature convergence anchors on the first viable option. Complete Phase 2 research before proposing anything in Phase 3. The best option may not be the first one found. |
 
 ## Escalation
 

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

@@ -24,6 +24,12 @@ When no arguments are provided (standalone invocation), session slug is unknown
 
 ## Process
 
+### Iron Law
+
+**Review identifies issues. Review never fixes them.**
+
+A reviewer who applies fixes is no longer reviewing — they are editing with reviewer authority and no review. Suggest the fix in the finding. Do not apply it. If you catch yourself writing production code during review, STOP. You have crossed the boundary.
+
 The review runs as a 7-phase pipeline. Each phase has a clear input, output, and exit condition.
 
 ```
@@ -560,6 +566,32 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 
 **Uncited claims:** Findings without evidence discarded in Phase 5. Observations without file:line references prefixed `[UNVERIFIED]` and downgraded to `suggestion`.
 
+## Rubric Compression
+
+Review rubrics passed to subagents in Phase 4 MUST use compressed single-line format to minimize token consumption. Each rubric entry is one line with pipe-delimited fields:
+
+```
+domain|check-name|severity|one-sentence-criterion
+```
+
+**Example (Compliance Agent rubric):**
+
+```
+compliance|spec-alignment|critical|Implementation matches all behaviors specified in the approved spec
+compliance|api-surface|important|New exports are minimal and well-named; internal symbols stay unexported
+compliance|backward-compat|critical|No breaking changes to existing callers without documented migration path
+compliance|naming|suggestion|Names follow project conventions (check AGENTS.md or .eslintrc)
+```
+
+**Why:** Verbose rubric prose inflates context by 2-5x without improving review accuracy. Dense single-line rubrics give the agent the same signal in fewer tokens, leaving more budget for actual code analysis.
+
+**Rules:**
+
+- Maximum 80 characters per criterion text
+- Domain must match the subagent's scope (compliance, bug, security, architecture)
+- Severity must be one of: critical, important, suggestion
+- Rubric entries are guidance, not exhaustive — agents may surface findings outside the rubric
+
 ## Harness Integration
 
 - **`assess_project`** — Phase 2: run validate/deps/docs in parallel. Failures are Critical and stop pipeline.
@@ -644,6 +676,7 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 - **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.
+- **Never apply fixes during review.** Review output is findings, not code changes. Suggest fixes in finding text; never edit production code. Iron Law violation.
 
 ## Red Flags
 
@@ -659,14 +692,16 @@ Every `ReviewFinding.evidence` array MUST include citations using one of:
 - **"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.
+- **Comment replacing code** -- If a diff removes functional code and adds a comment (e.g., `// removed`, `// TODO: re-add`, `// no longer needed`), flag as Critical. Comments are not fixes. The code was either needed (removal is a bug) or not (remove silently). A comment replacing code is technical debt disguised as a change.
 
 ## Rationalizations to Reject
 
-| Rationalization                                     | Reality                                                                                     |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| "The tests pass, so the logic must be correct"      | Tests can be incomplete. Review the logic independently of test results.                    |
-| "This is how it was done elsewhere in the codebase" | Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent. |
-| "It's just a refactor, low risk"                    | Refactors change behavior surfaces. Review them with the same rigor as feature changes.     |
+| Rationalization                                     | Reality                                                                                                                      |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| "The tests pass, so the logic must be correct"      | Tests can be incomplete. Review the logic independently of test results.                                                     |
+| "This is how it was done elsewhere in the codebase" | Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent.                                  |
+| "It's just a refactor, low risk"                    | Refactors change behavior surfaces. Review them with the same rigor as feature changes.                                      |
+| "The fix is trivial, I'll just apply it inline"     | Trivial fixes still skip review when applied by the reviewer. Suggest the fix; let the author apply and re-review. Iron Law. |
 
 ## Escalation