@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/commands/claude-code/harness/harness.md

@@ -0,0 +1,36 @@
+---
+name: harness
+description: Natural language router to harness skills — classifies intent, confirms, dispatches
+argument-hint: "--intent <intent>"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+<context>
+Cognitive mode: analytical-classifier
+Type: rigid
+</context>
+
+<objective>
+Natural language router to harness skills — classifies intent, confirms, dispatches
+
+Phases:
+- classify: Parse intent and search skills index for matches
+- confirm: Present routing decision with scope and reasoning
+- dispatch: Invoke selected skill via run_skill with original intent
+</objective>
+
+<execution_context>
+@agents/skills/claude-code/harness-router/SKILL.md
+@agents/skills/claude-code/harness-router/skill.yaml
+</execution_context>
+
+<process>
+1. Try: invoke mcp__harness__run_skill with skill: "harness-router"
+2. If MCP unavailable: read SKILL.md and follow its workflow directly
+3. Pass through any arguments provided by the user
+</process>

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

@@ -31,11 +31,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?
@@ -55,7 +55,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.
 
@@ -65,7 +65,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.
 
@@ -86,7 +86,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
@@ -104,7 +104,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
@@ -112,6 +112,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 | Reality |
+| --- | --- |
+| "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
@@ -124,7 +133,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).
 
@@ -133,13 +142,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"
 ```
 
@@ -159,7 +168,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"
 ```
 
@@ -172,7 +181,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.
@@ -189,7 +198,7 @@ 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/commands/codex/harness/cleanup-dead-code/SKILL.md

@@ -239,6 +239,15 @@ ORPHANED DEPENDENCY: moment (package.json)
 
 **Action:** Remove `moment` from package.json dependencies. Run `npm install` to update lockfile. Run tests — all pass. Commit: "remove unused moment dependency"
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "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. |
+
 ## Escalation
 
 - **When removing code causes unexpected test failures:** The code has a hidden dependency. Undo the deletion, investigate the dependency chain, and document the finding. The code is not dead — it is just hard to trace.

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

@@ -173,6 +173,15 @@ GAP: Undocumented module
   Suggested fix: Add AGENTS.md section describing purpose, constraints, and public API
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "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. |
+
 ## Escalation
 
 - **When drift is extensive (>30 findings):** Do not try to fix everything. Focus on Critical and High priority items. Create a tracking issue for the remaining items and schedule them across sprints.

package/dist/agents/commands/codex/harness/enforce-architecture/SKILL.md

@@ -274,21 +274,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/commands/codex/harness/harness-architecture-advisor/SKILL.md

@@ -311,21 +311,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/commands/codex/harness/harness-autopilot/SKILL.md

@@ -901,6 +901,16 @@ Recorded in .harness/failures.md.
 How should we proceed? (fix manually and continue / revise plan / stop)
 ```
 
+## 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. |
+
 ## Gates
 
 - **No reimplementing delegated skills.** Autopilot orchestrates. If you are writing planning logic, execution logic, verification logic, or review logic, STOP. Delegate to the appropriate persona agent via `subagent_type`.

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

@@ -389,6 +389,15 @@ harness validate — passes
 Human: "Approved."
 ```
 
+## 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. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-code-review/SKILL.md

@@ -833,21 +833,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 tests pass, so the logic must be correct"** — Tests can be incomplete. Review the logic independently of test results.
-- **"This is how it was done elsewhere in the codebase"** — Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent.
-- **"It's just a refactor, low risk"** — Refactors change behavior surfaces. Review them with the same rigor as feature changes.
+| Rationalization | Reality |
+| --- | --- |
+| "The tests pass, so the logic must be correct" | Tests can be incomplete. Review the logic independently of test results. |
+| "This is how it was done elsewhere in the codebase" | Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent. |
+| "It's just a refactor, low risk" | Refactors change behavior surfaces. Review them with the same rigor as feature changes. |
 
 ## Escalation
 

package/dist/agents/commands/codex/harness/harness-codebase-cleanup/SKILL.md

