@harness-engineering/cli 1.23.1 → 1.23.2

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

@@ -121,11 +121,29 @@ depends_on:
 
 8. **For rigid skills, write `## Escalation`.** Define when to stop and ask for help. Each escalation condition should describe the symptom, the likely cause, and what to report.
 
+9. **Write `## Rationalizations to Reject`.** Every user-facing skill must include this section. It contains domain-specific rationalizations that prevent agents from skipping steps with plausible-sounding excuses. Format requirements:
+   - **Table format:** `| Rationalization | Reality |` with a header separator row
+   - **3-8 entries** per skill, each specific to the skill's domain
+   - **No generic filler.** Every entry must address a rationalization that is plausible in the context of this specific skill
+   - **Do not repeat universal rationalizations.** The following three are always in effect for all skills and must NOT appear in individual skill tables:
+
+   | Rationalization         | Reality                                                                     |
+   | ----------------------- | --------------------------------------------------------------------------- |
+   | "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 here. |
+   | "We can fix it later"   | If worth flagging, document now with a concrete follow-up plan.             |
+
+   Example of a good domain-specific entry (for a code review skill):
+
+   | Rationalization                               | Reality                                                                                                                                    |
+   | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+   | "The tests pass so the logic must be correct" | Passing tests prove the tested paths work. They say nothing about untested paths, edge cases, or whether the tests themselves are correct. |
+
 ### Phase 5: VALIDATE — Verify the Skill
 
 1. **Run `harness skill validate`** to check:
    - `skill.yaml` has all required fields and valid values
-   - `SKILL.md` has all required sections (`## When to Use`, `## Process`, `## Harness Integration`, `## Success Criteria`, `## Examples`)
+   - `SKILL.md` has all required sections (`## When to Use`, `## Process`, `## Harness Integration`, `## Success Criteria`, `## Examples`, `## Rationalizations to Reject`)
    - Rigid skills have `## Gates` and `## Escalation` sections
    - The `name` in `skill.yaml` matches the directory name
    - Referenced tools exist
@@ -174,6 +192,16 @@ Use this checklist as a final quality gate before declaring a skill complete.
 - Rigid skills include Gates and Escalation sections with specific conditions and consequences
 - The skill can be loaded and run with `harness skill run <name>`
 
+## Rationalizations to Reject
+
+| Rationalization                                                         | Reality                                                                                                                                  |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| "This skill is too simple to need all required sections"                | Every section exists for a reason. A short section is fine; a missing section means the skill was not fully thought through.             |
+| "The process section covers it — no need for explicit success criteria" | Process describes what to do. Success criteria describe how to know it worked. They serve different purposes.                            |
+| "Rationalizations to Reject is meta — this skill does not need it"      | This section is required for all user-facing skills, including this one. No exceptions.                                                  |
+| "I will add examples later once the skill is proven"                    | Examples are a required section. A skill without examples forces the agent to guess at correct behavior. Write at least one example now. |
+| "The When to Use section is obvious from the name"                      | Negative conditions (when NOT to use) prevent misapplication. The skill name conveys nothing about boundary conditions.                  |
+
 ## Examples
 
 ### Example: Creating a Flexible Skill for Database Migration Review

package/dist/agents/skills/gemini-cli/harness-soundness-review/SKILL.md

