@harness-engineering/cli 1.25.4 → 1.25.6

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