@@ -218,6 +218,15 @@ After removing the `legacy-auth` module:
 - Report includes actionable guidance for every remaining finding
 - `harness validate` passes after cleanup
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "This dead export is in a high-churn file but the removal is clearly safe" | High-churn files have more hidden consumers. Safe findings in the top 10% by churn are downgraded to probably-safe, requiring explicit approval. |
+| "The convergence loop is not reducing findings quickly enough, so I will apply unsafe fixes to make progress" | Unsafe findings are never auto-fixed, regardless of convergence pressure. Each requires human judgment. |
+| "The verification gate failed on a probably-safe fix, but I am confident the fix is correct" | When verification fails after a fix batch, the entire batch must be reverted and all findings reclassified as unsafe. |
+| "I will skip the hotspot context phase since it adds time and the churn data is just supplementary" | The hotspot map drives safety classification accuracy. Without it, safe fixes in high-churn areas are not downgraded. |
+
 ## Escalation
 
 - **When convergence loop does not converge after 5 iterations:** The codebase has deeply tangled issues. Stop and report all remaining findings. Consider breaking the cleanup into focused sessions.

package/dist/agents/commands/codex/harness/harness-debugging/SKILL.md

@@ -350,6 +350,15 @@ if (req.validationErrors?.length) {
 
 Revert test: Commenting out the validation check causes the test to fail with 500. Confirmed.
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "I have a strong hunch about what is wrong, so I will jump straight to fixing it" | Phase 1 INVESTIGATE must be completed before ANY fix code is written. You are guessing, not debugging. |
+| "I changed two things and the bug is gone, so the fix must be correct" | One variable at a time is a gate. Changing multiple things simultaneously means you do not know which change fixed it. |
+| "This is my third attempt but I feel close, so one more try before escalating" | After 3 failed fix attempts, the gate requires you to question the architecture. The problem is likely not where you think it is. |
+| "A try-catch that swallows the error prevents the crash, so the bug is fixed" | Symptom suppression is explicitly listed as a bad fix. Wrapping the failure in a try-catch addresses what the bug did, not why it happened. |
+
 ## Gates
 
 - **Phase 1 before ANY fix.** You must complete investigation before writing fix code. Skipping investigation leads to symptom-chasing, which leads to more bugs.

package/dist/agents/commands/codex/harness/harness-dependency-health/SKILL.md

@@ -170,6 +170,14 @@ Output:
   3 actionable recommendations generated
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "There are a few orphan files but they are probably test fixtures or configs, so I will skip investigating them" | Orphan detection explicitly excludes entry points. Files with zero inbound imports that are not entry points must be investigated. |
+| "The cycle is between two closely related files, so it is not really a problem" | Cycles create fragile coupling where any change in the cycle affects all members. Even "related" files should not have circular dependencies. |
+| "The health score is a B, which is good enough -- no need to act on the recommendations" | A hub with 14 importers is a single point of failure. "Good enough" scores mask specific structural risks that compound over time. |
+
 ## Gates
 
 - **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, DFS cycle detection, hub/orphan identification). Do not stop — produce the best analysis possible.

package/dist/agents/commands/codex/harness/harness-docs-pipeline/SKILL.md

@@ -445,6 +445,15 @@ Input: --bootstrap flag set, no graph, no AGENTS.md
 4. REPORT   — Verdict: WARN (>30% modules undocumented, no graph)
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The drift finding is marked unsafe but the fix is obvious, so I will apply it silently" | Never apply a fix classified as unsafe without explicit user approval. The Iron Law: safe fixes are silent, unsafe fixes surface. |
+| "The convergence loop reduced findings from 8 to 6, but the remaining ones are hard -- I will keep iterating" | If a convergence iteration does not reduce the finding count, stop immediately. Continuing without progress wastes iterations. |
+| "I can write the drift detection logic directly instead of delegating to detect-doc-drift" | The pipeline delegates, never reimplements. Each sub-skill retains full standalone functionality. |
+| "The graph is not available so the pipeline results will be unreliable" | The entire pipeline runs without a graph using static analysis fallbacks. Reduced accuracy is noted in the report, not used as an excuse to skip. |
+
 ## Gates
 
 - **No fix without verification.** Every fix batch must be followed by `harness check-docs`. If check fails, revert the batch.

package/dist/agents/commands/codex/harness/harness-execution/SKILL.md

