@harness-engineering/cli 1.23.1 → 1.23.2

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

@@ -253,6 +253,16 @@ def test_admin_can_delete_any_project():
     assert admin.has_perm('delete_project', project)
 ```
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                                    | Reality                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The test only needs one user — I'll just hardcode `userId: 1` rather than building a factory."                    | Hardcoded IDs cause silent test failures when the database is reset, when tests run in parallel, or when another test creates a conflicting record. Factories with sequences or UUIDs exist precisely to avoid this class of failure. One hardcoded ID is how fragile test suites start.                            |
+| "The factory produces objects that are close enough to valid — the test just needs to override two fields anyway." | A factory that requires overrides to produce a valid object has wrong defaults. The factory's zero-override output must pass model validation. If it does not, the factory is documenting the wrong defaults and tests that rely on overrides will break when the model changes.                                    |
+| "Cleanup is handled by rolling back the test transaction — I don't need explicit teardown."                        | Transaction rollback works until it does not: tests that span multiple connections, tests that call external APIs, or tests that write to a queue or file system all escape the transaction. Explicit cleanup is the only strategy that covers all cases, including tests that use features you have not built yet. |
+| "We can share the same seeded dataset across all integration tests to avoid the overhead of per-test factories."   | Shared mutable data means test A's side effect becomes test B's precondition. When tests fail intermittently based on execution order, the root cause is always shared state. The overhead of per-test factory creation is small compared to the cost of debugging order-dependent failures.                        |
+| "The model only has three fields — writing a factory is more overhead than just constructing the object inline."   | Today's three-field model becomes tomorrow's ten-field model with required foreign keys. Inline construction scales linearly with model complexity. A factory written once absorbs all future field additions in one place. The overhead argument inverts as the codebase grows.                                    |
+
 ## Gates
 
 - **No hardcoded IDs in factories.** Factories must generate unique IDs per instance. Hardcoded IDs cause collision failures when tests run in parallel. Use sequences or UUIDs.

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

@@ -256,6 +256,16 @@ Phase 4: VALIDATE
   Result: NEEDS_ATTENTION -- 3 errors requiring translator coordination
 ```
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                                                                                                 | Reality                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "There's no voice guide, but the existing strings have a consistent tone — I can infer the voice from them and skip generating `VOICE.md`."                                     | Inferring voice from existing strings that may themselves have quality problems is circular. The GUIDE phase must produce a `VOICE.md` draft when none exists. Without a written guide, the audit has no stable reference for subsequent runs.                                   |
+| "This error message says 'Invalid credentials' — the rewrite is obvious, so I'll apply it without waiting for confirmation."                                                    | The gates require no semantic changes and no bulk changes without confirmation. Even obvious rewrites must be presented in the structured report format with the `UXC-ERR` code, current string, recommendation, rule, and rationale — not applied directly.                     |
+| "The `{count}` interpolation variable is in the original string — my rewrite restructured the sentence so the variable moved to a different position. That's still compatible." | Rewrites must preserve interpolation variables exactly as they appear. If restructuring a sentence moves a variable to a position where the resulting translation would be grammatically wrong in target locales, the rewrite is invalid. Flag it for translator review instead. |
+| "There are 8 occurrences of 'Sign in' and 3 of 'Log in' — I'll just update all 11 to 'Sign in' since that's clearly the majority term."                                         | Terminology standardization affecting more than 5 files requires presenting the full change list and waiting for human confirmation before recommending. The majority term is a reasonable default recommendation, but the human must approve the batch.                         |
+| "This empty state just says 'No results' — that's a warning, not an error, so I can deprioritize it and skip the rewrite."                                                      | Every warning finding requires a specific rewrite, not just a note that one is needed. The GUIDE phase produces rewrites for all error and warning findings. Skipping the rewrite for any classified finding produces an incomplete report.                                      |
+
 ## Gates
 
 - **No rewrite may change semantic meaning.** If a recommended rewrite alters what the user understands about the situation or available actions, it is rejected. Rewrites improve clarity and tone, not content.

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