@@ -1147,6 +1147,16 @@ These criteria validate the skill implementation artifacts. The behavioral succe
 7. `harness validate` passes after all files are written
 8. The skill test suite passes (structure, schema, platform-parity, references)
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                          | Reality                                                                                                                                                                        |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The spec looks coherent to me, so I can skip running the S1 internal coherence check"                   | Every check in the mode must run. S1 detects contradictions between decisions, technical design, and success criteria that human review frequently misses.                     |
+| "This unstated assumption is obvious, so documenting it would be pedantic"                               | S3 exists because "obvious" assumptions cause the most damage when they turn out to be wrong. Obvious assumptions are the cheapest to document and the most expensive to miss. |
+| "The success criterion is somewhat vague but the team will know what it means"                           | S7 flags vague criteria like "should be fast" because they are untestable. Vague criteria survive brainstorming and planning only to fail at verification.                     |
+| "This auto-fixable finding is minor, so I will just note it rather than applying the fix"                | Auto-fixable findings should be applied silently -- that is the design intent. Skipping them means the spec ships with known inferrable gaps.                                  |
+| "The feasibility check found a signature mismatch but the code can probably be adapted during execution" | S5 feasibility red flags are always severity "error" and always surface to the user. A spec that references nonexistent modules will produce a broken plan.                    |
+
 ## Examples
 
 ### Example: Spec Mode Invocation

package/dist/agents/skills/gemini-cli/harness-sql-review/SKILL.md

@@ -300,6 +300,16 @@ Phase 4: VALIDATE
   Report: NEEDS_ATTENTION (1 N+1 error, 1 missing index, 1 query rewrite)
 ```
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                   | Reality                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| "The ORM handles query optimization automatically"                                                | ORMs generate syntactically correct queries but do not detect N+1 patterns, choose optimal join strategies, or add missing indexes. The ORM executes what the code asks for. A `findMany` followed by per-item `findUnique` calls in a loop is an N+1 regardless of which ORM executes it. |
+| "That endpoint is only called by admins so performance doesn't matter"                            | Admin endpoints frequently become user-facing as products grow. An N+1 query on a 10-row table becomes a crisis when the table grows to 100,000 rows. Query correctness should not be conditional on current data volume.                                                                  |
+| "We can add indexes later if performance becomes a problem"                                       | Adding indexes to large production tables requires exclusive locks or online rebuild procedures that carry risk. Identifying and adding the correct index during development, before the table grows, costs minutes instead of hours of planned maintenance.                               |
+| "That DELETE without a WHERE clause is wrapped in application logic that only calls it correctly" | Application logic has bugs. A missing WHERE clause is a single misrouted request away from deleting the entire table. Database safety constraints must not depend on application-layer correctness.                                                                                        |
+| "The query is fast in development — the test database only has 100 rows"                          | Development databases do not represent production query plans. Full table scans, missing indexes, and N+1 patterns only manifest at production data volumes. Static analysis catches these issues regardless of local data size.                                                           |
+
 ## Gates
 
 - **No approving N+1 queries in user-facing hot paths.** An N+1 query in an endpoint called per page load is always an error. It must be fixed with eager loading, batching, or a JOIN before the PR can merge.

package/dist/agents/skills/gemini-cli/harness-state-management/SKILL.md

@@ -218,6 +218,16 @@ Treat learnings as a first-class project artifact. They are as valuable as tests
 - State is saved before session end with an accurate session summary
 - State files are committed to git separately from code changes
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                                       | Reality                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The session is short — I'll update state at the end rather than after each task."                                    | Context resets happen without warning. A session that ends mid-task with no state update forces the next session to reconstruct position by reading git history and code, which takes longer and produces an inaccurate picture. State is updated after each task, not at the end of the session.         |
+| "This decision is obvious from the code — I don't need to record the rationale in state."                             | What is obvious to the agent that made the decision is opaque to the agent that resumes three weeks later with no memory of the session. Decisions are recorded because the context that made them obvious does not survive a context reset. The rationale is exactly what needs to be saved.             |
+| "The learnings file is getting long — I'll trim old entries that are no longer relevant."                             | Learnings are append-only by design. An entry that seems irrelevant may become relevant when a related pattern resurfaces. Trimming destroys the chronological record and the ability to understand why earlier decisions were made. Entries are never deleted, only supplemented with corrections.       |
+| "I can re-read the plan to figure out where I am — I don't need to update the position in state."                     | The plan describes what to do; state records what has been done. Re-reading the plan without state requires the next session to infer progress from code, which produces uncertain position. Uncertain position leads to re-executing completed tasks or skipping tasks that appear complete but are not. |
+| "The stream auto-resolves from the branch — I don't need to explicitly verify which stream is active before writing." | Auto-resolution works when branch names match stream names and the index is current. When branches are renamed, stale, or when multiple streams exist for the same feature, auto-resolution can write to the wrong stream silently. Always announce the resolved stream before writing state.             |
+
 ## Examples
 
 ### Example: Starting a New Session (Resuming Work)

package/dist/agents/skills/gemini-cli/harness-supply-chain-audit/SKILL.md

@@ -222,6 +222,16 @@ Do not assert risk scores without citing the specific data point that generated
 - **If the npm or GitHub API is unavailable:** Note which factors were skipped with "unknown" scores. Do not fail the audit — partial results are better than none.
 - **If the user asks for a verdict ("is this safe?"):** Decline to give a binary answer. Supply chain risk is probabilistic. Present the risk signals and let the human decide.
 
+## 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 package has high risk signals but it is widely used, so it must be safe"              | The Iron Law: present findings as flags for human review, never as verdicts. Popularity does not eliminate bus-factor risk or maintenance abandonment. |
+| "The npm API returned an error for this package, so I will skip it and move on"             | API failures produce "unknown" scores with a note, not skips. Partial results with noted gaps are always better than incomplete audits.                |
+| "The install script is probably just native addon compilation, so I do not need to flag it" | Every install script must be flagged in the report. "Probably legitimate" is exactly the assumption that supply chain attacks exploit.                 |
+
 ## Examples
 
 ```

