harness-everything 0.2.1 → 0.3.6

package/todo-driven-workflow/references/execution-guide.md

@@ -0,0 +1,27 @@
+# Execution Guide (Deep Dive)
+
+## Tracker selection
+
+```mermaid
+flowchart TD
+  Start[Task needs milestones] --> Native{Native TODO tracker available?}
+  Native -->|Yes| Host[Use the host tracker]
+  Native -->|No| Markdown[Create tasks/todo.md or .github/harness-everything/todo.md]
+  Host --> One[Keep exactly one item in-progress]
+  Markdown --> One
+  One --> Check[Run the named verification command]
+  Check --> Record[Record evidence and mark the item complete]
+```
+
+## Rules
+
+1. Define 3-7 verifiable milestones before changing files.
+2. Prefer the host's native TODO tool and preserve its status history.
+3. If no native tracker exists, use a Markdown checklist in the repository or platform project-instructions area.
+4. Each item names its output, pass condition, and verification command.
+5. Keep one item `in-progress`; complete it from evidence before starting another.
+6. When parallel agents are active, isolate their writes with `using-git-worktrees` and merge only after scope review.
+
+The former repository TODO CLI is intentionally not a fallback. This keeps
+tracking native to the host or transparent in Markdown and avoids shared
+cross-session state collisions.

package/using-git-worktrees/SKILL.md

@@ -1,161 +1,49 @@
----
-name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
----
-
-# Using Git Worktrees
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Starting feature work that needs isolation from the current workspace, or before executing an implementation plan. |
-| **Expected Output** | An isolated workspace (native worktree tool preferred, `git worktree add` fallback) with dependencies installed and a clean baseline test run confirmed. |
-| **State Mutations** | May create a new worktree directory/branch (`.worktrees/<branch>` by default) and add it to `.gitignore` if not already ignored. |
-| **Enforcement Gate** | **MUST** detect an already-isolated workspace first (`GIT_DIR != GIT_COMMON`, excluding submodules) and skip creating a redundant one. **MUST** verify the worktree directory is gitignored before creating it. **MUST** get human consent before creating a new worktree if no preference was already declared. |
-
-## Overview
-
-Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
-
-**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
-
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
-
-## Step 0: Detect Existing Isolation
-
-**Before creating anything, check if you are already in an isolated workspace.**
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
-
-```bash
-# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
-git rev-parse --show-superproject-working-tree 2>/dev/null
-```
-
-**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
-
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
-
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
-
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
-
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.
-
-## Step 1: Create Isolated Workspace
-
-**You have two mechanisms. Try them in this order.**
-
-### 1a. Native Worktree Tools (preferred)
-
-The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
-
-Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
-
-Only proceed to Step 1b if you have no native worktree tool available.
-
-### 1b. Git Worktree Fallback
-
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
-
-#### Directory Selection
-
-Follow this priority order. Explicit user preference always beats observed filesystem state.
-
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
-
-2. **Check for an existing project-local worktree directory:**
-   ```bash
-   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-   ls -d worktrees 2>/dev/null      # Alternative
-   ```
-   If found, use it. If both exist, `.worktrees` wins.
-
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-#### Safety Verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
-```
-
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
-
-**Why critical:** Prevents accidentally committing worktree contents to repository.
-
-#### Create the Worktree
-
-```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
-```
-
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
-
-## Step 2: Project Setup
-
-Auto-detect and run appropriate setup:
-
-```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
-
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
-
-## Step 3: Verify Clean Baseline
-
-Run tests to ensure workspace starts clean:
-
-```bash
-# Use project-appropriate command
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:** Report failures, ask whether to proceed or investigate.
-
-**If tests pass:** Report ready.
-
-### Report
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
-
-## Quick Reference
-
-| Situation | Action |
-|-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
-| `.worktrees/` exists | Use it (verify ignored) |
+---
+name: using-git-worktrees
+description: Use when starting feature work needing isolation or before implementation plans - ensures an isolated workspace via native tools or git worktree fallback
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
+---
+
+# Using Git Worktrees
+
+Native worktree tools first, git fallback.
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Isolation-needing feature work; pre-plan setup. |
+| **Expected Output** | Isolated workspace plus clean test baseline. |
+| **State Mutations** | Creates `.worktrees/<branch>`; updates `.gitignore` if needed. |
+| **Enforcement Gate** | Detect existing isolation first; seamless sandbox fallback. |
+
+## Workflow
+
+**Step 0 — Detect existing isolation** (adapt per `environment-detection`):
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git branch --show-current
+git rev-parse --show-superproject-working-tree
+```
+Dirs differ and no superproject → already isolated; skip to Step 2; never nest. Superproject → submodule (normal repo). Else honor declared preference or ask consent; declined → in place.
+
+**Step 1 — Create**: native tool (`EnterWorktree`, `/worktree`, `--worktree`) first — raw git creates phantom state. Else verify ignored via `git check-ignore -q .worktrees || git check-ignore -q worktrees`; unignored → add to .gitignore and commit. Then `git worktree add "$path" -b "$BRANCH_NAME"` at declared preference, existing `.worktrees/`/`worktrees/`, or default `.worktrees/`. Sandbox denial → work in place.
+
+**Step 2 — Setup**: npm/cargo/pip/poetry/go.
+
+**Step 3 — Baseline**: run tests (`npm test`/`cargo test`/`pytest`/`go test ./...`); failures → report, ask.
+
+Deep dive: references/workflow-details.md
+
+## USE FOR:
+- feature work needing isolation
+- pre-implementation-plan setup
+- native vs manual `git worktree add`
+
+## DO NOT USE FOR:
+- nesting inside an existing worktree
+- branch/merge workflows