@@ -359,6 +359,15 @@ For behavioral verification (did the agent follow a convention, did the output m
 
 If a behavioral convention fails more than 40% of the time, the convention needs rewriting. Blame the instruction, not the executor.
 
+## Rationalizations to Reject
+
+| Rationalization                                                                       | Reality                                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The tests passed when I ran them earlier, so I do not need to re-run them now"       | The Iron Law forbids cached results. All verification evidence must be collected fresh in THIS session.                                                                                                 |
+| "The file exists and has code in it, so I can skip reading it thoroughly for Level 2" | Level 2 (SUBSTANTIVE) requires reading the file content thoroughly. Scanning for TODO, throw new Error, empty functions, and hardcoded return values catches stubs that look like real implementations. |
+| "This artifact is tested by a file that imports it, so it passes Level 3 WIRED"       | Being imported is necessary but not sufficient for WIRED. The test must actually make assertions about the artifact's behavior and not be skipped.                                                      |
+| "The verification report probably looks fine based on what I remember"                | The words "should", "probably", "seems to", and "I believe" are forbidden in verification reports. Replace with "verified: [evidence]" or "not verified: [what is missing]."                            |
+
 ## Examples
 
 ### Example: Verifying a New Service Module

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

@@ -125,6 +125,16 @@ This skill is entirely deterministic. There are no LLM judgment calls anywhere i
 - [ ] Overall verdict correctly reflects individual results
 - [ ] Failed checks include error output summary
 
+## Rationalizations to Reject
+
+These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.
+
+| Rationalization                                                                                    | Why It Is Wrong                                                                                                                                 |
+| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The lint command is slow and the code looks clean, so I will skip it"                             | No skipping. If a command is detected, it runs. Period. There is no "looks clean" judgment call.                                                |
+| "The typecheck failed but it is just a missing type declaration, so I will interpret it as a pass" | The exit code is the only signal. No judgment calls. Exit code non-zero equals FAIL, always.                                                    |
+| "I will fix the lint error I found and re-run, since it is a quick fix"                            | No file modifications. This skill is read-only plus command execution. Fixing errors is the responsibility of the skill that produced the code. |
+
 ## Examples
 
 ### Example: Node.js Project

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

@@ -242,6 +242,16 @@ const preview: Preview = {
 export default preview;
 ```
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                                      | Reality                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The baseline screenshots are committed locally but not pushed — CI can capture its own baselines on the first run." | CI baselines captured without human review become the source of truth for a rendering state nobody verified. Every baseline must be manually inspected before committing. A CI-generated baseline for a broken layout will pass every future comparison until someone notices the visual bug manually.                                               |
+| "The diff is only 0.3% of pixels — it's probably just font rendering noise, not a real regression."                  | "Probably" is not a classification. Investigate the diff to determine if it is environmental noise or a real change before dismissing it. If it is noise, fix the source (fonts, animations) and lower the threshold. If it is a real change, update the baseline with intent. Skipping investigation means regressions hide behind noise tolerance. |
+| "We have 300 components — it's not practical to have baselines for all of them."                                     | Start with shared design system components (buttons, inputs, modals) and page-level layouts. Partial coverage is better than none, and it is easier to add coverage incrementally than to audit an entire codebase for visual regressions after the fact. Prioritize high-visibility, high-change-frequency surfaces first.                          |
+| "The visual test suite takes 20 minutes — let's just run it manually before releases instead of in CI."              | Manual pre-release checks are skipped under deadline pressure. Visual regression is most valuable on every PR, where the author is still in context and the fix is immediate. A 20-minute suite is a signal to optimize (affected-story detection, parallelization), not to remove CI integration.                                                   |
+| "The component changed intentionally — I'll just auto-accept the diff without reviewing the new screenshot."         | Auto-accepting without review permanently resets the baseline to whatever was rendered, correct or not. Every baseline update requires a human to look at the new screenshot and confirm it matches design intent. The review is not a formality — it is the entire point of the approval workflow.                                                  |
+
 ## Gates
 
 - **No non-deterministic screenshots.** If the same code produces different screenshots on consecutive runs, the rendering is not stabilized. Fix animations, dynamic content, and font loading before capturing baselines.

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

@@ -16,14 +16,14 @@
 
 ### Phase 1: ASSESS — Determine Current State
 
-1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.yaml`, and any skill definitions. Their presence determines whether this is a new project or a migration.
+1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.
 
 2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.
 
 2b. **For existing projects with detectable frameworks:** Run `harness init` without flags first. The command auto-detects frameworks (FastAPI, Django, Gin, Axum, Spring Boot, Next.js, React+Vite, Vue, Express, NestJS) by scanning project files. Present the detection result to the human and ask for confirmation before proceeding. If detection fails, ask the human to specify `--framework` manually.
 
 3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
-   - **Basic:** Has `AGENTS.md` and `harness.yaml` with project metadata. No layers, no skills, no dependency constraints.
+   - **Basic:** Has `AGENTS.md` and `harness.config.json` with project metadata. No layers, no skills, no dependency constraints.
    - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
    - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.
 
@@ -44,13 +44,13 @@
    **Supported languages:** typescript, python, go, rust, java
 
 2. **Review generated files.** `harness init` creates:
-   - `harness.yaml` — Project configuration (name, stack, adoption level)
+   - `harness.config.json` — Project configuration (name, stack, adoption level)
    - `.harness/` directory — State and learnings storage
    - `AGENTS.md` — Agent instructions (template, needs customization)
    - Layer definitions (intermediate and above)
    - Dependency constraints (intermediate and above)
 
-3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.yaml`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
+3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.config.json`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
 
 ### Phase 3: CONFIGURE — Customize for the Project
 
@@ -63,7 +63,7 @@
    - Known constraints and forbidden patterns
    - Links to relevant documentation
 
-3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.yaml` and ensure they match the actual codebase structure.
+3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.config.json` and ensure they match the actual codebase structure.
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
@@ -75,7 +75,7 @@
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
-   - `harness.yaml` schema validity
+   - `harness.config.json` schema validity
    - `AGENTS.md` presence and required sections
    - Layer definitions (if intermediate+)
    - Dependency constraints (if intermediate+)
@@ -111,7 +111,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 
 ## Success Criteria
 
-- `harness.yaml` exists and passes schema validation
+- `harness.config.json` exists and passes schema validation
 - `AGENTS.md` exists with project-specific content (not just the template)
 - `.harness/` directory exists with appropriate state files
 - `harness validate` passes with zero errors
@@ -121,6 +121,15 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - All generated files are committed in a single atomic commit
 - i18n configuration is set if the human chose to enable it during init
 
+## Rationalizations to Reject
+
+| Rationalization                                                          | Why It Is Wrong                                                                                                                        |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| "The generated AGENTS.md template looks fine -- no need to customize it" | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.      |
+| "We should start at the advanced level since we want full coverage"      | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.       |
+| "I will skip the i18n question to keep setup fast"                       | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.  |
+| "Validation passed, so the project is ready"                             | Phase 4 includes harness check-deps for intermediate+ projects and knowledge graph initialization. Validation alone is not sufficient. |
+
 ## Examples
 
 ### Example: New TypeScript Project (Basic Level)
@@ -138,7 +147,7 @@ Human confirms: "Basic is fine for now."
 
 ```bash
 harness init --level basic --framework express
-# Creates: harness.yaml, .harness/, AGENTS.md (template)
+# Creates: harness.config.json, .harness/, AGENTS.md (template)
 ```
 
 **CONFIGURE:**
@@ -159,7 +168,7 @@ Edit AGENTS.md:
 
 ```bash
 harness validate  # Pass — basic level checks satisfied
-git add harness.yaml .harness/ AGENTS.md
+git add harness.config.json .harness/ AGENTS.md
 git commit -m "feat: initialize harness project at basic level"
 ```
 
@@ -168,7 +177,7 @@ git commit -m "feat: initialize harness project at basic level"
 **ASSESS:**
 
 ```
-Read harness.yaml — level: basic
+Read harness.config.json — level: basic
 Read AGENTS.md — exists, has project-specific content
 Run: harness validate — passes at basic level
 Recommend: intermediate (add layers and dependency constraints)
@@ -179,14 +188,14 @@ Human confirms: "Yes, we're ready for layers."
 
 ```bash
 harness init --level intermediate --migrate
-# Preserves existing harness.yaml and AGENTS.md
+# Preserves existing harness.config.json and AGENTS.md
 # Adds: layer definitions template, dependency constraints template
 ```
 
 **CONFIGURE:**
 
 ```
-Define layers in harness.yaml:
+Define layers in harness.config.json:
   - presentation: src/routes/, src/middleware/
   - business: src/services/, src/models/
   - data: src/repositories/, src/db/
@@ -214,7 +223,7 @@ git commit -m "feat: migrate harness project to intermediate level with layers"
 **Basic (start here):**
 
 - `AGENTS.md` with project context
-- `harness.yaml` with metadata
+- `harness.config.json` with metadata
 - `harness validate` runs in development
 
 **Intermediate (add structure):**

package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md

@@ -101,6 +101,15 @@ Good context engineering treats AGENTS.md as a **dynamic knowledge base**, not a
 - AGENTS.md sections accurately describe current module purposes, constraints, and relationships
 - A new AI agent reading AGENTS.md can navigate the codebase and make correct decisions without additional guidance
 
+## Rationalizations to Reject
+
+| Rationalization                                                            | Why It Is Wrong                                                                                                                                                           |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The automated checks passed, so AGENTS.md is accurate"                    | Phase 1 says automated tools catch structural issues but miss semantic drift. Manual review of each section is required.                                                  |
+| "This module is small and internal -- it does not need an AGENTS.md entry" | Undocumented files are the highest priority finding. Even small internal modules need at least a purpose statement.                                                       |
+| "AGENTS.md is severely outdated -- let me rewrite it from scratch"         | Do not attempt to fix everything at once when there are >20 issues. Prioritize: broken links first, then undocumented public APIs.                                        |
+| "I will add the file paths and leave the descriptions for later"           | Purpose-first descriptions, relationship mapping, and gotchas are what make context engineering useful. A file listing without context is marginally better than nothing. |
+
 ## Examples
 
 ### Example: New module added but not documented

package/dist/agents/skills/codex/add-harness-component/SKILL.md

@@ -29,11 +29,11 @@
    - **Component:** Name, which layer it belongs to, what it depends on, what will depend on it
    - **Skill:** Name, purpose, type (rigid or flexible), triggers
 
-3. **Check prerequisites.** The project must already be initialized with harness. If `harness.yaml` does not exist, stop and run initialize-harness-project first.
+3. **Check prerequisites.** The project must already be initialized with harness. If `harness.config.json` does not exist, stop and run initialize-harness-project first.
 
 ### Phase 2: VALIDATE — Check Against Existing Constraints
 
-1. **Read the current configuration.** Load `harness.yaml` and `AGENTS.md` to understand existing layers, constraints, and architecture.
+1. **Read the current configuration.** Load `harness.config.json` and `AGENTS.md` to understand existing layers, constraints, and architecture.
 
 2. **Verify the new component does not conflict:**
    - Does the layer name already exist?
@@ -53,7 +53,7 @@
    - Component: `harness add component <name> --layer <layer-name>`
    - Skill: `harness add skill <name> --type <rigid|flexible>`
 
-2. **Review generated files and configuration changes.** `harness add` modifies `harness.yaml` and may generate template files. Check that the changes look correct.
+2. **Review generated files and configuration changes.** `harness add` modifies `harness.config.json` and may generate template files. Check that the changes look correct.
 
 3. **Create the actual code or content.** `harness add` creates the configuration entry but not necessarily the implementation. Create the directories, files, and initial code as needed.
 
@@ -63,7 +63,7 @@
 
 2. **Update `AGENTS.md`.** Add the new component to the architecture section. Document its purpose, boundaries, and relationships to other components. This keeps agent instructions accurate.
 
-3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.yaml` reflects the actual import graph.
+3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.config.json` reflects the actual import graph.
 
 4. **For new skills:** Write the `skill.yaml` and `SKILL.md` files following the harness skill format. Use harness-skill-authoring for guidance on writing good skill content.
 
@@ -84,7 +84,7 @@ harness scan [path]
 Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
 
 3. **If validation fails,** fix the issues before committing. Common causes:
-   - New layer not properly registered in `harness.yaml`
+   - New layer not properly registered in `harness.config.json`
    - Component placed in wrong directory for its declared layer
    - Imports from forbidden layers
    - `AGENTS.md` references outdated architecture
@@ -102,7 +102,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
 ## Success Criteria
 
-- The new component is properly registered in `harness.yaml`
+- The new component is properly registered in `harness.config.json`
 - The component's files exist in the correct directories for its declared layer
 - `AGENTS.md` is updated to reflect the new component
 - `harness validate` passes after the addition
@@ -110,6 +110,15 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 - No circular dependencies were introduced
 - The addition is committed as a single atomic commit
 
+## Rationalizations to Reject
+
+| Rationalization                                                                | Why It Is Wrong                                                                                                                                     |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I will add the component and fix any constraint violations later"             | Phase 2 requires running harness check-deps for a clean baseline BEFORE adding. Phase 5 requires it to pass AFTER adding.                           |
+| "AGENTS.md does not need updating for a small internal component"              | Phase 4 explicitly requires updating AGENTS.md for every new component. Without it, AI agents have no context.                                      |
+| "The new layer imports are obvious, so I do not need to check for circularity" | Phase 2 checks whether new dependency relationships create circular imports. Circular dependencies are invisible until they cause runtime failures. |
+| "I will commit the config change and the code separately for cleaner history"  | The success criteria require a single atomic commit. Splitting creates a window where config references a nonexistent component.                    |
+
 ## Examples
 
 ### Example: Adding a New Layer
@@ -122,7 +131,7 @@ DETERMINE: Adding a layer. Name: infrastructure. Dirs: src/infrastructure/.
   Imported by: business layer (services call external APIs through infrastructure).
 
 VALIDATE:
-  Read harness.yaml — existing layers: presentation, business, data.
+  Read harness.config.json — existing layers: presentation, business, data.
   No conflict with "infrastructure" name.
   Run: harness check-deps — passes (clean baseline).
 
@@ -131,13 +140,13 @@ ADD:
   mkdir -p src/infrastructure
 
 WIRE:
-  Update harness.yaml: allow business → infrastructure imports.
+  Update harness.config.json: allow business → infrastructure imports.
   Update AGENTS.md: document infrastructure layer purpose and boundaries.
 
 VERIFY:
   harness validate    # Pass
   harness check-deps  # Pass
-  git add harness.yaml AGENTS.md src/infrastructure/
+  git add harness.config.json AGENTS.md src/infrastructure/
   git commit -m "feat: add infrastructure layer for external API clients"
 ```
 
@@ -157,7 +166,7 @@ WIRE:
 
 VERIFY:
   harness validate  # Pass
-  git add harness.yaml AGENTS.md
+  git add harness.config.json AGENTS.md
   git commit -m "feat: track API spec for documentation drift detection"
 ```
 
@@ -170,7 +179,7 @@ DETERMINE: Adding a component. Name: notification-service. Layer: business.
   Depends on: data layer (notification repository). Depended on by: presentation layer (routes).
 
 VALIDATE:
-  Read harness.yaml — business layer exists, maps to src/services/.
+  Read harness.config.json — business layer exists, maps to src/services/.
   No existing notification-service directory.
   business → data is an allowed import. Presentation → business is allowed.
   Run: harness check-deps — passes.
@@ -187,6 +196,6 @@ WIRE:
 VERIFY:
   harness validate    # Pass
   harness check-deps  # Pass
-  git add harness.yaml AGENTS.md src/services/notification-service.*
+  git add harness.config.json AGENTS.md src/services/notification-service.*
   git commit -m "feat: add notification service to business layer"
 ```

package/dist/agents/skills/codex/align-documentation/SKILL.md

@@ -160,6 +160,15 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 - Documentation updates are committed with clear references to the triggering code change
 - No orphaned references to old names, paths, or deleted features remain
 
+## Rationalizations to Reject
+
+| Rationalization                                                               | Why It Is Wrong                                                                                                                                        |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The code change is small, so docs probably do not need updating"             | A single function signature change changes the contract for every consumer. Map every code change to its documentation impact regardless of diff size. |
+| "I updated the main reference -- the other mentions can wait"                 | Orphaned references in AGENTS.md and tutorials actively mislead agents and developers. Phase 4 requires verifying no orphaned references remain.       |
+| "I will match the new documentation to what I think the code does"            | Phase 4 requires cross-checking each update against the actual code. Documentation that is wrong is worse than documentation that is missing.          |
+| "The existing doc style is inconsistent, so I will improve it while aligning" | Follow the existing style. Documentation alignment is about accuracy, not style improvement. Style changes should be a separate effort.                |
+
 ## Examples
 
 ### Example: Syncing docs after a module rename

package/dist/agents/skills/codex/check-mechanical-constraints/SKILL.md

@@ -116,6 +116,15 @@ For each violation that was not auto-fixed, report:
 - Auto-fixed changes are verified by running the test suite
 - No violations are suppressed without explicit team approval and a documented reason
 
+## Rationalizations to Reject
+
+| Rationalization                                                                       | Why It Is Wrong                                                                                                                         |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| "This forbidden import is just for one utility function -- I will suppress it inline" | The gate says no suppressing rules without documentation. Undocumented suppressions accumulate and erode the constraint system.         |
+| "The auto-fix looks right, so I do not need to re-run tests"                          | The gate says no auto-fix without test verification. Even import reordering can break code that depends on module initialization order. |
+| "This is just a Tier 2 warning -- it can wait until after merge"                      | Tier 2 violations must be resolved before merge to main. Warnings that accumulate on main become the new baseline.                      |
+| "The linter rule does not make sense for this project, so I will just disable it"     | Propose a config change with justification, do not disable the rule inline. Fix it at the configuration level.                          |
+
 ## Examples
 
 ### Example: Forbidden import detected

package/dist/agents/skills/codex/cleanup-dead-code/SKILL.md

@@ -191,6 +191,17 @@ Code behind feature flags or environment checks may appear dead in the default c
 - No dynamically-imported, type-only, or side-effect code was accidentally deleted
 - Each cleanup commit is atomic and has a descriptive message explaining what was removed and why
 
+## Rationalizations to Reject
+
+These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.
+
+| Rationalization                                                                                        | Why It Is Wrong                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This export has zero static imports, so it is definitely dead and safe to remove"                     | Zero static imports does not mean zero consumers. Dynamic imports, type-only imports, side-effect imports, and package entry points all create false positives. |
+| "I removed the dead code and the tests pass, so I do not need to run harness validate and check-deps"  | Both harness validate and harness check-deps must pass after every cleanup. Dead code removal can introduce dependency violations.                              |
+| "The convergence loop found new dead code after my fixes, but it is probably just noise from the tool" | Removing dead code creates more dead code. The convergence loop exists to catch these cascades. If the issue count decreased, loop back.                        |
+| "The entropy report has 60 items but I can clean them all up in one pass to be thorough"               | When the report is very large (>50 items), pick the highest-confidence dead code first. Attempting everything at once risks compound errors.                    |
+
 ## Examples
 
 ### Example: Removing unused utility functions

package/dist/agents/skills/codex/detect-doc-drift/SKILL.md

@@ -127,6 +127,15 @@ Group findings by documentation file so that fixes can be applied file-by-file.
 - No documentation references deleted files, functions, or features
 - Drift findings are prioritized and assigned to the appropriate fix cycle
 
+## Rationalizations to Reject
+
+| Rationalization                                                           | Why It Is Wrong                                                                                                                      |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| "The docs are close enough -- a renamed function is obvious from context" | Renamed references in AGENTS.md cause AI agents to hallucinate about non-existent code. Precision matters.                           |
+| "We only changed internal code, so the docs do not need checking"         | Internal API docs with wrong signatures waste developer debugging time. Changed-behavior-not-reflected drift is High priority.       |
+| "There are too many findings to deal with right now, so skip the scan"    | The escalation protocol exists for this case: focus on Critical and High items, create a tracking issue for the rest.                |
+| "We can rely on code review to catch stale docs"                          | Code reviewers focus on code correctness, not documentation cross-references. harness check-docs catches what humans routinely miss. |
+
 ## Examples
 
 ### Example: Renamed function detected

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

@@ -272,21 +272,11 @@ 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
-
-- **"The violation is minor — just one import"** — One violation sets a precedent. Enforce the constraint or document an explicit exception with rationale.
-- **"It works, so the architecture must be fine"** — Working code with bad architecture is technical debt with compound interest. Correct function does not excuse structural violations.
-- **"This is a legacy module, different rules apply"** — Legacy does not mean exempt. Either the constraint applies or it needs an explicit documented exception.
+| Rationalization                                  | Reality                                                                                                                              |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| "The violation is minor — just one import"       | One violation sets a precedent. Enforce the constraint or document an explicit exception with rationale.                             |
+| "It works, so the architecture must be fine"     | Working code with bad architecture is technical debt with compound interest. Correct function does not excuse structural violations. |
+| "This is a legacy module, different rules apply" | Legacy does not mean exempt. Either the constraint applies or it needs an explicit documented exception.                             |
 
 ## Escalation
 

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

@@ -261,6 +261,16 @@ A11Y-030 [info] Hardcoded color value not from design token set
 - `A11Y-031`: Contrast failure -- fix requires choosing a darker color. Escalate to design tokens or get human input on replacement color.
 - `A11Y-001`: The `alt=""` fix assumes decorative. If the icon conveys meaning, human must write descriptive alt text.
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                                                         | Reality                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The contrast ratio is 4.4:1 — that's essentially 4.5:1 and the difference is imperceptible. I'll mark it passing."                     | WCAG AA requires exactly 4.5:1 for normal text. 4.4:1 fails. There is no rounding or visual perception exception in the standard. Flag the failure with the actual ratio and let the user decide how to remediate.                                                             |
+| "This `<div onClick>` already has good visual styling — adding `role='button'` and a keyboard handler is unnecessary clutter."          | A clickable `<div>` without `role="button"` and `onKeyDown` is inaccessible to keyboard-only users and screen reader users. Visual styling has no bearing on ARIA semantics or keyboard reachability. This is A11Y-012, always flagged.                                        |
+| "The automated fix for this `<img>` alt attribute is obvious — I'll apply it without showing the diff since it's just adding `alt=''`." | Every automated fix must be presented as a before/after diff before being written to disk. This is a hard gate. The correct alt value for non-decorative images requires human judgment, and even `alt=""` makes a semantic claim about decorativeness that must be confirmed. |
+| "I18n is enabled, so I'll skip the `lang` and `dir` attribute checks entirely — harness-i18n will catch them."                          | Deferral to harness-i18n is conditional on `i18n.enabled: true` in config. If i18n is not configured, these checks remain part of this skill's scan. Always read the config before skipping any check category.                                                                |
+| "There are 15 findings in this component — I'll fix the easy ones automatically and leave the rest without reporting them explicitly."  | All findings must be reported, regardless of whether they are auto-fixable. The report is the primary deliverable of the REPORT phase. Selectively reporting only fixable violations hides the full accessibility debt from the team.                                          |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

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

@@ -332,21 +332,11 @@ 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
-
-- **"It's an internal API, breaking changes are fine"** — Internal consumers break too. Version the change or coordinate the migration explicitly.
-- **"The field name is obvious enough"** — API field names are a public contract. Follow existing naming conventions and document the semantics.
-- **"Nobody uses that endpoint anyway"** — Verify with access logs or usage data. Assumptions about usage without evidence lead to silent breakages.
+| Rationalization                                   | Reality                                                                                                   |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| "It's an internal API, breaking changes are fine" | Internal consumers break too. Version the change or coordinate the migration explicitly.                  |
+| "The field name is obvious enough"                | API field names are a public contract. Follow existing naming conventions and document the semantics.     |
+| "Nobody uses that endpoint anyway"                | Verify with access logs or usage data. Assumptions about usage without evidence lead to silent breakages. |
 
 ## Escalation
 

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

@@ -309,21 +309,11 @@ 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
-
-- **"This will be easier to maintain"** — Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase.
-- **"It's the modern approach"** — Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.
-- **"Other teams do it this way"** — Other teams have different constraints. Evaluate the option on this codebase's specific merits.
+| Rationalization                   | Reality                                                                                             |
+| --------------------------------- | --------------------------------------------------------------------------------------------------- |
+| "This will be easier to maintain" | Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase. |
+| "It's the modern approach"        | Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.            |
+| "Other teams do it this way"      | Other teams have different constraints. Evaluate the option on this codebase's specific merits.     |
 
 ## Escalation
 

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

@@ -307,21 +307,11 @@ 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
-
-- **"No one would guess this token format"** — Security by obscurity. Tokens must be cryptographically secure regardless of format predictability.
-- **"This is an internal service, auth is less critical"** — Internal services are lateral movement targets. Authenticate all service boundaries.
-- **"The frontend validates permissions, so the backend doesn't need to"** — Client-side checks are bypassable. Server-side authorization is the only real enforcement.
+| Rationalization                                                      | Reality                                                                                             |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| "No one would guess this token format"                               | Security by obscurity. Tokens must be cryptographically secure regardless of format predictability. |
+| "This is an internal service, auth is less critical"                 | Internal services are lateral movement targets. Authenticate all service boundaries.                |
+| "The frontend validates permissions, so the backend doesn't need to" | Client-side checks are bypassable. Server-side authorization is the only real enforcement.          |
 
 ## Escalation
 

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

@@ -720,6 +720,16 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 - Checkpoint commits fire after every passing checkpoint; recovery commits fire on retry budget exhaustion
 - Rigor level persists across session resume — set once during INIT, never changed mid-session
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                     | Reality                                                                                                                                                                                                                 |
+| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "This phase is low complexity, so I can skip the APPROVE_PLAN gate entirely"                        | Low complexity only means auto-approval when no concern signals fire. If the planner flagged concerns, produced a complexity override, or the task count exceeds 15, the gate pauses regardless of the spec annotation. |
+| "I can write the planning logic inline instead of dispatching to the harness-planner persona agent" | The Iron Law is explicit: autopilot delegates, never reimplements. Using a general-purpose agent or inlining planning logic bypasses the harness methodology.                                                           |
+| "The retry budget is exhausted but I can try one more approach before stopping"                     | The 3-attempt retry budget exists because each failed attempt degrades context and compounds risk. Exceeding the budget without human input turns a recoverable failure into an unrecoverable one.                      |
+| "I will skip the scratchpad since keeping research in conversation is faster"                       | Scratchpad is gated by rigor level. At standard or thorough, bulky research (>500 words) must go to scratchpad to keep agent conversation focused on decisions.                                                         |
+| "The plan auto-approved, so I can skip recording the decision in the decisions array"               | Every plan approval -- auto or manual -- must be recorded with its signal evaluation. The decisions array is the audit trail that explains why a plan was approved.                                                     |
+
 ## Examples
 
 ### Example: 3-Phase Security Scanner

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

@@ -326,6 +326,15 @@ These patterns make requirements testable and unambiguous. Apply them when the o
 - `harness validate` passes after the spec is written
 - If scope was too large, it was decomposed into sub-projects with the human's approval
 
+## Rationalizations to Reject
+
+| Rationalization                                                                    | Reality                                                                                                                                                                                     |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I already understand the problem well enough to skip the question phase"          | The Gates section is explicit: you must ask at least one clarifying question before proposing approaches. Skipping questions means making untested assumptions.                             |
+| "There is only one viable approach, so presenting alternatives would be contrived" | The gate requires at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision -- the human has no real choice.                                      |
+| "I will draft the full spec and present it for review all at once to save time"    | Section-dump specs are explicitly forbidden. Presenting section by section with feedback between each catches misunderstandings early.                                                      |
+| "This future capability is low-cost to include now, so we should build it in"      | YAGNI is a gate, not a suggestion. Every capability must trace to a stated requirement. "We might need this later" is the exact rationalization that turns focused specs into bloated ones. |
+
 ## Examples
 
 ### Example: Designing a Notification System