package/dist/agents/skills/gemini-cli/harness-tdd/SKILL.md

@@ -114,6 +114,15 @@ Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycle
 - No test tests implementation details (only observable behavior)
 - No production code exists that was not demanded by a failing test
 
+## Rationalizations to Reject
+
+| Rationalization                                                                                     | Reality                                                                                                                                                                                             |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "I know exactly what the implementation should be, so I will write it first and add the test after" | Code before test equals delete it. The gate is explicit: if production code is written before a failing test exists, delete the production code and start correctly.                                |
+| "The test passed on the first run, so TDD is working"                                               | If the test passed without implementing the production code, either the behavior already exists or the test is wrong. You must watch the test FAIL for the right reason before proceeding to GREEN. |
+| "I will test multiple behaviors in this one test to be efficient"                                   | One test, one assertion, one behavior. Multi-behavior tests make it impossible to pinpoint which behavior broke when the test fails.                                                                |
+| "Harness validate can wait until the end of the feature since it slows down the cycle"              | No skipping VALIDATE. Every cycle must end with harness check-deps and harness validate. A passing test with a failing validation means the implementation violated a project constraint.           |
+
 ## Examples
 
 ### Example: Adding a `calculateTotal` function

package/dist/agents/skills/gemini-cli/harness-test-advisor/SKILL.md

@@ -126,6 +126,16 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 - Report follows the structured output format
 - All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
+## 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                                                                                                                                                                     |
+| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Only the Tier 1 direct tests matter -- Tier 2 and Tier 3 are probably unnecessary"                | Tier 2 tests catch indirect breakage one hop away. A change to auth.ts breaks login.ts which breaks login.test.ts. Skipping Tier 2 misses exactly the regressions hardest to debug. |
+| "The changed file has no tests, but that is not my concern -- I just advise on which tests to run" | Coverage gaps must be flagged. When a changed file has no test coverage, the advisor reports it. Silently producing an empty test list gives false confidence.                      |
+| "The graph is stale but I will use it anyway since some data is better than no data"               | If the graph is more than 10 commits behind, refresh before proceeding. Staleness sensitivity is Medium for test advisor.                                                           |
+
 ## Examples
 
 ### Example: Selecting Tests for a Services Change

package/dist/agents/skills/gemini-cli/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/gemini-cli/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/gemini-cli/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/gemini-cli/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/gemini-cli/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/gemini-cli/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/gemini-cli/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-md-HCCCO5PK.js

