@harness-engineering/cli 1.1.1 → 1.2.0

package/dist/agents/skills/gemini-cli/enforce-architecture/SKILL.md

@@ -1,165 +0,0 @@
-# Enforce Architecture
-
-> Validate architectural layer boundaries and detect dependency violations. No code may violate layer constraints — this is a hard gate, not a suggestion.
-
-## When to Use
-
-- Before approving any pull request or merge
-- After writing new imports or module references
-- When adding a new module or package to the project
-- When `on_pre_commit` or `on_architecture_check` triggers fire
-- After refactoring that moves code between layers or modules
-- NOT when editing documentation, configuration, or non-code files
-- NOT when the violation is intentional and requires a constraint update (escalate instead)
-
-## Process
-
-### Phase 1: Load Constraints
-
-1. **Read `harness.config.json`** to understand the project's architectural constraints. The config defines:
-   - **Layers** — ordered list of architectural layers (e.g., `ui -> service -> repository -> domain`)
-   - **Dependency rules** — which layers may import from which (typically: layers may only import from layers below them)
-   - **Forbidden imports** — specific import paths that are never allowed in certain contexts
-   - **Boundary definitions** — which directories/packages belong to which layer
-
-2. **Understand the layer model.** In a typical layered architecture:
-   - Higher layers depend on lower layers (UI depends on Service, Service depends on Repository)
-   - Lower layers NEVER depend on higher layers (Repository must not import from UI)
-   - Same-layer imports may or may not be allowed depending on project config
-   - Cross-cutting concerns (logging, config) have their own rules
-
-### Phase 2: Run Dependency Checks
-
-1. **Run `harness check-deps`** to analyze all import statements against the constraint model. Capture the full JSON output.
-
-2. **Parse the results.** Each violation includes:
-   - The violating file and line number
-   - The forbidden import target
-   - The source layer and target layer
-   - The specific rule being violated
-
-### Phase 3: Analyze Violations
-
-For each violation, determine:
-
-1. **Which layers are involved.** Identify the source file's layer and the imported module's layer. Map them to the constraint model.
-
-2. **What rule is violated.** Common violation types:
-   - **Upward dependency** — a lower layer imports from a higher layer (e.g., repository importing from UI). This is the most serious type. It creates coupling that makes the lower layer untestable in isolation.
-   - **Skip-layer dependency** — a layer reaches past its immediate neighbor (e.g., UI importing directly from Repository, bypassing Service). This breaks encapsulation and makes the middle layer pointless.
-   - **Circular dependency** — two modules or layers depend on each other. This creates fragile coupling where changing either module risks breaking the other.
-   - **Forbidden import** — a specific import that is explicitly banned (e.g., importing a database driver outside the repository layer). This prevents implementation details from leaking.
-
-3. **Explain the impact.** For each violation, state:
-   - WHY the constraint exists (what architectural property it protects)
-   - WHAT would happen if the violation were allowed to persist
-   - HOW it affects testability, maintainability, and changeability
-
-### Phase 4: Guide Resolution
-
-For each violation, provide a specific fix:
-
-- **Upward dependency:** Introduce an interface or abstraction in the lower layer. The higher layer implements it; the lower layer depends only on the abstraction. Alternatively, use dependency injection.
-- **Skip-layer dependency:** Route the call through the intermediate layer. Add a method to the Service layer that delegates to the Repository, then have the UI call the Service.
-- **Circular dependency:** Break the cycle by extracting shared types into a common module that both can depend on, or restructure so the dependency flows in one direction only.
-- **Forbidden import:** Replace the forbidden import with the approved alternative. If no alternative exists, the feature may need to live in a different layer.
-
-## Common Violation Patterns
-
-### Pattern: "I just need one thing from that layer"
-
-A UI component imports a repository function directly because "it is just one query." Fix: add the query to the Service layer. The extra indirection is the architecture working correctly.
-
-### Pattern: "Shared types across layers"
-
-Two layers both need the same type definition. Fix: place shared types in the lowest layer that both depend on, or create a dedicated `types` or `shared` module at the bottom of the layer stack.
-
-### Pattern: "Test utilities importing production code from wrong layer"
-
-Test helpers import across layer boundaries for convenience. Fix: each layer's tests should only import from that layer and below. Test utilities should follow the same constraints as production code.
-
-### Pattern: "Circular dependency through re-exports"
-
-Module A re-exports from Module B, and Module B imports from Module A. The circular dependency is hidden by the re-export. Fix: identify the true dependency direction and remove the reverse path.
-
-## Harness Integration
-
-- **`harness check-deps`** — Primary tool. Analyzes all imports against the layer model defined in `harness.config.json`. Returns structured violation data including file, line, source layer, target layer, and rule violated.
-- **`harness check-deps --json`** — Machine-readable output for automated pipelines. Use this when parsing results programmatically.
-- **`harness validate`** — Includes dependency checking as part of full project validation. Use when you want a complete health check, not just architecture.
-
-## Success Criteria
-
-- `harness check-deps` reports zero violations
-- All imports flow downward through the layer stack (or follow explicitly configured exceptions)
-- No circular dependencies exist between modules or layers
-- No forbidden imports are present anywhere in the codebase
-- Every new module is assigned to the correct layer in the config
-- The layer model in `harness.config.json` accurately reflects the intended architecture
-
-## Examples
-
-### Example: Service layer importing from UI layer
-
-**Violation from `harness check-deps`:**
-
-```
-VIOLATION: Upward dependency
-  File: src/services/user-service.ts:12
-  Import: import { UserForm } from '../components/UserForm'
-  Source layer: service (level 2)
-  Target layer: ui (level 3)
-  Rule: service layer must not depend on ui layer
-```
-
-**Impact:** The UserService now depends on a React component. It cannot be used in a CLI tool, a background job, or tested without a DOM. The service layer should be framework-agnostic.
-
-**Resolution:**
-
-```typescript
-// BEFORE (violating)
-import { UserForm } from '../components/UserForm';
-const data = UserForm.defaultValues; // using UI defaults in service
-
-// AFTER (fixed)
-// Define the defaults where they belong — in the service layer
-const DEFAULT_USER_DATA: UserInput = { name: '', email: '' };
-```
-
-### Example: Circular dependency between modules
-
-**Violation from `harness check-deps`:**
-
-```
-VIOLATION: Circular dependency detected
-  Cycle: src/services/order-service.ts -> src/services/inventory-service.ts -> src/services/order-service.ts
-  order-service imports checkStock from inventory-service
-  inventory-service imports getOrderQuantity from order-service
-```
-
-**Resolution:** Extract the shared concern into a new module:
-
-```typescript
-// src/services/stock-calculator.ts (new, shared module)
-export function calculateRequiredStock(quantity: number, reserved: number): number {
-  return quantity - reserved;
-}
-```
-
-Both services import from `stock-calculator` instead of from each other. The cycle is broken.
-
-## Gates
-
-These are hard stops. Architecture violations are not warnings — they are errors.
-
-- **No code with layer violations may be approved or merged.** If `harness check-deps` reports violations, the code must be fixed before it proceeds.
-- **No new modules without layer assignment.** Every new directory or package must be mapped to a layer in `harness.config.json` before code is written in it.
-- **No "temporary" violations.** There is no TODO for architecture. Either the code respects the constraints or it does not ship.
-- **No suppressing violations without team approval.** If a violation needs to be allowed, the constraint in `harness.config.json` must be explicitly updated with a comment explaining why.
-
-## Escalation
-
-- **When a violation seems impossible to fix within the current architecture:** The architecture may need to evolve. Escalate to the human with a clear explanation of the constraint, the use case, and why they conflict. Propose options: update the constraint, restructure the code, or add a new layer.
-- **When `harness check-deps` reports false positives:** Verify the layer assignments in `harness.config.json` are correct. If a file is assigned to the wrong layer, fix the config. If the tool is genuinely wrong, report the issue.
-- **When fixing one violation creates another:** This usually indicates a deeper structural issue. Step back and look at the dependency graph as a whole rather than fixing violations one at a time.
-- **When the team wants to change the layer model:** This is a significant architectural decision. All existing code must be migrated to the new model. Plan this as a dedicated refactoring effort, not a side task.

