@harness-engineering/cli 1.25.4 → 1.25.6

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

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

@@ -973,15 +973,67 @@ All checks work from document analysis and codebase reads alone. Graph adds prec
 7. `harness validate` passes after all files are written
 8. The skill test suite passes (structure, schema, platform-parity, references)
 
+## Red Flags
+
+| Flag                                                                         | Corrective Action                                                                                                                                                      |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The spec looks internally consistent at a high level"                       | STOP. S1 requires checking each decision against Technical Design line by line. "High level" consistency misses contradictions in the details.                         |
+| "This assumption is obvious and doesn't need to be stated"                   | STOP. S3 exists because unstated assumptions cause the most damage when wrong. If it's obvious, writing it down costs nothing. Skipping it costs debugging time later. |
+| "The finding is minor so I'll auto-fix it without surfacing to the user"     | STOP. Only inferrable fixes are auto-fixed. If the fix involves a design choice — even one you think is obvious — surface it. You are not the designer.                |
+| `// TODO: add traceability` or `// spec gap — fill later` in spec/plan files | STOP. TODOs in specs are unfinished review. The spec is not converged. Fix the gap or surface it as a finding — do not defer it.                                       |
+
+**Review-never-fixes:** Soundness review identifies structural issues in specs and plans. It applies inferrable fixes (formatting, missing links, obvious gaps) but NEVER makes design decisions. If a finding requires judgment, surface it to the user — even if the "right" answer seems obvious. A reviewer who makes design decisions has stopped reviewing and started designing without the authority to do so.
+
+## Uncertainty Surfacing
+
+When a check produces ambiguous results, classify the ambiguity immediately:
+
+- **Blocking:** Cannot determine severity without user input (e.g., S1 finds a potential contradiction that might be intentional). Surface as a finding with `autoFixable: false`.
+- **Assumption:** Can classify if assumption is stated (e.g., "the spec uses 'fast' to mean sub-second, not sub-minute"). Apply the assumption, log it, and continue. If wrong, the convergence loop will catch it.
+- **Deferrable:** Ambiguity does not affect sign-off (e.g., unclear whether a non-goal is worth stating). Note as a suggestion-severity finding.
+
+Do not auto-fix ambiguous findings. Ambiguity means you lack context — applying a "fix" without context is guessing.
+
+## Rubric Compression
+
+Soundness check rubrics used internally MUST use compressed single-line format. Each check is one line with pipe-delimited fields:
+
+```
+mode|check-id|severity|criterion
+```
+
+**Example (Spec Mode rubric):**
+
+```
+spec|S1|error|No contradictions between decisions, technical design, and success criteria
+spec|S2|warning|Every goal has at least one success criterion; no orphan criteria
+spec|S3|warning|All implicit assumptions documented in Assumptions section
+spec|S4|warning|Error/edge cases covered; EARS unwanted-behavior gaps filled
+spec|S5|error|No references to nonexistent codebase capabilities or incompatible patterns
+spec|S6|error|No speculative features without requirement traceability
+spec|S7|warning|All success criteria are observable and measurable with concrete thresholds
+```
+
+**Why:** Verbose check descriptions inflate review context without improving check accuracy. Dense single-line rubrics give the same signal in fewer tokens, leaving more budget for actual document analysis.
+
+**Rules:**
+
+- Mode prefix must be `spec` or `plan`
+- Check ID must match the defined check IDs (S1-S7, P1-P7)
+- Severity must be `error` or `warning`
+- Maximum 80 characters per criterion text
+
 ## Rationalizations to Reject
 
-| Rationalization                                                                                          | Reality                                                                                                                                       |
-| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The spec looks coherent to me, so I can skip running the S1 internal coherence check"                   | Every check in the mode must run. S1 detects contradictions that human review frequently misses.                                              |
-| "This unstated assumption is obvious, so documenting it would be pedantic"                               | S3 exists because "obvious" assumptions cause the most damage when wrong. Cheapest to document, most expensive to miss.                       |
-| "The success criterion is somewhat vague but the team will know what it means"                           | S7 flags vague criteria like "should be fast" because they are untestable. Vague criteria survive brainstorming only to fail at verification. |
-| "This auto-fixable finding is minor, so I will just note it rather than applying the fix"                | Auto-fixable findings should be applied silently — that is the design intent. Skipping them ships known inferrable gaps.                      |
-| "The feasibility check found a signature mismatch but the code can probably be adapted during execution" | S5 red flags are always severity "error" and always surfaced. A spec referencing nonexistent modules produces a broken plan.                  |
+| Rationalization                                                                                          | Reality                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The spec looks coherent to me, so I can skip running the S1 internal coherence check"                   | Every check in the mode must run. S1 detects contradictions that human review frequently misses.                                                 |
+| "This unstated assumption is obvious, so documenting it would be pedantic"                               | S3 exists because "obvious" assumptions cause the most damage when wrong. Cheapest to document, most expensive to miss.                          |
+| "The success criterion is somewhat vague but the team will know what it means"                           | S7 flags vague criteria like "should be fast" because they are untestable. Vague criteria survive brainstorming only to fail at verification.    |
+| "This auto-fixable finding is minor, so I will just note it rather than applying the fix"                | Auto-fixable findings should be applied silently — that is the design intent. Skipping them ships known inferrable gaps.                         |
+| "The feasibility check found a signature mismatch but the code can probably be adapted during execution" | S5 red flags are always severity "error" and always surfaced. A spec referencing nonexistent modules produces a broken plan.                     |
+| "The convergence loop is taking too long, so I will skip the re-check and declare converged"             | Convergence requires the issue count to stop decreasing. Declaring convergence without a re-check is falsifying the exit condition.              |
+| "This spec is well-written enough that a soundness review would not find anything"                       | Every spec gets a soundness review. Well-written specs still have unstated assumptions (S3) and vague criteria (S7). The review is not optional. |
 
 ## Examples
 

