@harness-engineering/cli 1.8.0 → 1.8.1

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

@@ -0,0 +1,268 @@
+# Harness Git Workflow
+
+> Worktree setup, dependency installation, baseline verification, and branch finishing. Clean isolation for every workstream.
+
+## When to Use
+
+- When starting work that should be isolated from the main branch (new feature, experiment, multi-task plan)
+- When finishing a branch and deciding how to land it (merge, PR, keep, discard)
+- When `on_pr` or `on_commit` triggers fire and worktree management is needed
+- When the human asks to "set up a branch" or "start a new workstream"
+- NOT for simple single-file changes that do not need branch isolation
+- NOT when work is already in progress on the correct branch
+
+## Process
+
+### Part A: Worktree Creation
+
+#### Step 1: Choose Worktree Location
+
+1. **Check for `.worktrees/` directory** in the project root. If it exists, use it — this is the preferred location.
+
+2. **Check CLAUDE.md or AGENTS.md** for worktree preferences. Some projects specify a custom worktree directory or naming convention. Follow those instructions.
+
+3. **If neither exists, ask the user:** "Where should I create the worktree? Options: (A) `.worktrees/<branch-name>` in the project root, (B) a sibling directory alongside the project, (C) a custom path."
+
+4. **If placing worktrees in the project directory,** verify that the worktree directory is gitignored. Check `.gitignore` for `.worktrees/` or the chosen directory name. If not gitignored, add it before creating the worktree.
+
+#### Step 2: Check for Existing Worktrees
+
+1. **Run `git worktree list`** to see active worktrees.
+
+2. **If a worktree already exists for the target branch,** do not create a duplicate. Ask: "A worktree for branch `<name>` already exists at `<path>`. Should I use it, or create a new branch?"
+
+3. **If the target directory already exists** (but is not a worktree), do not overwrite. Ask the user how to proceed.
+
+#### Step 3: Create Branch and Worktree
+
+1. **Create the branch** from the current HEAD (or from the specified base):
+
+   ```
+   git branch <branch-name> <base>
+   ```
+
+2. **Create the worktree:**
+
+   ```
+   git worktree add <path> <branch-name>
+   ```
+
+3. **Verify the worktree was created.** Check that the directory exists and contains a `.git` file (not a `.git` directory — worktrees use a file pointing to the main repo).
+
+#### Step 4: Auto-Detect and Run Setup
+
+Inspect the worktree for project files and run the appropriate setup:
+
+| File Found                         | Action                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| `package.json`                     | `npm install` (or `yarn install` / `pnpm install` if lockfile indicates) |
+| `Cargo.toml`                       | `cargo build`                                                            |
+| `go.mod`                           | `go mod download`                                                        |
+| `requirements.txt`                 | `pip install -r requirements.txt`                                        |
+| `pyproject.toml`                   | `pip install -e .` or `poetry install`                                   |
+| `Gemfile`                          | `bundle install`                                                         |
+| `Makefile` (with `install` target) | `make install`                                                           |
+
+If multiple project files exist (monorepo), install at the root level. Do not guess which subpackages to install — follow the project's documented setup or ask.
+
+#### Step 5: Verify Clean Baseline
+
+Before any work begins, verify the worktree is in a clean, working state:
+
+1. **Run the test suite.** All tests must pass on the fresh branch before any changes.
+
+2. **Run `harness validate`.** Project health must be green before starting work.
+
+3. **If tests fail or validation fails on the fresh branch,** stop. The base branch has issues. Report: "Baseline verification failed on fresh branch: [failure details]. The base branch needs to be fixed first."
+
+4. **Record the baseline.** Note the test count and validation result. This is the comparison point for the branch finishing phase.
+
+---
+
+### Part B: Branch Finishing
+
+When work on the branch is complete, follow this protocol to land the changes.
+
+#### Step 1: Pre-Finish Verification
+
+1. **Run the full test suite.** All tests must pass.
+
+2. **Run `harness validate`.** Project health must be green.
+
+3. **Check for uncommitted changes.** Run `git status`. All changes must be committed. If there are uncommitted changes, commit or stash them before finishing.
+
+4. **Check the branch is up to date.** If the base branch has advanced since the worktree was created:
+   ```
+   git fetch origin
+   git log HEAD..origin/main --oneline
+   ```
+   If there are new commits on the base, rebase or merge before finishing:
+   ```
+   git rebase origin/main
+   ```
+   Re-run tests after rebasing.
+
+#### Step 2: Choose Finishing Strategy
+
+Present 4 options to the user:
+
+1. **Merge locally.** Merge the branch into the base branch on the local machine.
+   - Best for: small changes, solo work, when CI is not required
+   - Command: `git checkout main && git merge <branch>`
+
+2. **Push and create PR.** Push the branch to the remote and open a pull request.
+   - Best for: team work, changes that need review, when CI must pass
+   - Command: `git push -u origin <branch>` then create PR via `gh pr create`
+
+3. **Keep as-is.** Leave the branch and worktree in place for continued work later.
+   - Best for: work-in-progress, experiments, paused projects
+
+4. **Discard.** Delete the branch and worktree. All changes are lost.
+   - Best for: failed experiments, abandoned approaches
+   - Safety: Confirm with the user before discarding. List the commits that will be lost.
+
+#### Step 3: Execute Chosen Strategy
+
+**If merge locally:**
+
+```bash
+cd <main-repo-path>
+git merge <branch-name>
+# Run tests on main after merge
+# Run harness validate after merge
+git worktree remove <worktree-path>
+git branch -d <branch-name>
+```
+
+**If push and create PR:**
+
+```bash
+cd <worktree-path>
+git push -u origin <branch-name>
+gh pr create --title "<title>" --body "<description>"
+# Report the PR URL to the user
+# Leave worktree in place until PR is merged
+```
+
+**If keep as-is:**
+
+```
+No action needed. Report the worktree path and branch name for future reference.
+```
+
+**If discard:**
+
+```bash
+# Confirm with user first — list commits that will be lost
+git worktree remove <worktree-path>
+git branch -D <branch-name>
+```
+
+#### Step 4: Clean Up
+
+1. **Remove the worktree** (unless keeping as-is or waiting for PR merge):
+
+   ```
+   git worktree remove <worktree-path>
+   ```
+
+2. **Prune stale worktree references:**
+
+   ```
+   git worktree prune
+   ```
+
+3. **Verify cleanup.** Run `git worktree list` and confirm the removed worktree is no longer listed.
+
+## Harness Integration
+
+- **`harness validate`** — Run during baseline verification (Step 5 of Part A) and pre-finish verification (Step 1 of Part B). Ensures project health is green at both boundaries.
+- **Test runner** — Run fresh in the worktree, not in the main repo. Tests must pass both at baseline (before work) and at finish (after work).
+- **`.gitignore`** — Verify worktree directory is gitignored if it lives inside the project tree.
+
+## Success Criteria
+
+- Worktree was created in the correct location (`.worktrees/` preferred, or per project convention)
+- Dependencies were auto-detected and installed
+- Baseline verification passed (tests green, harness validates) before any work began
+- Branch finishing strategy was chosen by the user (not assumed)
+- Chosen strategy was executed correctly (merge, PR, keep, or discard)
+- Worktree was cleaned up after finishing (unless keeping for continued work)
+- No stale worktree references remain after cleanup
+
+## Examples
+
+### Example: Setting Up a Worktree for a New Feature
+
+```bash
+# Check for preferred location
+ls .worktrees/    # exists — use it
+
+# Check gitignore
+grep '.worktrees' .gitignore    # found — good, already gitignored
+
+# Check existing worktrees
+git worktree list
+# /Users/dev/project  abc1234 [main]
+# No existing worktree for this feature
+
+# Create branch and worktree
+git branch feat/notifications main
+git worktree add .worktrees/notifications feat/notifications
+
+# Auto-detect setup (found package.json)
+cd .worktrees/notifications && npm install
+
+# Verify baseline
+npm test                # 142 tests, all pass
+harness validate        # passes
+
+# Ready to work. Report:
+# "Worktree created at .worktrees/notifications on branch feat/notifications.
+#  142 tests passing. harness validate green. Ready to start."
+```
+
+### Example: Finishing a Branch with PR
+
+```bash
+# Pre-finish verification
+cd .worktrees/notifications
+npm test                # 158 tests, all pass (16 new)
+harness validate        # passes
+git status              # clean — all committed
+
+# Check if base has advanced
+git fetch origin
+git log HEAD..origin/main --oneline
+# 3 new commits on main — rebase
+
+git rebase origin/main
+npm test                # still passes after rebase
+
+# User chooses: Push and create PR
+git push -u origin feat/notifications
+gh pr create --title "feat(notifications): email and in-app notifications" \
+  --body "Implements notification service with create, list, and expiry.
+  16 new tests. All passing."
+
+# Report: "PR created: https://github.com/org/repo/pull/42
+#  Worktree at .worktrees/notifications kept until PR merges."
+```
+
+### Example: Discarding a Failed Experiment
+
+```bash
+# User says: "That approach didn't work, let's scrap it."
+
+# Show what will be lost
+git log main..HEAD --oneline
+# a1b2c3d try websocket approach
+# d4e5f6g add socket.io dependency
+# "These 2 commits will be lost. Discard? (yes/no)"
+# Human: "yes"
+
+git worktree remove .worktrees/ws-experiment
+git branch -D feat/ws-experiment
+git worktree prune
+git worktree list    # ws-experiment no longer listed
+```

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

