harness-everything 0.2.0

package/tdd/guides/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/tdd/guides/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/tdd/guides/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/tdd/guides/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/todo-driven-workflow/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: todo-driven-workflow
+description: Enforces a deliberate, step-by-step execution loop.
+author: Miya Daniel | Harness Core Team
+version: 1.1.0
+metadata:
+  type: harness-discipline
+---
+
+# Todo-Driven Workflow (以 TODO 驅動的自動化工作流)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 2/3 Task Identification. Input: High-level task description. |
+| **Expected Output** | Granular execution state. A series of terminal calls to `todo-cli.js`. |
+| **State Mutations** | MUST write to `.claude/harness-state/todo-state.json` via CLI. |
+| **Enforcement Gate** | `node harness-everything/scripts/todo-cli.js`. Exits with Code 1 if multitasking, bypassing initialization, or skipping `verify-gate.js`. |
+
+This skill enforces a disciplined execution loop. It prevents "hallucinated progress" by forcing the Agent to track exact state and prove completion before moving to the next step. 
+
+---
+
+## ⚡ Core Trigger (觸發時機)
+This workflow is **the default operating behavior** for any complex, multi-step, or multi-file development tasks (Tier 2 and Tier 3).
+
+## ⚙️ Execution Method
+
+| Environment | Primary Task Tracker | Implementation Method |
+| :--- | :--- | :--- |
+| **All Environments** | `todo-cli.js` | You MUST use `node harness-everything/scripts/todo-cli.js` for all state transitions. Do NOT rely on prompt text. |
+
+---
+
+## 🔄 Execution Loop: Think > Try > Summarize > Record
+
+### 1. Analyze and Plan (Think)
+Break the high-level goal into **3 to 7 concrete, verifiable sub-tasks**.
+
+### 2. Initialize the Todo List (Record)
+- **CRITICAL ACTION**: You MUST use the `run_in_terminal` tool to run `node harness-everything/scripts/todo-cli.js init "Task 1" "Task 2"` BEFORE modifying any code.
+- *Rule*: The terminal output will confirm the list is initialized.
+
+### 3. Step-by-Step Execution
+1. **Start**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js start <id>`. **If you try to start two tasks, the script will crash and block you.**
+2. **Execute**: Perform the necessary actions (read files, grep, run terminal commands, edit files).
+3. **Verify**: The validation gate is hardcoded into the completion step.
+4. **Complete**: Use `run_in_terminal` to run `node harness-everything/scripts/todo-cli.js complete <id>`. If the internal `verify-gate.js` check fails, this command will Exit 1 and block you.
+
+### 4. Handling Blocker Failures (Dynamic Adaptation)
+If a step fails:
+- Use `node harness-everything/scripts/todo-cli.js add "Fix specific error"` to insert a blocker.
+- Do NOT silently ignore or bypass the error.

package/using-git-worktrees/SKILL.md

@@ -0,0 +1,161 @@
+---
+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) |

package/verification-loop/SKILL.md

@@ -0,0 +1,138 @@
+---
+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.

package/verify-before-claim/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: verify-before-claim
+description: "Verify external framework/API claims and unmeasured perf/cost estimates against an authoritative source before asserting them, instead of answering from training memory."
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+metadata:
+  type: harness-discipline
+---
+
+# Verify Before Claim
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | About to state how an external system (framework/library/SDK/API/service) currently behaves, or about to state an unmeasured performance/cost/timing number. |
+| **Expected Output** | The claim is backed by a `WebFetch`/`WebSearch`-sourced quote from authoritative docs, or an actual measurement — never asserted from training memory alone. |
+| **State Mutations** | None — this is a discipline governing what gets asserted in the response, not a file-mutating skill. |
+| **Enforcement Gate** | An external-behavior claim without a same-session fetch/search backing it **MUST NOT** be asserted with confidence; an unmeasured number **MUST** be explicitly labeled as an estimate, not presented as fact. |
+
+Training memory goes stale and is easy to misremember with full confidence.
+This skill exists because that failure mode is real and already happened in
+this repo: an early claim that `rule-of-3.js`'s `process.exit(1)` blocked a
+Claude Code `PreToolUse` hook was wrong — the official docs say only
+`exit(2)` blocks, `exit(1)` is a non-blocking error — and it was only caught
+by actually fetching `code.claude.com/docs/en/hooks` instead of trusting the
+assumption. The circuit breaker had never blocked anything until that got
+checked.
+
+`harness-everything/scripts/tier-router.js` fires a lightweight keyword-based
+reminder for this automatically (`UserPromptSubmit`, "FACT-AUDIT REMINDER"
+block) so you don't have to be manually pushed into checking every time. This
+file is the actual discipline behind that reminder.
+
+## TRIGGER — verify before asserting, don't skip because the answer "feels obvious"
+
+Whenever either is true:
+
+1. **You are about to state how an external system currently behaves** —
+   a framework, library, SDK, CLI tool, API, or service's schema, defaults,
+   exit codes, config flags, pricing, rate limits, version-specific behavior,
+   or "does X support Y." This includes cases that feel like common
+   knowledge — exit-code conventions, hook payload shapes, and default
+   values are exactly where confident misremembering happens.
+2. **You are about to state a performance, cost, or timing number that
+   wasn't produced by an actual run in this session** — "this should take
+   ~X," "this is O(n)," "this will cost about $Y," "this should be fast
+   enough." An estimate rendered with confidence is still an estimate.
+
+## Procedure
+
+- For claim (1): `WebFetch` the tool's official documentation first. If the
+  official docs don't cover it, `WebSearch` and cite what you find. Quote the
+  relevant part back rather than paraphrasing from memory — paraphrasing
+  reintroduces the same risk you're trying to avoid.
+- For claim (2): if the stakes justify it (the number feeds a design
+  decision, a rejection/deferral, or something the user will act on),
+  actually run it — a real benchmark, a real timing, a real measurement —
+  instead of reasoning about what it "should" be. If running it isn't
+  feasible, say explicitly that the number is an unverified estimate; don't
+  present it with the same confidence as a measured fact.
+- If a fetch or search comes back inconclusive or contradicts your prior
+  assumption, say so and show the source — don't quietly reconcile it into
+  something that sounds more confident than what you actually found.
+
+## SKIP — don't over-trigger
+
+- **The claim is about this repository's own code**, not an external system.
+  Reading the actual source here already is the authoritative check; no web
+  verification needed.
+- **The user supplied the fact or number directly** in this conversation —
+  trust their firsthand statement, don't second-guess it with a search.
+- **Already verified this session** — don't re-fetch the same source
+  redundantly if it was already checked earlier in this conversation and
+  nothing suggests it changed.
+- **Generic, non-version-specific CS/engineering knowledge** (what a hash map
+  is, what Big-O notation means) — this isn't tied to any particular tool's
+  current implementation, so there's nothing to go stale.
+
+## Why this is a skill, not just a hook
+
+The `tier-router.js` reminder is a keyword net — cheap, broad, and it can
+only nudge, not judge whether a specific sentence you're about to write is
+actually an unverified claim. The judgment call is still yours: notice when
+you're about to assert something you haven't actually checked this session,
+regardless of whether a keyword happened to fire.