package/using-git-worktrees/references/workflow-details.md

@@ -0,0 +1,108 @@
+# Using Git Worktrees — Full Workflow Reference
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Need Workspace Isolation] --> CheckIso{1. Already in Worktree?}
+
+    CheckIso -- Yes (GIT_DIR != GIT_COMMON) --> Setup[3. Run Project Setup & Dependencies]
+    CheckIso -- No (Normal Repo) --> CheckNative{2. Native Worktree Tool Available?}
+
+    CheckNative -- Yes --> RunNative[Use Native Worktree Tool] --> Setup
+    CheckNative -- No --> RunGit[Try git worktree add .worktrees/branch]
+
+    RunGit -- Success --> Setup
+    RunGit -- Fails / Denied --> WorkInPlace[Fallback: Work in Place in Current Directory] --> Setup
+
+    Setup --> RunBaseline[4. Verify Clean Test Baseline]
+    RunBaseline --> Done[Isolated Workspace Ready]
+```
+
+## Step 0 detail
+
+**Submodule guard:** `git-dir` differs from `git-common-dir` inside git submodules as well. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree
+```
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to project setup.
+
+## Step 1a detail — native tools
+
+The user has asked for an isolated workspace. Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to setup.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only use the git fallback if you have no native worktree tool available.
+
+## Step 1b detail — directory selection priority
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+2. **Check for an existing project-local worktree directory:** Check if `.worktrees/` or `worktrees/` exists using cross-platform file system tools (`read_file` / `list_dir` or native shell test commands). If found, use it. If both exist, `.worktrees` wins.
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+### Safety verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees || git check-ignore -q worktrees
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### Create the worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+## Step 2 detail — project setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 3 detail — baseline report
+
+If tests fail: report failures, ask whether to proceed or investigate. If tests pass:
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```

package/verification-loop/SKILL.md

@@ -1,138 +1,46 @@
----
-name: verification-loop
-description: "A comprehensive verification system for Claude Code sessions."
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
-metadata:
-  origin: ECC
----
-
-# Verification Loop Skill
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Approaching task completion or PR creation. Input: The modified project files. |
-| **Expected Output** | Terminal logs showing successful Build, Type Check, Lint, and Test execution. |
-| **State Mutations** | None. Pure verification. |
-| **Enforcement Gate** | You MUST execute `npm run build`, `npm run lint`, and `npm run test` (or equivalent). You cannot complete the task if any of these return Exit Code 1. |
-
-A comprehensive verification system for Claude Code sessions.
-
-## When to Use
-
-Invoke this skill:
-- After completing a feature or significant code change
-- Before creating a PR
-- When you want to ensure quality gates pass
-- After refactoring
-
-## Verification Phases
-
-### Phase 1: Build Verification
-```bash
-# Check if project builds
-npm run build 2>&1 | tail -20
-# OR
-pnpm build 2>&1 | tail -20
-```
-
-If build fails, STOP and fix before continuing.
-
-### Phase 2: Type Check
-```bash
-# TypeScript projects
-npx tsc --noEmit 2>&1 | head -30
-
-# Python projects
-pyright . 2>&1 | head -30
-```
-
-Report all type errors. Fix critical ones before continuing.
-
-### Phase 3: Lint Check
-```bash
-# JavaScript/TypeScript
-npm run lint 2>&1 | head -30
-
-# Python
-ruff check . 2>&1 | head -30
-```
-
-### Phase 4: Test Suite
-```bash
-# Run tests with coverage
-npm run test -- --coverage 2>&1 | tail -50
-
-# Check coverage threshold
-# Target: 80% minimum
-```
-
-Report:
-- Total tests: X
-- Passed: X
-- Failed: X
-- Coverage: X%
-
-### Phase 5: Security Scan
-```bash
-# Check for secrets
-grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
-grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
-
-# Check for console.log
-grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
-```
-
-### Phase 6: Diff Review
-```bash
-# Show what changed
-git diff --stat
-git diff HEAD~1 --name-only
-```
-
-Review each changed file for:
-- Unintended changes
-- Missing error handling
-- Potential edge cases
-
-## Output Format
-
-After running all phases, produce a verification report:
-
-```
-VERIFICATION REPORT
-==================
-
-Build:     [PASS/FAIL]
-Types:     [PASS/FAIL] (X errors)
-Lint:      [PASS/FAIL] (X warnings)
-Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
-Security:  [PASS/FAIL] (X issues)
-Diff:      [X files changed]
-
-Overall:   [READY/NOT READY] for PR
-
-Issues to Fix:
-1. ...
-2. ...
-```
-
-## Continuous Mode
-
-For long sessions, run verification every 15 minutes or after major changes:
-
-```markdown
-Set a mental checkpoint:
-- After completing each function
-- After finishing a component
-- Before moving to next task
-
-Run: /verify
-```
-
-## Integration with Hooks
-
-This skill complements PostToolUse hooks but provides deeper verification.
-Hooks catch issues immediately; this skill provides comprehensive review.
+---
+name: verification-loop
+description: "Run objective verification gates (build, types, lint, tests, security scan) before claiming work done. USE FOR: \"run the full verification loop\", \"verify this is done before delivery\". DO NOT USE FOR: \"design discussions with no completed work\", \"planning without code changes\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.6
+---
+
+# Verification Loop
+
+Run objective quality gates before claiming a change is ready.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Completed implementation or change awaiting delivery. |
+| **Expected Output** | Evidence-backed verification report and delivery decision. |
+| **State Mutations** | Fills a report from `templates/verification-report.template.md`. |
+| **Enforcement Gate** | Build, type, lint, test, security, and diff gates all pass. |
+
+## USE FOR:
+
+- Verify a feature or change before delivery
+- Run quality gates before a PR
+
+## DO NOT USE FOR:
+
+- Fixing failures without re-running the loop
+- Writing new features or tests (use `tdd`)
+
+## Workflow
+
+Never claim completion until every applicable gate passes. On failure, fix the cause
+and rerun from the first affected gate.
+
+1. Build: `npm run build`.
+2. Types: `npx tsc --noEmit` or `pyright .`.
+3. Lint: `npm run lint` or `ruff check .`.
+4. Tests and coverage: `npm run test -- --coverage`.
+5. Security scan: secrets and stray logs.
+6. Diff review: `git diff --stat` and unintended-change checks.
+7. Fill `templates/verification-report.template.md` with evidence.
+
+Deep dive: `references/verification-phases.md`

package/verification-loop/references/verification-phases.md

@@ -0,0 +1,116 @@
+# Verification Phases (Deep Dive)
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Pre-Delivery / PR Verification] --> Build[1. Phase 1: Build Verification]
+    Build --> Type[2. Phase 2: Type Check]
+    Type --> Lint[3. Phase 3: Lint Check]
+    Lint --> Test[4. Phase 4: Test Suite Execution]
+    Test --> Security[5. Phase 5: Security & Secret Scan]
+    Security --> Diff[6. Phase 6: Diff Review]
+    
+    Diff --> CheckScript{7. Is verify-gate.js / Template Available?}
+    
+    CheckScript -- Yes --> RunScript[Run harness-everything/scripts/verify-gate.js / Fill verification-report.template.md]
+    CheckScript -- No --> DirectReport[Output Verification Report Inline in Response]
+    
+    RunScript --> ReportResult{All Verification Gates Passed?}
+    DirectReport --> ReportResult
+    
+    ReportResult -- Exit 0 / All Green --> Deliver[Task Ready for Delivery / PR]
+    ReportResult -- Failures Detected --> Fix[Fix Issues in Code & Re-verify] --> Build
+```
+
+Adapt commands according to the project's ecosystem and active environment (`environment-detection`). Run commands directly without non-portable POSIX pipe assumptions (avoid raw `head`, `tail`, `grep`, `2>/dev/null` piping on Windows).
+
+## Phase 1: Build Verification
+
+```bash
+# Check if project builds (JS/TS example)
+npm run build
+# OR
+pnpm build
+```
+
+If build fails, STOP and fix before continuing.
+
+## Phase 2: Type Check
+
+```bash
+# TypeScript projects
+npx tsc --noEmit
+
+# Python projects
+pyright .
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+## Phase 3: Lint Check
+
+```bash
+# JavaScript/TypeScript
+npm run lint
+
+# Python
+ruff check .
+```
+
+## Phase 4: Test Suite
+
+```bash
+# Run tests with coverage
+npm run test -- --coverage
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+## Phase 5: Security & Code Hygiene Scan
+
+Use native IDE search tools (`grep_search` / `file_search`) or cross-platform scripts rather than raw terminal `grep` pipes:
+- Check for hardcoded API keys / secrets (`sk-`, `api_key`).
+- Check for leftover debug log statements (`console.log`, `print`).
+
+## Phase 6: Diff Review
+
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes
+- Missing error handling
+- Potential edge cases
+
+## Output Format
+
+After running all phases, fill in `verification-loop/templates/verification-report.template.md` with the actual results and present it.
+
+## Continuous Mode
+
+For long sessions, run verification every 15 minutes or after major changes:
+
+```markdown
+Set a mental checkpoint:
+- After completing each function
+- After finishing a component
+- Before moving to next task
+
+Run: /verify
+```
+
+## Integration with Hooks
+
+This skill complements PostToolUse hooks but provides deeper verification.
+Hooks catch issues immediately; this skill provides comprehensive review.

package/verification-loop/templates/verification-report.template.md

@@ -0,0 +1,15 @@
+VERIFICATION REPORT
+==================
+
+Build:     [PASS/FAIL]
+Types:     [PASS/FAIL] (X errors)
+Lint:      [PASS/FAIL] (X warnings)
+Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:  [PASS/FAIL] (X issues)
+Diff:      [X files changed]
+
+Overall:   [READY/NOT READY] for PR
+
+Issues to Fix:
+1. ...
+2. ...