package/dist/agents/skills/gemini-cli/enforce-architecture/skill.yaml

@@ -1,31 +0,0 @@
-name: enforce-architecture
-version: "1.0.0"
-description: Validate architectural layer boundaries and detect circular dependencies
-cognitive_mode: meticulous-verifier
-triggers:
-  - manual
-  - on_pr
-  - on_commit
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Glob
-cli:
-  command: harness skill run enforce-architecture
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: enforce-architecture
-    path: string
-type: rigid
-state:
-  persistent: false
-  files: []
-depends_on: []

package/dist/agents/skills/gemini-cli/harness-architecture-advisor/skill.yaml

@@ -1,48 +0,0 @@
-name: harness-architecture-advisor
-version: "1.0.0"
-description: Interactive architecture advisor that surfaces trade-offs and helps humans choose
-cognitive_mode: advisory-guide
-triggers:
-  - manual
-  - on_new_feature
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Read
-  - Glob
-  - Grep
-  - Bash
-cli:
-  command: harness skill run harness-architecture-advisor
-  args:
-    - name: path
-      description: Project root path
-      required: false
-    - name: topic
-      description: "Architecture topic (e.g., api-design, data-modeling, decomposition)"
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-architecture-advisor
-    path: string
-type: flexible
-phases:
-  - name: discover
-    description: Ask questions about the problem space and constraints
-    required: true
-  - name: analyze
-    description: Research the codebase and identify relevant patterns
-    required: true
-  - name: propose
-    description: Present 2-3 architectural options with trade-offs
-    required: true
-  - name: document
-    description: Write an Architecture Decision Record for the chosen option
-    required: true
-state:
-  persistent: true
-  files:
-    - .harness/architecture/
-depends_on: []