package/dist/agents/skills/claude-code/harness-tdd/SKILL.md

@@ -85,6 +85,16 @@ harness scan [path]
 
 Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
 
+### Uncertainty Surfacing
+
+When you encounter an unknown during a RED-GREEN-REFACTOR cycle, classify it immediately:
+
+- **Blocking:** Cannot write a meaningful test without resolving this (e.g., unclear expected behavior). STOP and surface to human with options.
+- **Assumption:** Can write the test if assumption is stated explicitly (e.g., "input is always non-null"). Document the assumption in a test comment and continue. If the assumption proves wrong, the test must be revised.
+- **Deferrable:** Does not affect the current cycle (e.g., performance characteristics). Record for a future cycle.
+
+Do not bury unknowns in test code. An unstated assumption in a test is a test that passes for the wrong reason.
+
 ### Cycle Rhythm
 
 Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycles. Each cycle should take 2-15 minutes. If a cycle takes longer than 15 minutes, the step is too large — break it down.
@@ -122,6 +132,8 @@ Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycle
 | "The test passed on the first run, so TDD is working"                                               | If the test passed without implementing the production code, either the behavior already exists or the test is wrong. You must watch the test FAIL for the right reason before proceeding to GREEN. |
 | "I will test multiple behaviors in this one test to be efficient"                                   | One test, one assertion, one behavior. Multi-behavior tests make it impossible to pinpoint which behavior broke when the test fails.                                                                |
 | "Harness validate can wait until the end of the feature since it slows down the cycle"              | No skipping VALIDATE. Every cycle must end with harness check-deps and harness validate. A passing test with a failing validation means the implementation violated a project constraint.           |
+| "This edge case is unlikely, so I will skip writing a test for it"                                  | If the edge case can happen, it needs a test. Unlikely is not impossible. The test is cheap; the production bug is expensive.                                                                       |
+| "The existing tests cover this behavior implicitly, so no new test is needed"                       | Implicit coverage is not TDD. If you cannot point to a specific test that asserts the specific behavior, write one. Implicit coverage breaks silently when the implying test changes.               |
 
 ## Examples
 
@@ -166,6 +178,15 @@ git commit -m "feat(cart): calculate total from item price and quantity"
 
 **Next cycle (RED):** Write a test for empty array input. Watch it fail (or pass — if it passes, the behavior is already handled). Continue.
 
+## Red Flags
+
+| Flag                                                                                      | Corrective Action                                                                                                                               |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I'll write the test after since I know what the code should do"                          | STOP. Test-after is not TDD. Delete the production code, write the test, watch it fail.                                                         |
+| "The test is trivial/obvious so I don't need to watch it fail"                            | STOP. Observing failure proves the test catches the defect. A test you haven't seen fail might pass for the wrong reason.                       |
+| "I'll batch these small tests together to save time"                                      | STOP. Each RED-GREEN-REFACTOR cycle is atomic. Batching obscures which behavior broke when a test fails.                                        |
+| `// removed old validation` or `// TODO: re-add error handling` replacing functional code | STOP. Code-to-comment replacement is deletion with a fig leaf. Either keep the code or delete it cleanly with a test proving it is unnecessary. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/skills/claude-code/harness-verification/SKILL.md

@@ -43,6 +43,20 @@ When no arguments are provided (standalone invocation), session slug is unknown
 
 ---
 