@@ -0,0 +1,9 @@
+import {
+  generateAgentsMd
+} from "./chunk-E2GTL3YS.js";
+import "./chunk-V27WDRYV.js";
+import "./chunk-5LMZA5LZ.js";
+import "./chunk-CLD4KL7O.js";
+export {
+  generateAgentsMd
+};

package/dist/{architecture-FVERI7BQ.js → architecture-S2H624W7.js}

@@ -1,13 +1,13 @@
 import {
   checkDependenciesDefinition,
   handleCheckDependencies
-} from "./chunk-RQ3AKUJB.js";
-import "./chunk-H7Y5CKTM.js";
+} from "./chunk-2DHX6TAP.js";
+import "./chunk-Q3XYV5UC.js";
 import "./chunk-IDZNPTYD.js";
 import "./chunk-W6Y7ZW3Y.js";
-import "./chunk-QBATHQXU.js";
-import "./chunk-ERS5EVUZ.js";
-import "./chunk-EUCASOD7.js";
+import "./chunk-V27WDRYV.js";
+import "./chunk-5LMZA5LZ.js";
+import "./chunk-CLD4KL7O.js";
 export {
   checkDependenciesDefinition,
   handleCheckDependencies

package/dist/{assess-project-UGL5KLBV.js → assess-project-XSGK44S5.js}

@@ -1,7 +1,7 @@
 import {
   assessProjectDefinition,
   handleAssessProject
-} from "./chunk-CZEPCYVX.js";
+} from "./chunk-ZRYDYDB2.js";
 import "./chunk-W6Y7ZW3Y.js";
 export {
   assessProjectDefinition,

package/dist/bin/harness-mcp.js

@@ -1,28 +1,28 @@
 #!/usr/bin/env node
 import {
   startServer
-} from "../chunk-L57RL7MC.js";
-import "../chunk-ZLTFDTK7.js";
-import "../chunk-FNVAW5NG.js";
-import "../chunk-LAKMOIU6.js";
-import "../chunk-KIR5PQX5.js";
-import "../chunk-7DMF3VT5.js";
-import "../chunk-CZEPCYVX.js";
-import "../chunk-CJDVBBPB.js";
-import "../chunk-7XZSHTYZ.js";
-import "../chunk-7V5Y2L67.js";
-import "../chunk-RQ3AKUJB.js";
-import "../chunk-H7Y5CKTM.js";
-import "../chunk-HRUCT5YX.js";
-import "../chunk-AQN7GFKU.js";
+} from "../chunk-BK52Z6DR.js";
+import "../chunk-KC5CTCEL.js";
+import "../chunk-S5ZXT3TZ.js";
+import "../chunk-ZYJJUPNE.js";
+import "../chunk-ZRYDYDB2.js";
+import "../chunk-2GT3HO2T.js";
+import "../chunk-2DHX6TAP.js";
+import "../chunk-Q3XYV5UC.js";
+import "../chunk-MZAHE4DK.js";
+import "../chunk-2YA4XRI3.js";
+import "../chunk-MHOO7NLG.js";
 import "../chunk-IDZNPTYD.js";
 import "../chunk-W6Y7ZW3Y.js";
+import "../chunk-PGF44T2D.js";
+import "../chunk-3ISINLYT.js";
 import "../chunk-N5G5QMS3.js";
-import "../chunk-3WGJMBKH.js";
+import "../chunk-I47JLISV.js";
+import "../chunk-V27WDRYV.js";
+import "../chunk-5LMZA5LZ.js";
+import "../chunk-CLD4KL7O.js";
 import "../chunk-SE4YPMLH.js";
-import "../chunk-QBATHQXU.js";
-import "../chunk-ERS5EVUZ.js";
-import "../chunk-EUCASOD7.js";
+import "../chunk-3WGJMBKH.js";
 
 // src/bin/harness-mcp.ts
 import "dotenv/config";