@@ -474,6 +474,15 @@ Read learnings: .harness/learnings.md — "Date comparison needed UTC normalizat
 Run: harness validate — passes. Resume from Task 4.
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The plan says to do X, but doing Y would be cleaner -- I will improvise" | The Iron Law states: execute the plan as written. If the plan is wrong, stop and fix the plan. Improvising mid-execution introduces untested assumptions. |
+| "This task depends on Task 3 which I know is done, so I can skip verifying prerequisites" | Prerequisites must be verified mechanically, not from memory. Check that dependency tasks are marked complete in state and that referenced files exist. |
+| "The checkpoint is just a confirmation step and the output looks correct, so I will auto-continue" | Checkpoints are non-negotiable pause points. If a task has a checkpoint marker, execution must pause. |
+| "Harness validate passed on the previous task and nothing changed structurally, so I can skip it for this one" | Validation runs after every task with no exceptions. Each task may introduce subtle architectural drift that only harness validate catches. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-hotspot-detector/SKILL.md

@@ -152,6 +152,14 @@ Output:
   Top recommendation: Extract shared billing types
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "High churn just means the file is actively developed, not that it is risky" | High churn in shared utilities specifically equals high risk. A file with 45 commits that co-changes with 12 different files indicates hidden coupling. |
+| "The co-change pair is between two files in different modules, but they probably just happen to change at the same time" | Distant co-change pairs are flagged as suspicious precisely because they indicate hidden coupling. |
+| "No graph exists so the analysis will be too incomplete to be useful" | Git log provides ~90% of the data needed for hotspot detection. The fallback is the highest-completeness fallback across all graph-enhanced skills. |
+
 ## Gates
 
 - **Graph preferred, fallback available.** If no graph exists, use git log for churn and co-change analysis. Do not stop — git log provides ~90% of the data needed.

package/dist/agents/commands/codex/harness/harness-impact-analysis/SKILL.md

@@ -175,6 +175,14 @@ Output:
   Downstream consumers: 8 files across 3 modules
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The change is small so the blast radius must be low -- I can skip the transitive dependent check" | Small changes to shared utilities can have outsized blast radius. A one-line change to auth.ts can affect 23 transitive dependents. |
+| "The graph is a few commits behind but it is close enough for this analysis" | If the graph is more than 2 commits behind, the skill requires a refresh before proceeding. Recent commits may have added new consumers. |
+| "No graph exists so I cannot produce a useful impact analysis" | The fallback strategy using import parsing and naming conventions achieves ~70% completeness. Missing the graph does not mean stopping. |
+
 ## Gates
 
 - **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, naming conventions, path matching). Do not stop — produce the best analysis possible with available tools.

package/dist/agents/commands/codex/harness/harness-integrity/SKILL.md

@@ -155,6 +155,14 @@ Integrity Check: FAIL
 Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "All three mechanical checks failed, but I should still run the AI review to get useful feedback" | When ALL three checks fail, stop immediately. Do not proceed to Phase 2. AI review on code that does not compile is wasted effort. |
+| "The security scanner found a warning but it is not high severity, so it should not affect the overall result" | Error-severity security findings are blocking. The distinction is severity, not the agent's opinion of importance. |
+| "The AI review flagged an architectural concern as blocking, so the integrity check should fail" | Only runtime errors, data loss, and security vulnerabilities count as blocking review findings. Architectural concerns are noted but do not block. |
+
 ## Gates
 
 - **Mechanical first.** Always run Phase 1 before Phase 2. If the code does not compile or pass basic checks, AI review is wasted effort (unless partial results exist).

package/dist/agents/commands/codex/harness/harness-onboarding/SKILL.md

@@ -25,7 +25,7 @@
    - Constraints and forbidden patterns
    - Any special instructions or warnings
 
-2. **Read `harness.yaml`.** Extract:
+2. **Read `harness.config.json`.** Extract:
    - Project name and stack
    - Adoption level (basic, intermediate, advanced)
    - Layer definitions and their directory mappings
@@ -50,7 +50,7 @@
 2. **Map the architecture.** Walk the directory structure and identify:
    - Top-level organization pattern (monorepo, single package, workspace)
    - Source code location and entry points