+### Uncertainty Surfacing
+
+When you encounter an unknown during verification, classify it immediately:
+
+- **Blocking:** Cannot determine pass/fail without resolving this (e.g., spec does not define expected behavior for a scenario, cannot run tests due to missing dependency). STOP and escalate.
+- **Assumption:** Can verify if assumption is stated (e.g., "this module is internal-only so WIRED check against external consumers is not applicable"). Document the assumption in the report. If wrong, verification must be re-run.
+- **Deferrable:** Does not affect current verification (e.g., whether additional test coverage would be beneficial). Note in report as an observation.
+
+Do not mark PASS with unstated assumptions. An assumption-laden PASS is a false positive.
+
+**Review-never-fixes:** Verification identifies gaps. Verification never fills them. If you find a stub, missing test, or unwired artifact, record it as a FAIL with evidence. Do not implement the fix — that is the executor's job. A verifier who fixes is no longer verifying independently.
+
+---
+
 ### Context Loading
 
 Before running verification levels, load session context:
@@ -284,6 +298,15 @@ L2|real-logic|Functions contain meaningful logic, not just hardcoded returns
 - Maximum 80 characters per criterion text
 - Rubric entries are guidance — the verification levels define the authoritative checks
 
+## Red Flags
+
+| Flag                                                                   | Corrective Action                                                                                                                                              |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Tests passed earlier, so I just need to check the files exist"        | STOP. Iron Law: fresh evidence in THIS session. "Earlier" is cached — run the checks now.                                                                      |
+| "The implementation looks substantive at a glance"                     | STOP. Level 2 requires thorough reading, not glancing. Stubs designed to look real (e.g., functions with only a log statement) are the whole reason L2 exists. |
+| "The artifact is exported so it must be wired"                         | STOP. Export without import is dead code. Trace the actual usage chain: import, call, test, pass. "Must be" is not evidence.                                   |
+| `// stubbed for now` or `// implementation pending` in production code | STOP. These are Level 2 failures. Do not proceed to Level 3. Do not fix them yourself — record as FAIL and report.                                             |
+
 ## Non-Determinism Tolerance
 
 Mechanical checks (tests, lint, types) are binary pass/fail. No tolerance.
@@ -292,12 +315,14 @@ For behavioral verification (convention adherence, style guides), accept thresho
 
 ## Rationalizations to Reject
 
-| Rationalization                                            | Reality                                                                                                                        |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| "Tests passed earlier, no need to re-run"                  | Iron Law forbids cached results. All evidence must be fresh in THIS session.                                                   |
-| "File exists and has code, skip thorough read for Level 2" | Level 2 requires thorough reading. Scanning for TODO, throw Error, empty functions catches stubs that look real.               |
-| "Artifact is imported by a test file, so passes Level 3"   | Import is necessary but not sufficient. Test must assert on behavior and not be skipped.                                       |
-| "Verification report probably looks fine from memory"      | "Should", "probably", "seems to", "I believe" are forbidden. Replace with "verified: [evidence]" or "not verified: [missing]." |
+| Rationalization                                                         | Reality                                                                                                                                                             |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Tests passed earlier, no need to re-run"                               | Iron Law forbids cached results. All evidence must be fresh in THIS session.                                                                                        |
+| "File exists and has code, skip thorough read for Level 2"              | Level 2 requires thorough reading. Scanning for TODO, throw Error, empty functions catches stubs that look real.                                                    |
+| "Artifact is imported by a test file, so passes Level 3"                | Import is necessary but not sufficient. Test must assert on behavior and not be skipped.                                                                            |
+| "Verification report probably looks fine from memory"                   | "Should", "probably", "seems to", "I believe" are forbidden. Replace with "verified: [evidence]" or "not verified: [missing]."                                      |
+| "I found a stub so I'll quickly implement it to make verification pass" | Verification identifies gaps — verification never fills them. Record the stub as a FAIL. The executor fixes it. A verifier who implements is no longer independent. |
+| "The spec only mentions 3 behaviors but I'll verify 5 to be thorough"   | Verify what the spec requires, not what you think it should require. Extra verification against unstated requirements conflates verification with spec review.      |
 
 ## Examples
 

package/dist/agents/skills/codex/enforce-architecture/SKILL.md

@@ -272,6 +272,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 violation is minor — just one import"       | One violation sets a precedent. Enforce the constraint or document an explicit exception with rationale.                             |

package/dist/agents/skills/codex/harness-api-design/SKILL.md

@@ -332,6 +332,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 an internal API, breaking changes are fine" | Internal consumers break too. Version the change or coordinate the migration explicitly.                  |

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

@@ -312,6 +312,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                                                                                                                                                                   |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | "This will be easier to maintain"                            | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase.                                                                       |

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

@@ -307,6 +307,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 one would guess this token format"                               | Security by obscurity. Tokens must be cryptographically secure regardless of format predictability. |

package/dist/agents/skills/codex/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/codex/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/codex/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/codex/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/codex/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.