@harness-engineering/cli 1.25.4 → 1.25.6

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

@@ -603,6 +603,16 @@ compliance|naming|suggestion|Names follow project conventions (check AGENTS.md o
 - **`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.
 
+## Uncertainty Surfacing
+
+When a review subagent encounters ambiguity during analysis, classify it immediately:
+
+- **Blocking:** Cannot determine severity without more context (e.g., unclear whether a pattern is intentional or accidental). Surface as a finding with severity `suggestion` and rationale explaining the ambiguity. Do not guess.
+- **Assumption:** Can classify if assumption is stated (e.g., "assuming this endpoint is internal-only, the missing auth check is acceptable"). State the assumption in the finding. If wrong, the finding severity changes.
+- **Deferrable:** Ambiguity does not affect the review (e.g., whether a naming choice will cause confusion in the future). Omit from findings — it is noise.
+
+Do not suppress ambiguous findings. An ambiguous finding surfaced as a question is more valuable than a confident finding built on a wrong assumption.
+
 ## Success Criteria
 
 - Pipeline runs all 7 phases in order (skipping GATE without `--ci`)
@@ -696,12 +706,26 @@ compliance|naming|suggestion|Names follow project conventions (check AGENTS.md o
 
 ## 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.                                      |
-| "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. |
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+| Rationalization                                                 | Reality                                                                                                                                                |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The 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.                           |
+| "The diff is small so I can approve without reading every file" | Small diffs can contain critical bugs. Read every changed file completely — size does not correlate with risk. A one-line auth bypass is a small diff. |
+| "The author is experienced, so I can be less thorough"          | Review rigor is based on the code, not the author. Experienced authors make mistakes too. Apply the same checklist regardless of who wrote it.         |
 
 ## Escalation
 

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

@@ -286,6 +286,18 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
 | Rationalization                              | Reality                                                                                                                          |
 | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | "The table is small, we don't need an index" | Tables grow. Plan for the steady state, not the current row count.                                                               |

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

@@ -15,6 +15,14 @@
 
 ## Process
 
+### Iron Law
+
+**Phase 1 INVESTIGATE before ANY fix. No exceptions.**
+
+If you find yourself writing fix code before completing investigation, STOP. Delete the fix. You are guessing, not debugging. A fix without investigation is a coin flip that creates the illusion of progress.
+
+---
+
 ### Prerequisite: Start a Debug Session
 
 Before beginning, create a persistent debug session. This survives context resets and tracks state across multiple attempts.
@@ -53,6 +61,8 @@ Error: <the error message or symptom>
 
 **You must complete Phase 1 before writing ANY fix code. No exceptions.**
 
+**Read-only constraint:** Phase 1 is investigation only. You may read files, run commands, add log statements, and record observations. You may NOT write production code fixes, modify business logic, or commit changes during investigation. If you find yourself writing a fix, you have jumped to Phase 4.
+
 #### Step 1: Run Entropy Analysis
 
 ```bash
@@ -115,6 +125,16 @@ Update the session status to `investigating`.
 
 ---
 
+### Uncertainty Surfacing
+
+When you encounter an unknown during investigation or analysis, classify it immediately:
+
+- **Blocking:** Cannot form a testable hypothesis without resolving this (e.g., cannot reproduce the bug, unclear what "correct" behavior is). STOP and escalate to human.
+- **Assumption:** Can proceed with a stated assumption (e.g., "the database schema has not changed since last deployment"). Document in the session log. If wrong, hypotheses built on it are invalid.
+- **Deferrable:** Does not affect the current investigation (e.g., whether other code paths have similar issues). Note in session log for follow-up.
+
+Do not bury unknowns. An unstated assumption in your investigation leads to fixes that address the wrong root cause.
+
 ### Phase 2: ANALYZE — Find the Pattern
 
 #### Step 1: Find Working Examples
@@ -298,14 +318,25 @@ Update the session status to `resolved`.
 - Debug session file is complete with investigation log, hypotheses, and resolution
 - Learnings were captured for future reference
 
+## Red Flags
+
+| Flag                                                                            | Corrective Action                                                                                                                                                 |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "It's probably X, let me just fix that"                                         | STOP. "Probably" is a guess, not a diagnosis. Complete Phase 1 INVESTIGATE before writing any fix code.                                                           |
+| "I'll change a few things and see if the bug goes away"                         | STOP. One variable at a time. Multiple simultaneous changes mean you cannot determine which one had the effect — or whether you introduced a new bug.             |
+| "One more fix attempt before I escalate" after 2 failed attempts                | STOP. Three failed attempts means your mental model is wrong. Step back, re-read the investigation log, and question your assumptions about how the system works. |
+| `// temporary workaround` or `// TODO: real fix later` replacing root-cause fix | STOP. Workarounds are symptom suppression. The root cause remains. Fix it properly or escalate — do not commit workarounds disguised as fixes.                    |
+
 ## Rationalizations to Reject
 
-| Rationalization                                                                   | Reality                                                                                                                                     |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| "I have a strong hunch about what is wrong, so I will jump straight to fixing it" | Phase 1 INVESTIGATE must be completed before ANY fix code is written. You are guessing, not debugging.                                      |
-| "I changed two things and the bug is gone, so the fix must be correct"            | One variable at a time is a gate. Changing multiple things simultaneously means you do not know which change fixed it.                      |
-| "This is my third attempt but I feel close, so one more try before escalating"    | After 3 failed fix attempts, the gate requires you to question the architecture. The problem is likely not where you think it is.           |
-| "A try-catch that swallows the error prevents the crash, so the bug is fixed"     | Symptom suppression is explicitly listed as a bad fix. Wrapping the failure in a try-catch addresses what the bug did, not why it happened. |
+| Rationalization                                                                   | Reality                                                                                                                                                                                  |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I have a strong hunch about what is wrong, so I will jump straight to fixing it" | Phase 1 INVESTIGATE must be completed before ANY fix code is written. You are guessing, not debugging.                                                                                   |
+| "I changed two things and the bug is gone, so the fix must be correct"            | One variable at a time is a gate. Changing multiple things simultaneously means you do not know which change fixed it.                                                                   |
+| "This is my third attempt but I feel close, so one more try before escalating"    | After 3 failed fix attempts, the gate requires you to question the architecture. The problem is likely not where you think it is.                                                        |
+| "A try-catch that swallows the error prevents the crash, so the bug is fixed"     | Symptom suppression is explicitly listed as a bad fix. Wrapping the failure in a try-catch addresses what the bug did, not why it happened.                                              |
+| "The bug only happens in edge cases, so a partial fix is acceptable"              | A partial fix means the bug still exists. Either fix the root cause completely or document the remaining scenarios as known issues with tracked tickets.                                 |
+| "I can skip the regression test since I understand the root cause well"           | Understanding the root cause and proving the fix catches it are different things. The revert-and-fail test is mandatory — it is the only proof the test actually guards against the bug. |
 
 ## Examples
 
@@ -359,6 +390,7 @@ Revert test: Commenting out the validation check causes the test to fail with 50
 
 ## Gates
 
+- **Investigation phases are read-only.** Phase 1 and Phase 2 produce understanding, not code. Reading files, running commands, and adding diagnostic log statements are allowed. Writing production code fixes is not. If you find yourself writing a fix during investigation, you have skipped ahead.
 - **Phase 1 before ANY fix.** You must complete investigation before writing fix code. Skipping investigation leads to symptom-chasing, which leads to more bugs.
 - **One variable at a time.** Changing multiple things simultaneously is forbidden. If you changed two things and the bug is fixed, you do not know which change fixed it (or if the other change introduced a new bug).
 - **After 3 failed fix attempts, question the architecture.** If three consecutive hypotheses were wrong or three fixes did not resolve the issue, the problem is likely not where you think it is. Step back. Re-read the investigation log. Consider that the bug might be in a different layer entirely.

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

@@ -283,6 +283,18 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
 | Rationalization                                | Reality                                                                                                                                |
 | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | "It's just a config change, not a code change" | Config changes cause outages at the same rate as code changes. Deploy them with the same rigor and rollback strategy.                  |

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

@@ -76,6 +76,18 @@ Fall back to file-based commands if no graph is available.
 
 ---
 
+### Uncertainty Surfacing
+
+When you encounter an unknown during task execution, classify it immediately:
+
+- **Blocking:** Cannot complete the task as written without resolving this (e.g., referenced file doesn't exist, spec behavior undefined for this scenario). STOP. Record as a blocker and report.
+- **Assumption:** Can proceed if assumption is stated (e.g., "the API returns JSON, not XML"). Document the assumption in the commit message. If wrong, the task must be revisited.
+- **Deferrable:** Does not affect the current task (e.g., whether a later task will need a different approach). Note in learnings for future tasks.
+
+Do not improvise past unknowns. An assumption that turns out wrong is cheaper than an improvised solution that hides the unknown.
+
+**Read-only constraint for Phase 1:** Phase 1 PREPARE is research and state loading. Do not write production code, create files, or make commits during PREPARE. If prerequisites fail, report the failure — do not attempt to fix prerequisites yourself.
+
 ### Phase 2: EXECUTE — Implement Tasks Atomically
 
 Report progress with: `**[Phase N/M]** Task N — <description>`
@@ -329,14 +341,25 @@ Claims about task completion, test results, or code behavior MUST cite evidence:
 - No improvisation: tasks executed as written, or stopped with blocker reported
 - All stopping conditions respected
 
+## Red Flags
+
+| Flag                                                                   | Corrective Action                                                                                                                      |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| "The plan says X but Y would be cleaner — I'll improvise"              | STOP. Iron Law: execute the plan as written. If the plan is wrong, stop and fix the plan. Improvising introduces untested assumptions. |
+| "I'll skip the test for this task since it's just configuration"       | STOP. The TDD rhythm is not optional. Configuration changes need tests too — they prove the config does what the task requires.        |
+| "I'll handle this edge case the plan didn't mention"                   | STOP. Unplanned work is scope creep. If the edge case matters, it's a plan deficiency — record it as a blocker.                        |
+| `// TODO: come back to this` or `// skipped for now` in committed code | STOP. Every commit must be atomic and complete for its task. TODOs in committed code are incomplete tasks disguised as progress.       |
+
 ## Rationalizations to Reject
 
-| Rationalization                                                                                                | Reality                                                                                                                                                   |
-| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The plan says to do X, but doing Y would be cleaner -- I will improvise"                                      | The Iron Law states: execute the plan as written. If the plan is wrong, stop and fix the plan. Improvising mid-execution introduces untested assumptions. |
-| "This task depends on Task 3 which I know is done, so I can skip verifying prerequisites"                      | Prerequisites must be verified mechanically, not from memory. Check that dependency tasks are marked complete in state and that referenced files exist.   |
-| "The checkpoint is just a confirmation step and the output looks correct, so I will auto-continue"             | Checkpoints are non-negotiable pause points. If a task has a checkpoint marker, execution must pause.                                                     |
-| "Harness validate passed on the previous task and nothing changed structurally, so I can skip it for this one" | Validation runs after every task with no exceptions. Each task may introduce subtle architectural drift that only harness validate catches.               |
+| Rationalization                                                                                                | Reality                                                                                                                                                         |
+| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The plan says to do X, but doing Y would be cleaner -- I will improvise"                                      | The Iron Law states: execute the plan as written. If the plan is wrong, stop and fix the plan. Improvising mid-execution introduces untested assumptions.       |
+| "This task depends on Task 3 which I know is done, so I can skip verifying prerequisites"                      | Prerequisites must be verified mechanically, not from memory. Check that dependency tasks are marked complete in state and that referenced files exist.         |
+| "The checkpoint is just a confirmation step and the output looks correct, so I will auto-continue"             | Checkpoints are non-negotiable pause points. If a task has a checkpoint marker, execution must pause.                                                           |
+| "Harness validate passed on the previous task and nothing changed structurally, so I can skip it for this one" | Validation runs after every task with no exceptions. Each task may introduce subtle architectural drift that only harness validate catches.                     |
+| "The task failed but I can see the fix — I'll apply it and move on without recording a blocker"                | A failed task is a blocker. Record it, report it, and stop. Applying unplanned fixes mid-execution makes progress untraceable and may cascade into later tasks. |
+| "Phase 1 prerequisites are missing but I can create them as part of this task"                                 | PREPARE is read-only. Missing prerequisites mean a prior task or the plan is deficient. Report the gap — do not fix prerequisites during execution setup.       |
 
 ## Examples
 
@@ -398,6 +421,7 @@ harness validate — passes. Resume Task 4.
 
 Hard stops. Violating any gate means the process has broken down.
 
+- **Phase 1 PREPARE is read-only.** Do not write production code, create files, or commit during preparation. If prerequisites are missing, report the gap — do not fix it yourself.
 - **No execution without a plan.** If no plan exists, do not start. Use harness-planning.
 - **No improvisation.** Execute as written. Do not add "improvements" not in the plan.
 - **No skipping tasks.** Tasks are dependency-ordered. Execute in order.

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

@@ -342,17 +342,28 @@ Only apply when modifying existing documented behavior. When `docs/changes/` exi
 - Human has reviewed and approved the plan
 - Rigor level rules followed: fast skips skeleton; thorough always skeletons with approval; standard skeletons at >= 8 tasks
 
+## Red Flags
+
+| Flag                                                                         | Corrective Action                                                                                                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I know the implementation well enough to skip reading the spec"             | STOP. Phase 1 SCOPE starts by reading the spec. Assumptions about spec content lead to plans that implement the wrong thing.                                  |
+| "This task is self-explanatory, no need for exact file paths and commands"   | STOP. Iron Law: every task must contain exact file paths, exact commands, and complete code snippets. "Implement the service" is a wish, not a task.          |
+| "I'll plan the happy path now and add error handling tasks later"            | STOP. Error handling is not optional. The spec's success criteria include error scenarios. Plan them alongside the happy path.                                |
+| `// detailed steps TBD` or `// expand during execution` in task descriptions | STOP. A task that defers detail to execution is a vague task. If you cannot write the exact steps now, you do not understand the task well enough to plan it. |
+
 ## Rationalizations to Reject
 
-| Rationalization                                                                                               | Reality                                                                                                                                                                 |
-| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The task is conceptually clear so I do not need to include exact code in the plan"                           | Every task must have exact file paths, exact code, and exact commands. If you cannot write the code in the plan, you do not understand the task well enough to plan it. |
-| "This task touches 5 files but it is logically one unit of work, so splitting it would add overhead"          | Tasks touching more than 3 files must be split. The overhead of splitting is far less than the cost of a failed oversized task.                                         |
-| "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.                    |
+| Rationalization                                                                                               | Reality                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The task is conceptually clear so I do not need to include exact code in the plan"                           | Every task must have exact file paths, exact code, and exact commands. If you cannot write the code in the plan, you do not understand the task well enough to plan it.                                     |
+| "This task touches 5 files but it is logically one unit of work, so splitting it would add overhead"          | Tasks touching more than 3 files must be split. The overhead of splitting is far less than the cost of a failed oversized task.                                                                             |
+| "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.                                                        |
+| "The skeleton pass adds overhead for a plan this size — I will go straight to full tasks"                     | Rigor level rules are not optional. In thorough mode, the skeleton is always required. In standard mode, 8+ tasks require a skeleton. Skipping it risks task-level misalignment with the goal.              |
+| "I will write implementation code in the plan to make the tasks more concrete"                                | Planning produces a plan document, not code. Writing code during planning violates the phase boundary — code belongs in execution. Exact snippets in task descriptions are plan content, not executed code. |
 
 ## Examples
 

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

@@ -10,6 +10,16 @@
 - NOT as a replacement for full peer review (use `harness-code-review` for that)
 - NOT for commits that only update documentation or configuration (fast path skips AI review)
 
+## Process
+
+### Iron Law
+
+**Mechanical checks gate AI review. No exceptions.**
+
+If lint, typecheck, or tests fail, the pipeline stops. AI review does not run. Observations from AI review are advisory — they never block a commit. Only mechanical failures block. This ordering is non-negotiable.
+
+---
+
 ## Principle: Deterministic First
 
 This skill follows the Deterministic-vs-LLM Responsibility Split principle. Mechanical checks run first and must pass before any AI review occurs. If a linter or type checker can catch the problem, the LLM should not be the one finding it.
@@ -262,6 +272,47 @@ fi
 
 **Note:** AI review observations (WARN) do not block the commit — only mechanical check failures (FAIL) block. The author decides whether to address AI observations.
 
+## Red Flags
+
+| Flag                                                                              | Corrective Action                                                                                                                                             |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The lint errors are just warnings, I can proceed to AI review"                   | STOP. The gate is absolute. Any mechanical check failure means STOP. Warnings configured as errors are failures.                                              |
+| "I'll run the full test suite later in CI"                                        | STOP. Pre-commit checks include tests. The purpose is to catch failures BEFORE they reach CI — not to defer them.                                             |
+| "This is just a config change, skip the security scan"                            | STOP. Phase 3 runs against all staged source files regardless of change type. Config files can contain hardcoded secrets.                                     |
+| `// quick fix, will clean up before PR` or `// TODO: handle error` in staged code | STOP. Pre-commit is the last line of defense before code enters the repository. Code committed with cleanup TODOs gets merged with cleanup TODOs. Fix it now. |
+
+**Review-never-fixes:** Pre-commit review identifies observations. It never modifies staged code. AI review findings are reported for the author to decide — not applied automatically. A review that silently modifies code is not a review.
+
+## Rubric Compression
+
+Pre-commit review checklists MUST use compressed single-line format. Each check is one line with pipe-delimited fields:
+
+```
+phase|check-name|blocking|criterion
+```
+
+**Example:**
+
+```
+mechanical|lint|yes|Zero lint errors in staged files
+mechanical|typecheck|yes|Zero type errors reported by tsc --noEmit
+mechanical|tests|yes|All tests pass with exit code 0
+mechanical|harness-health|yes|assess_project returns healthy: true
+security|secrets|yes|No hardcoded secrets, API keys, or credentials in staged files
+security|injection|yes|No eval(), exec(), or unparameterized SQL in staged files
+security|advisory|no|CORS wildcards, HTTP URLs, disabled TLS — reported but non-blocking
+ai|obvious-bugs|no|Null dereference, infinite loops, off-by-one, resource leaks
+ai|debug-artifacts|no|No console.log, debugger statements, or TODO without issue ref
+```
+
+**Why:** Dense single-line rubrics minimize token consumption while preserving the same review signal. More budget for actual diff analysis.
+
+**Rules:**
+
+- Phase must be `mechanical`, `security`, or `ai`
+- Blocking must be `yes` or `no`
+- Maximum 80 characters per criterion text
+
 ## Gates
 
 - **Mechanical checks must pass before AI review.** Do not run AI review if lint/typecheck/tests fail.
@@ -286,12 +337,14 @@ fi
 
 ## Rationalizations to Reject
 
-| Rationalization                                                               | Why It Is Wrong                                                                                                                                               |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The lint errors are just warnings, so I can proceed to AI review"            | The gate is absolute: any mechanical check failure means STOP. AI review does not run until lint, typecheck, and tests all pass.                              |
-| "This is a docs-only change but let me run AI review anyway for thoroughness" | The fast path is mandatory. If only docs/config files changed, AI review is skipped. Running it anyway wastes tokens.                                         |
-| "The AI found a style issue, so I should block the commit"                    | AI review observations are advisory only. Only mechanical check failures block the commit.                                                                    |
-| "I will skip the security scan since this is an internal endpoint"            | Phase 3 runs the security scanner against all staged source files regardless of exposure. Hardcoded secrets and injection are blocking even in internal code. |
+| Rationalization                                                               | Why It Is Wrong                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The lint errors are just warnings, so I can proceed to AI review"            | The gate is absolute: any mechanical check failure means STOP. AI review does not run until lint, typecheck, and tests all pass.                                                                                       |
+| "This is a docs-only change but let me run AI review anyway for thoroughness" | The fast path is mandatory. If only docs/config files changed, AI review is skipped. Running it anyway wastes tokens.                                                                                                  |
+| "The AI found a style issue, so I should block the commit"                    | AI review observations are advisory only. Only mechanical check failures block the commit.                                                                                                                             |
+| "I will skip the security scan since this is an internal endpoint"            | Phase 3 runs the security scanner against all staged source files regardless of exposure. Hardcoded secrets and injection are blocking even in internal code.                                                          |
+| "The AI found an issue so I should fix it before reporting"                   | Pre-commit review reports findings — it does not apply fixes. The author decides what to act on. A review that silently modifies code is editing, not reviewing.                                                       |
+| "The mechanical checks passed so the code is ready — skip the AI review"      | If source files are staged (not docs/config only), AI review runs. Mechanical checks catch syntax and type errors; AI review catches semantic issues like null dereference and resource leaks. Both layers have value. |
 
 ## Examples
 

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

@@ -16,7 +16,7 @@
 
 ## Process
 
-### Iron Rule
+### Iron Law
 
 **All tests must pass BEFORE you start refactoring and AFTER every single change.**
 
@@ -41,6 +41,16 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 Catches indirect consumers that grep misses. Fall back to file-based commands if no graph is available.
 
+### Uncertainty Surfacing
+
+When you encounter an unknown during refactoring, classify it immediately:
+
+- **Blocking:** Cannot determine if the change is purely structural without resolving this (e.g., unclear whether callers rely on implementation detail). STOP and surface to human.
+- **Assumption:** Can proceed if assumption is stated (e.g., "no external consumers of this internal API"). Document the assumption and continue. If wrong, revert.
+- **Deferrable:** Does not affect the current refactoring step (e.g., whether a further refactoring would be beneficial). Note for future consideration.
+
+Do not guess whether a change is behavioral or structural. If you are unsure, it is blocking.
+
 ### Phase 2: Execute — One Small Change at a Time
 
 For EACH step in the plan:
@@ -134,14 +144,25 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 - No behavioral changes were introduced (the test suite is the proof)
 - No dead code was left behind (run `harness cleanup` to verify)
 
+## Red Flags
+
+| Flag                                                                                    | Corrective Action                                                                                                                                                            |
+| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This refactoring is safe, I don't need to run tests after this small change"           | STOP. The Iron Law is absolute: tests after EVERY change. "Small" and "safe" are the changes that introduce subtle bugs.                                                     |
+| "I'll combine these two renames into one commit since they're related"                  | STOP. One change per commit. Combined changes make it impossible to isolate which change caused a regression.                                                                |
+| "The failing test is testing implementation details, so I'll fix the test"              | STOP. Changing tests during refactoring is a warning sign. Verify the test is actually testing implementation details — not behavior your refactoring inadvertently changed. |
+| `// removed old implementation` or `// TODO: move back later` replacing functional code | STOP. Either the code lives in its new location or it doesn't. Comments are not migration plans. Keep the code or delete it with a test proving the deletion is safe.        |
+
 ## Rationalizations to Reject
 
-| Rationalization                                                                                                     | Reality                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The tests are mostly passing, so I can start refactoring and fix the remaining failures as I go"                   | All tests must pass BEFORE refactoring starts. If tests are not green before you start, you are not refactoring -- you are debugging.        |
-| "This refactoring changes a small amount of behavior, but it is a clear improvement"                                | Refactoring must not change behavior. The test suite is the proof. If the refactoring requires changing tests, you may be changing behavior. |
-| "I will make several changes at once and run tests at the end since each change is small"                           | Tests must run after EVERY single change. If a test breaks, you must undo the LAST change immediately.                                       |
-| "The refactoring did not produce a measurable improvement, but the code is different so it must be somewhat better" | If the refactoring introduced no measurable improvement, revert the entire sequence. Refactoring for its own sake is churn.                  |
+| Rationalization                                                                                                     | Reality                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The tests are mostly passing, so I can start refactoring and fix the remaining failures as I go"                   | All tests must pass BEFORE refactoring starts. If tests are not green before you start, you are not refactoring -- you are debugging.                       |
+| "This refactoring changes a small amount of behavior, but it is a clear improvement"                                | Refactoring must not change behavior. The test suite is the proof. If the refactoring requires changing tests, you may be changing behavior.                |
+| "I will make several changes at once and run tests at the end since each change is small"                           | Tests must run after EVERY single change. If a test breaks, you must undo the LAST change immediately.                                                      |
+| "The refactoring did not produce a measurable improvement, but the code is different so it must be somewhat better" | If the refactoring introduced no measurable improvement, revert the entire sequence. Refactoring for its own sake is churn.                                 |
+| "I will refactor this and add the new feature in the same pass to be efficient"                                     | Refactoring and feature work are separate tasks. Mixing them means test failures could be from the refactoring OR the new behavior — you cannot tell which. |
+| "The test suite is slow, so I will run tests only at the end of the refactoring sequence"                           | Each step must be independently verified. A slow test suite is a separate problem to solve — it is not a reason to skip the safety net.                     |
 
 ## Examples
 

package/dist/agents/skills/cursor/harness-security-scan/SKILL.md

@@ -94,6 +94,18 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
 | Rationalization                     | Reality                                                                                            |
 | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
 | "No attacker would find this"       | Security by obscurity. If the code is wrong, flag it regardless of discoverability.                |

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

@@ -14,6 +14,14 @@
 
 ## Process
 
+### Iron Law
+
+**No skill ships without validation passing and test scenarios exercising every discipline section.**
+
+A skill that passes happy-path execution but has untested discipline sections (Red Flags, Gates, Rationalizations) is a trap — agents activate it but have no guardrails when they encounter edge cases. Phase 5B is not optional.
+
+---
+
 ### Phase 1: DEFINE — Establish the Skill's Purpose
 
 1. **Identify the recurring process.** What does the team do repeatedly? Name it. Describe it in one sentence. This becomes the skill's `description` in `skill.yaml` and the blockquote summary in `SKILL.md`.
@@ -344,16 +352,29 @@ Use this checklist as a final quality gate before declaring a skill complete.
 - Rigid skills include Gates and Escalation sections with specific conditions and consequences
 - The skill can be loaded and run with `harness skill run <name>`
 
+## Red Flags
+
+| Flag                                                                                | Corrective Action                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This skill is simple enough to ship without test scenarios"                        | STOP. Phase 5B exists because untested discipline sections are decoration. If you cannot construct a scenario that triggers each discipline section, the section is too abstract — revise it. |
+| "I'll add the Rationalizations/Gates/Escalation section after the skill is working" | STOP. Discipline sections are required sections. A skill that "works" without guardrails is a trap — agents activate but flounder at edge cases. Write the real content now.                  |
+| "The skill works, I tested it by running it once"                                   | STOP. A single happy-path run does not test discipline sections. Write scenarios that trigger Red Flags, Gates, and Rationalizations.                                                         |
+| `// placeholder for future phases` or `// TODO: add gate conditions` in SKILL.md    | STOP. Placeholder sections are stubs. A skill with stub discipline sections passes validation but fails in practice. Write the real content or remove the section entirely.                   |
+
+**Review-never-fixes:** When reviewing or extending an existing skill, identify issues but do not fix them inline. Document findings, propose fixes, and let the skill author decide. Reviewing and editing are separate roles.
+
 ## 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.                                                                                  |
-| "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. |
+| 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.  |
+| "This is an internal skill, so discipline sections are unnecessary"     | Agents rationalize skipping steps in internal skills too. Every user-facing skill requires the full discipline stack — no exemptions for internal or simple skills.                                       |
+| "I will copy the Rationalizations from a similar skill and adapt them"  | Domain-specific means domain-specific. Copied rationalizations address the source skill's shortcuts, not this skill's. Write fresh entries based on what an agent executing THIS skill would try to skip. |
 
 ## Examples
 
@@ -471,3 +492,17 @@ Tools: Bash, Read, Glob.
   "Rollback to version [X] failed. Current state: [description].
   Manual intervention required."
 ```
+
+## Gates
+
+- **No shipping without validation.** `harness skill validate` must pass with zero errors before declaring a skill complete. Validation failures are not warnings — they are hard stops.
+- **No shipping without test scenarios.** Phase 5B is mandatory. A skill without test scenarios that exercise its discipline sections (Red Flags, Gates, Rationalizations) is not complete, even if validation passes.
+- **No placeholder sections.** Every required section must contain substantive content. A `## Rationalizations to Reject` section with generic entries or a `## Gates` section with no conditions is a stub, not a section.
+- **No skipping negative conditions.** The `## When to Use` section must include both positive (when TO use) and negative (when NOT to use) conditions. Missing negatives cause misapplication.
+
+## Escalation
+
+- **When you cannot identify domain-specific rationalizations:** The skill's process section is too vague. If you cannot imagine an agent trying to shortcut the process, the process lacks enough prescriptive steps. Revise the process first, then rationalizations will become obvious.
+- **When validation fails on a section you believe is present:** The section heading may not match the expected format exactly. Check for typos, extra whitespace, or wrong heading level.
+- **When the skill spans more than 6 phases:** The skill is doing too much. Propose splitting into two skills with clear handoff points. A skill that tries to cover too many concerns becomes vague in each one.
+- **When you cannot write a test scenario that triggers a Gate:** The Gate condition is too abstract. Revise it to include specific, observable conditions that an agent would encounter.