-   - Layer boundaries (from `harness.yaml` and actual directory structure)
+   - Layer boundaries (from `harness.config.json` and actual directory structure)
    - Shared utilities or common modules
    - Configuration files and their purposes
 
@@ -63,7 +63,7 @@
    - Code formatting (detect from config files: `.prettierrc`, `.eslintrc`, `biome.json`)
 
 4. **Map the constraints.** Identify what is restricted:
-   - Forbidden imports (from `harness.yaml` dependency constraints)
+   - Forbidden imports (from `harness.config.json` dependency constraints)
    - Layer boundary rules (which layers can import from which)
    - Linting rules that encode architectural decisions
    - Any constraints documented in `AGENTS.md` that are not yet automated
@@ -97,8 +97,8 @@ Graph queries produce a complete architecture map in seconds, including transiti
 
 ### Phase 3: ORIENT — Identify Adoption Level and Maturity
 
-1. **Confirm the adoption level** matches what `harness.yaml` declares:
-   - Basic: `AGENTS.md` and `harness.yaml` exist but no layers or constraints
+1. **Confirm the adoption level** matches what `harness.config.json` declares:
+   - Basic: `AGENTS.md` and `harness.config.json` exist but no layers or constraints
    - Intermediate: Layers defined, dependency constraints enforced, at least one custom skill
    - Advanced: Personas, state management, learnings, CI integration
 
@@ -186,16 +186,16 @@ Graph queries produce a complete architecture map in seconds, including transiti
 - **`harness check-deps`** — Run to verify dependency constraints are passing, which confirms layer boundaries are respected.
 - **`harness state show`** — View current state to understand where the last session left off.
 - **`AGENTS.md`** — Primary source of project context and agent instructions.
-- **`harness.yaml`** — Source of structural configuration (layers, constraints, skills).
+- **`harness.config.json`** — Source of structural configuration (layers, constraints, skills).
 - **`.harness/learnings.md`** — Historical context and institutional knowledge.
 
 ## Success Criteria
 
-- All four configuration sources were read (`AGENTS.md`, `harness.yaml`, `.harness/learnings.md`, `.harness/state.json`)
+- All four configuration sources were read (`AGENTS.md`, `harness.config.json`, `.harness/learnings.md`, `.harness/state.json`)
 - Technology stack is accurately identified (language, framework, test runner, build tool)
 - Architecture is mapped with correct layer boundaries and dependency directions
 - Conventions are identified from actual code patterns, not assumed
-- Constraints are enumerated from both `harness.yaml` and `AGENTS.md`
+- Constraints are enumerated from both `harness.config.json` and `AGENTS.md`
 - Adoption level is confirmed (not just declared — validated)
 - A structured orientation summary is produced with all sections filled
 - The "Getting Started" section is actionable and tailored to the audience
@@ -213,7 +213,7 @@ Read AGENTS.md:
   - Stack: TypeScript, Express, Vitest, PostgreSQL
   - Conventions: zod validation, repository pattern, kebab-case files
 
-Read harness.yaml:
+Read harness.config.json:
   - Level: intermediate
   - Layers: presentation (src/routes/), business (src/services/), data (src/repositories/)
   - Constraints: presentation → business OK, business → data OK, data → presentation FORBIDDEN
@@ -260,7 +260,7 @@ Produce orientation with all sections. Getting Started for this context:
 
 ```
 Read AGENTS.md — exists, minimal content
-Read harness.yaml — level: basic, no layers defined
+Read harness.config.json — level: basic, no layers defined
 No .harness/learnings.md
 No .harness/state.json
 ```
@@ -276,6 +276,14 @@ Getting Started:
    (use initialize-harness-project to upgrade)
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "I can skip reading .harness/learnings.md since it is just historical notes" | Learnings contain hard-won insights from previous sessions -- decisions made, gotchas discovered, patterns that worked or failed. Skipping them means repeating mistakes already diagnosed. |
+| "The harness.config.json says intermediate, so I can report that without validation" | Declared adoption level must be confirmed, not assumed. A project that declares intermediate but fails harness validate is not truly intermediate. |
+| "I will map the architecture by reading the directory names since that is faster than checking conventions in actual code" | Conventions must be identified from actual code patterns, not assumed from directory structure. File naming, import style, and error handling can only be verified by reading real source files. |
+
 ## Adoption Maturity
 
 A mental model for where a team sits on the harness adoption curve. Not prescriptive — just orientation.