@@ -0,0 +1,31 @@
+name: harness-git-workflow
+version: "1.0.0"
+description: Git workflow best practices integrated with harness validation
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run harness-git-workflow
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-git-workflow
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,167 @@
+# Harness Integrity
+
+> Unified integrity gate — single invocation chains mechanical verification with AI-powered code review and produces a consolidated pass/fail report.
+
+## When to Use
+
+- Before opening or merging a pull request
+- At project milestones as a comprehensive quality check
+- When you need a single authoritative answer: "is this code ready to ship?"
+- NOT after every task (use `harness-verify` for quick post-task checks)
+- NOT for deep architectural audits (use `harness-verification` for that)
+
+## Relationship to Other Skills
+
+| Skill                        | What It Does                                   | Scope                  | Time  |
+| ---------------------------- | ---------------------------------------------- | ---------------------- | ----- |
+| **harness-verify**           | Mechanical only: typecheck, lint, test         | Exit codes             | ~30s  |
+| **harness-code-review**      | AI only: change-type-aware review              | LLM analysis           | ~2min |
+| **harness-integrity** (this) | Both: verify + code-review unified             | Full pipeline          | ~3min |
+| **harness-verification**     | Deep audit: architecture, patterns, edge cases | Thorough investigation | ~5min |
+
+`harness-integrity` is the standard pre-PR gate. It runs the fast mechanical checks first, then layers on AI review, and produces a single consolidated report.
+
+## Process
+
+### Phase 1: VERIFY
+
+Invoke `harness-verify` to run the mechanical quick gate.
+
+1. Delegate entirely to `harness-verify` — typecheck, lint, test.
+2. Capture the structured result (PASS/FAIL per check).
+3. **If ALL three checks FAIL**, stop here. Do not proceed to Phase 2. The code is not in a reviewable state.
+4. If at least one check passes (or some are skipped), proceed to Phase 2.
+
+### Phase 1.5: SECURITY SCAN
+
+Run the built-in security scanner as a mechanical check between verification and AI review.
+
+1. Use `run_security_scan` MCP tool against the project root (or changed files if available).
+2. Capture findings by severity: errors, warnings, info.
+3. **Error-severity security findings are blocking** — they cause the overall integrity check to FAIL, same as a test failure.
+4. Warning/info findings are included in the report but do not block.
+
+### Phase 1.7: DESIGN HEALTH (conditional)
+
+When the project has `design` configured in `harness.config.json`:
+
+1. Run `harness-design` in review mode to check existing components against design intent and anti-patterns.
+2. Run `harness-accessibility` in scan+evaluate mode to check WCAG compliance.
+3. Combine findings into a design health summary:
+   - Error count (blocking, based on strictness)
+   - Warning count (non-blocking)
+   - Info count (advisory)
+4. **Error-severity design findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, design findings do not block.
+5. If no `design` block exists, skip this phase entirely.
+
+### Phase 1.8: I18N SCAN (conditional)
+
+When the project has `i18n.enabled: true` in `harness.config.json`:
+
+1. Run `harness-i18n` in scan mode to detect hardcoded strings, missing translations, locale-sensitive formatting issues, and RTL violations.
+2. Combine findings into an i18n health summary:
+   - Error count (blocking, based on `i18n.strictness`)
+   - Warning count (non-blocking)
+   - Info count (advisory)
+3. **Error-severity i18n findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, i18n findings do not block.
+4. If no `i18n` block exists or `i18n.enabled` is false, skip this phase entirely.
+
+### Phase 2: REVIEW
+
+Run change-type-aware AI review using `harness-code-review`.
+
+1. Detect the change type if not provided: `feature`, `bugfix`, `refactor`, or `docs`.
+2. Invoke `harness-code-review` with the detected change type.
+3. Capture the review findings: suggestions, blocking issues, and notes.
+4. A review finding is "blocking" only if it would cause a runtime error, data loss, or security vulnerability.
+5. The AI review includes a security-focused pass that complements the mechanical scanner — checking for semantic issues like user input flowing to dangerous sinks across function boundaries.
+
+### Phase 3: REPORT
+
+Produce a unified integrity report in this exact format:
+
+```
+Integrity Check: [PASS/FAIL]
+- Tests:    [PASS/FAIL/SKIPPED]
+- Lint:     [PASS/FAIL/SKIPPED]
+- Types:    [PASS/FAIL/SKIPPED]
+- Security: [PASS/WARN/FAIL] ([count] errors, [count] warnings)
+- Design:   [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
+- i18n:     [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
+- Review:   [PASS/FAIL] ([count] suggestions, [count] blocking)
+
+Overall: [PASS/FAIL]
+```
+
+Rules:
+
+- Overall `PASS` requires: all non-skipped mechanical checks pass AND zero blocking review findings AND zero blocking design findings (strict mode only) AND zero blocking i18n findings (strict mode only).
+- Any mechanical failure OR any blocking review finding means `FAIL`.
+- On FAIL, include a summary section listing each failure reason.
+- Non-blocking review suggestions are noted but do not cause FAIL.
+
+## Deterministic Checks
+
+- **Phase 1 is fully deterministic.** Exit codes determine pass/fail with no interpretation.
+- **Phase 2 involves LLM judgment.** The AI review may produce different results on repeated runs. Only "blocking" findings (runtime errors, data loss, security) affect the overall result.
+
+## Harness Integration
+
+- Chains harness-verify (mechanical) and harness-code-review (AI) into a unified pipeline
+- Follows Principle 7 — deterministic checks always run first
+- Consumes change-type detection from harness-code-review for per-type checklists
+- Output can be written to `.harness/integrity-report.md` for CI integration
+- Invokes `harness-design` and `harness-accessibility` for design health when `design` config exists
+- Design strictness from config controls whether design findings block the overall result
+- Invokes `harness-i18n` for i18n compliance when `i18n.enabled` is true in config. i18n strictness controls whether findings block the overall result.
+
+## Success Criteria
+
+- [ ] Mechanical verification ran and produced structured results
+- [ ] AI review ran with change-type awareness
+- [ ] Unified report follows the exact format
+- [ ] Overall verdict correctly reflects both mechanical and review results
+
+## Examples
+
+### Example: All Clear
+
+```
+Integrity Check: PASS
+- Tests: PASS (42/42)
+- Lint: PASS (0 warnings)
+- Types: PASS
+- Security: PASS (0 errors, 0 warnings)
+- Design: PASS (0 errors, 0 warnings)
+- i18n: PASS (0 errors, 0 warnings)
+- Review: 1 suggestion (0 blocking)
+```
+
+### Example: Security Blocking Issue
+
+```
+Integrity Check: FAIL
+- Tests: PASS (42/42)
+- Lint: PASS
+- Types: PASS
+- Security: FAIL (1 error, 0 warnings)
+  - [SEC-INJ-002] src/auth/login.ts:42 — SQL query built with string concatenation
+- Design: WARN (0 errors, 2 warnings)
+- i18n: SKIPPED
+- Review: 3 findings (1 blocking)
+
+Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
+```
+
+## 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).
+- **No partial reports.** The report must include results from all phases that were executed. Do not output Phase 1 results without attempting Phase 2 (unless the all-fail early stop triggers).
+- **Fresh execution only.** Do not reuse cached results. Run everything from scratch each time.
+
+## Escalation
+
+- **All checks fail:** If typecheck, lint, and test all fail in Phase 1, stop immediately. Report the failures and skip Phase 2. The code needs basic fixes before review is worthwhile.
+- **Architectural concerns:** If the AI review identifies architectural concerns, note them in the report but do not mark them as blocking. Architectural decisions require human judgment.
+- **Timeout:** Phase 1 inherits the 120-second per-command timeout from `harness-verify`. Phase 2 has a 180-second timeout for the AI review.
+- **Missing dependencies:** If `harness-verify` or `harness-code-review` skills are unavailable, report the missing dependency and mark the corresponding phase as `ERROR`.

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

@@ -0,0 +1,47 @@
+name: harness-integrity
+version: "1.0.0"
+description: Unified integrity gate — chains verify (quick gate) with AI review into a single report
+triggers:
+  - manual
+  - on_pr
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-integrity
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: change-type
+      description: "Type of change: feature, bugfix, refactor, docs"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-integrity
+    path: string
+type: rigid
+cognitive_mode: meticulous-verifier
+phases:
+  - name: verify
+    description: Run harness-verify quick gate (test, lint, typecheck)
+    required: true
+  - name: review
+    description: Run change-type-aware AI review
+    required: true
+  - name: report
+    description: Produce unified integrity report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-verify
+  - harness-code-review