package/dist/agents/skills/gemini-cli/harness-brainstorming/skill.yaml

@@ -1,47 +0,0 @@
-name: harness-brainstorming
-version: "1.0.0"
-description: Structured ideation and exploration with harness methodology
-cognitive_mode: constructive-architect
-triggers:
-  - manual
-  - on_new_feature
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-cli:
-  command: harness skill run harness-brainstorming
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-brainstorming
-    path: string
-type: rigid
-phases:
-  - name: explore
-    description: Generate ideas and possibilities
-    required: true
-  - name: evaluate
-    description: Assess ideas against constraints
-    required: true
-  - name: prioritize
-    description: Select and sequence top ideas
-    required: true
-  - name: validate
-    description: Run harness checks on selected approach
-    required: true
-state:
-  persistent: false
-  files: []
-depends_on:
-  - harness-planning

package/dist/agents/skills/gemini-cli/harness-code-review/skill.yaml

@@ -1,32 +0,0 @@
-name: harness-code-review
-version: "1.0.0"
-description: Structured code review with automated harness checks
-cognitive_mode: adversarial-reviewer
-triggers:
-  - manual
-  - on_pr
-  - on_review
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Glob
-  - Grep
-cli:
-  command: harness skill run harness-code-review
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-code-review
-    path: string
-type: rigid
-state:
-  persistent: false
-  files: []
-depends_on: []

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