package/dist/agents/commands/codex/harness/harness-perf/SKILL.md

@@ -247,6 +247,15 @@ Phase 4: ENFORCE
   Result: PASS — no blocking violations.
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The cyclomatic complexity is 16 but the function is straightforward, so I can override the Tier 1 threshold" | Tier 1 violations are non-negotiable blockers. No merge with Tier 1 performance violations. If a threshold needs adjustment, reconfigure with documented justification. |
+| "The benchmark regression is only 6% and it is probably just noise" | The noise margin (default 3%) is applied before flagging. A 6% regression on a perf-critical path exceeds the Tier 1 threshold even after noise consideration. |
+| "The working tree has a small uncommitted change but it should not affect benchmark results" | No running benchmarks with a dirty working tree. Uncommitted changes invalidate benchmark results. |
+| "I will update the baselines to match the new performance numbers rather than fixing the regression" | Baselines must come from fresh runs against committed code. Silently moving the goalposts defeats the purpose of performance gates. |
+
 ## Gates
 
 - **No ignoring Tier 1 violations.** They must be fixed or the threshold must be reconfigured (with documented justification).

package/dist/agents/commands/codex/harness/harness-planning/SKILL.md

@@ -561,6 +561,16 @@ Files: src/services/notification-service.ts, src/services/notification-service.t
 
 _Presented for approval. User approved. Expanded to full tasks._
 
+## 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. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-refactoring/SKILL.md

@@ -136,6 +136,15 @@ 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)
 
+## 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. |
+
 ## Examples
 
 ### Example: Moving business logic out of a UI component

package/dist/agents/commands/codex/harness/harness-release-readiness/SKILL.md

@@ -672,6 +672,15 @@ Current:  27/28 passed (PASS — 1 warning remaining)
 The project is release-ready. The remaining warning (README usage section) is not blocking.
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The MAINTAIN phase takes too long, so I will skip dispatching the 4 maintenance agents" | No skipping the MAINTAIN phase. Maintenance checks catch issues that release-specific checks miss. |
+| "This auto-fix is obviously correct, so I can apply it without prompting the user" | No auto-fix without prompting. Every fix must be presented to the human before being applied. |
+| "Most checks pass and only a few warnings remain, so the release is ready" | A "mostly passing" report is not a passing report. The result is PASS only when zero failures exist across all categories. |
+| "The previous run found these issues and I fixed them, so I can trust the cached results" | Session resumption requires re-running all checks. Code may have changed since the last run. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-roadmap/SKILL.md

@@ -44,7 +44,7 @@ If the human has not seen and approved the milestone groupings and feature list,
    - Has spec + plan but no implementation -> `planned`
    - Has spec but no plan -> `backlog`
    - Has plan but no spec -> `planned` (unusual, flag for human review)
-6. Detect project name from `harness.yaml` `project` field, or `package.json` `name` field, or directory name as fallback.
+6. Detect project name from `harness.config.json` `project` field, or `package.json` `name` field, or directory name as fallback.
 
 Present scan summary:
 
@@ -579,6 +579,15 @@ Total features: 4
 harness validate: passed
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The feature list looks correct, so I can skip the PROPOSE phase and write the roadmap directly" | The Iron Law: never write docs/roadmap.md without the human confirming the proposed structure first. |
+| "This sync detected a status change and the inference is clearly correct, so I can apply it without confirmation" | The sync PROPOSE phase requires presenting proposed changes and waiting for human confirmation. The human-always-wins rule applies. |
+| "The existing roadmap is outdated, so I will recreate it with --create to get a fresh start" | No overwriting an existing roadmap without explicit user consent. Silent overwrites destroy prior manual edits and status tracking. |
+| "There is no roadmap yet but the user asked me to add a feature, so I will create one as a side effect of --add" | When the roadmap does not exist, --add must error with a clear message directing the user to --create. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.