@@ -1,356 +0,0 @@
-# Harness Debugging
-
-> 4-phase systematic debugging with entropy analysis and persistent sessions. Phase 1 before ANY fix. "It's probably X" is not a diagnosis.
-
-## When to Use
-
-- When a test fails and the cause is not immediately obvious
-- When a feature works in one context but fails in another
-- When an error message does not clearly indicate the root cause
-- When `on_bug_fix` triggers fire
-- When a previous fix attempt did not resolve the issue
-- NOT for known issues with documented solutions (apply the solution directly)
-- NOT for typos, syntax errors, or other obvious fixes (just fix them)
-- NOT for feature development (use harness-tdd instead)
-
-## Process
-
-### Prerequisite: Start a Debug Session
-
-Before beginning, create a persistent debug session. This survives context resets and tracks state across multiple attempts.
-
-```
-.harness/debug/active/<session-id>.md
-```
-
-Session file format:
-
-```markdown
-# Debug Session: <brief-description>
-
-Status: gathering
-Started: <timestamp>
-Error: <the error message or symptom>
-
-## Investigation Log
-
-(append entries as you go)
-
-## Hypotheses
-
-(track what you have tried)
-
-## Resolution
-
-(filled in when resolved)
-```
-
-**Status transitions:** `gathering` -> `investigating` -> `fixing` -> `verifying` -> `resolved`
-
----
-
-### Phase 1: INVESTIGATE — Understand Before Acting
-
-**You must complete Phase 1 before writing ANY fix code. No exceptions.**
-
-#### Step 1: Run Entropy Analysis
-
-```bash
-harness cleanup
-```
-
-Review the output. Entropy analysis reveals:
-
-- Dead code and unused imports near the failure
-- Pattern violations that may be contributing
-- Documentation drift that may have caused incorrect usage
-- Dependency issues that could affect behavior
-
-Record relevant findings in the session log.
-
-#### Step 2: Read the Error Carefully
-
-Read the COMPLETE error message. Not just the first line — the entire stack trace, every warning, every note. Errors often contain the answer.
-
-Ask yourself:
-
-- What exactly failed? (Not "it broke" — what specific operation?)
-- Where did it fail? (File, line, function)
-- What was the input that caused the failure?
-- What was the expected behavior vs actual behavior?
-
-Record the answers in the session log.
-
-#### Step 3: Reproduce Consistently
-
-Run the failing scenario multiple times. Confirm it fails every time with the same error. If it is intermittent, record:
-
-- How often it fails (1 in 3? 1 in 10?)
-- Whether the failure mode changes
-- Environmental factors (timing, ordering, state)
-
-If you cannot reproduce the failure, you cannot debug it. Escalate.
-
-#### Step 4: Check Recent Changes
-
-```bash
-git log --oneline -20
-git diff HEAD~5
-```
-
-What changed recently? Many bugs are caused by the most recent change. Compare the failing state to the last known working state.
-
-#### Step 5: Trace Data Flow Backward
-
-Start at the error location and trace backward:
-
-1. What function threw the error?
-2. What called that function? With what arguments?
-3. Where did those arguments come from?
-4. Continue until you find where the actual value diverges from the expected value.
-
-Read each function in the call chain completely. Do not skim.
-
-Update the session status to `investigating`.
-
----
-
-### Phase 2: ANALYZE — Find the Pattern
-
-#### Step 1: Find Working Examples
-
-Search the codebase for similar functionality that WORKS. There is almost always a working example of what you are trying to do.
-
-```
-Look for:
-- Other calls to the same function/API that succeed
-- Similar features that work correctly
-- Test fixtures that exercise the same code path
-- Documentation or comments that describe expected behavior
-```
-
-#### Step 2: Read Reference Implementations Completely
-
-When you find a working example, read it in its entirety. Do not cherry-pick lines. Understand:
-
-- How it sets up the context
-- What arguments it passes
-- How it handles errors
-- What it does differently from the failing code
-
-#### Step 3: Identify Differences
-
-Compare the working example to the failing code line by line. The bug is in the differences. Common categories:
-
-- **Missing setup:** Working code initializes something the failing code skips
-- **Wrong arguments:** Type mismatch, wrong order, missing optional parameter
-- **State dependency:** Working code runs after some prerequisite; failing code does not
-- **Environment:** Working code runs in a different context (different config, different permissions)
-- **Timing:** Working code awaits something the failing code does not
-
-Record all differences in the session log.
-
----
-
-### Phase 3: HYPOTHESIZE — One Variable at a Time
-
-#### Step 1: Form a Single Falsifiable Hypothesis
-
-Based on your investigation and analysis, state a specific hypothesis:
-
-```
-"The failure occurs because [specific cause].
-If this hypothesis is correct, then [observable prediction].
-I can test this by [specific action]."
-```
-
-A good hypothesis is falsifiable — there is a concrete test that would disprove it. "Something is wrong with the configuration" is not a hypothesis. "The database connection string is missing the port number, causing connection timeout" is a hypothesis.
-
-#### Step 2: Test ONE Variable
-
-Change exactly ONE thing to test your hypothesis. If you change multiple things, you cannot determine which one had the effect.
-
-- Add a single log statement to check a value
-- Change one argument to match the working example
-- Add one missing setup step
-
-#### Step 3: Observe the Result
-
-Run the failing scenario. Did the behavior change?
-
-- **Hypothesis confirmed:** The change fixed it (or changed the error in the predicted way). Proceed to Phase 4.
-- **Hypothesis rejected:** Revert the change. Form a new hypothesis based on what you learned. The rejection itself is valuable data — record it.
-
-#### Step 4: Create Minimal Reproduction
-
-If the bug is in a complex system, extract a minimal reproduction:
-
-- Smallest possible code that exhibits the bug
-- Fewest dependencies
-- Simplest configuration
-
-This serves two purposes: it confirms your understanding of the root cause, and it becomes the basis for a regression test.
-
-Update the session status to `fixing`.
-
----
-
-### Phase 4: FIX — Root Cause, Not Symptoms
-
-#### Step 1: Write the Regression Test
-
-Before writing the fix, write a test that:
-
-- Reproduces the exact failure scenario
-- Asserts the correct behavior
-- Currently FAILS (proving it catches the bug)
-
-This follows harness-tdd discipline. The fix is driven by a failing test.
-
-#### Step 2: Implement the Fix
-
-Write a SINGLE fix that addresses the ROOT CAUSE identified in Phase 3. Not a workaround. Not a symptom suppression. The root cause.
-
-Characteristics of a good fix:
-
-- Changes as little code as possible
-- Addresses why the bug happened, not just what the bug did
-- Does not introduce new complexity
-- Would be obvious to someone reading the code later
-
-Characteristics of a bad fix (revert immediately):
-
-- Adds a special case or `if` branch for the specific failing input
-- Wraps the failure in a try-catch that swallows the error
-- Adds a retry loop or delay to "work around" a timing issue
-- Changes a type to `any` or removes a type check
-
-#### Step 3: Verify the Fix
-
-1. Run the regression test — must PASS
-2. Run the full test suite — all tests must PASS
-3. Run `harness validate` — must PASS
-4. Run `harness check-deps` — must PASS
-5. Manually verify the original failing scenario works
-
-#### Step 4: Verify the Test Catches the Bug
-
-Apply the regression test verification protocol:
-
-1. Temporarily revert the fix
-2. Run the regression test — must FAIL
-3. Restore the fix
-4. Run the regression test — must PASS
-
-If the test passes without the fix, the test does not catch the bug. Rewrite the test.
-
-#### Step 5: Close the Session
-
-Update the debug session:
-
-```markdown
-Status: resolved
-Resolved: <timestamp>
-
-## Resolution
-
-Root cause: <what actually caused the bug>
-Fix: <what was changed and why>
-Regression test: <path to test file>
-Learnings: <what to remember for next time>
-```
-
-Move the session file:
-
-```bash
-mv .harness/debug/active/<session-id>.md .harness/debug/resolved/
-```
-
-Append learnings to `.harness/learnings.md` if the bug revealed a pattern that should be remembered.
-
-Update the session status to `resolved`.
-
-## Harness Integration
-
-- **`harness cleanup`** — Run in Phase 1 INVESTIGATE for entropy analysis. Reveals dead code, pattern violations, and drift near the failure site.
-- **`harness validate`** — Run in Phase 4 VERIFY after applying the fix. Confirms the fix does not break project-wide constraints.
-- **`harness check-deps`** — Run in Phase 4 VERIFY. Confirms the fix does not introduce dependency violations.
-- **`harness state learn`** — Run after resolution to capture learnings for future sessions.
-- **Debug session files** — Stored in `.harness/debug/active/` (in progress) and `.harness/debug/resolved/` (completed). These persist across context resets.
-
-## Success Criteria
-
-- Phase 1 INVESTIGATE was completed before any fix was attempted
-- Root cause was identified and documented (not just the symptom)
-- A regression test exists that fails without the fix and passes with it
-- The fix addresses the root cause, not a symptom
-- All harness checks pass after the fix
-- Debug session file is complete with investigation log, hypotheses, and resolution
-- Learnings were captured for future reference
-
-## Examples
-
-### Example: API Endpoint Returns 500 Instead of 400
-
-**Phase 1 — INVESTIGATE:**
-
-```
-harness cleanup: No entropy issues near api/routes/users.ts
-Error: "Cannot read properties of undefined (reading 'email')"
-Stack trace points to: src/services/user-service.ts:34
-Reproduces consistently with POST /users and empty body {}
-Recent changes: Added input validation middleware (2 commits ago)
-Data flow: request.body -> validate() -> createUser(body.email)
-```
-
-**Phase 2 — ANALYZE:**
-
-```
-Working example: POST /orders handles empty body correctly
-Difference: /orders validates BEFORE destructuring; /users destructures BEFORE validating
-The validation middleware runs but its result is not checked
-```
-
-**Phase 3 — HYPOTHESIZE:**
-
-```
-Hypothesis: The validation middleware sets req.validationErrors but the route
-handler does not check it before accessing req.body.email.
-Test: Add a log before line 34 to check req.validationErrors.
-Result: Confirmed — validationErrors contains "email is required" but handler proceeds.
-```
-
-**Phase 4 — FIX:**
-
-```typescript
-// Regression test
-it('returns 400 when request body is empty', async () => {
-  const res = await request(app).post('/users').send({});
-  expect(res.status).toBe(400);
-  expect(res.body.errors).toContain('email is required');
-});
-
-// Fix: Check validation result before processing
-if (req.validationErrors?.length) {
-  return res.status(400).json({ errors: req.validationErrors });
-}
-```
-
-Revert test: Commenting out the validation check causes the test to fail with 500. Confirmed.
-
-## 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.
-- **One variable at a time.** Changing multiple things simultaneously is forbidden. If you changed two things and the bug is fixed, you do not know which change fixed it (or if the other change introduced a new bug).
-- **After 3 failed fix attempts, question the architecture.** If three consecutive hypotheses were wrong or three fixes did not resolve the issue, the problem is likely not where you think it is. Step back. Re-read the investigation log. Consider that the bug might be in a different layer entirely.
-- **Never "quick fix now, investigate later."** There is no later. The quick fix becomes permanent. The investigation never happens. The root cause festers. Fix it right or do not fix it.
-- **Regression test must fail without fix.** A test that passes whether or not the fix is present is not a regression test. It provides no protection.
-
-## Escalation
-
-- **Red flag: "It's probably X, let me fix that."** STOP. This is guessing, not debugging. You skipped Phase 1. Go back to investigation.
-- **Red flag: "One more fix attempt" after 2 failed attempts.** STOP. You are about to hit the 3-attempt wall. Step back and question your mental model of the system. Re-read the code from scratch. Consider that your understanding of how the system works may be wrong.
-- **Cannot reproduce the bug:** If you cannot make the bug happen consistently, you cannot debug it scientifically. Document exactly what you tried, what environment you tested in, and escalate. Do not guess at a fix for a bug you cannot reproduce.
-- **Bug is in a dependency you do not control:** Document the bug, write a test that demonstrates it, and escalate. If a workaround is needed, clearly mark it as a workaround with a reference to the upstream issue.
-- **Investigation reveals a systemic issue:** If the bug is a symptom of a larger architectural problem (e.g., widespread race conditions, fundamental type unsafety), escalate to the human. A local fix will not solve a systemic problem.
-- **Debug session exceeds 60 minutes without progress:** Something is wrong with the approach. Stop. Summarize what you know in the session file. Take a break (context reset). Return with fresh eyes and re-read the session file from the beginning.