harness-everything 0.2.2 → 0.3.6

package/tdd/guides/mocking.md

@@ -1,59 +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
+# 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

@@ -1,10 +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
+# 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

@@ -1,61 +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");
-});
-```
+# 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/tdd/references/core-discipline.md

@@ -0,0 +1,49 @@
+# TDD — Core Discipline (Full Detail)
+
+## Process & TDD Execution Flow
+
+Follow the decision matrix below when conducting TDD:
+
+```mermaid
+flowchart TD
+    Start[Trigger: Tier 2 Feature / Bugfix Task] --> Red[1. RED: Write Failing Unit/Integration Test]
+    Red --> TestRunner{Run Project Test Runner}
+
+    TestRunner -- Tests Fail as Expected --> Green[2. GREEN: Write Minimal Code to Pass]
+    TestRunner -- Tests Unexpectedly Pass --> FixTest[Fix Test Logic / Assertions] --> Red
+
+    Green --> CheckPass{Re-run Test Runner}
+    CheckPass -- Tests Pass --> Refactor[3. REFACTOR: Clean Code & Verify Alignments]
+    CheckPass -- Tests Fail (> 3 Retries) --> ZoomOut[Trigger zoom-out Circuit Breaker]
+
+    Refactor --> VerifyFinal[Re-run Tests & Mark Todo Complete]
+    VerifyFinal --> Done[TDD Cycle Complete]
+```
+
+When this skill is loaded, you MUST suppress the urge to write implementation code directly, and strictly follow these three phases.
+
+**Evidence Assertion (Law of Evidence Assertion - 證據斷言定律)**:
+During each TDD phase (RED, GREEN, REFACTOR), you MUST present actual terminal test execution logs showing the exact test failure or pass. Claiming progress or success based on "assumed" passes is strictly PROHIBITED; you must assert outcomes with hard, objective evidence.
+
+### 1. RED (Write a Failing Test)
+- **Action**: Before implementing the requested feature or Bug fix, write the corresponding Unit Test or Integration Test in the test folder.
+- **Validation**: Run the test to **ensure the test fails** (this proves the test actually covers unimplemented functionality, rather than being a fake test).
+- **Note**: If the test passes immediately, it means your test is wrong or the Bug doesn't actually exist. You must fix the test.
+
+### 2. GREEN (Implement Minimal Code to Pass Test)
+- **Action**: Switch to the implementation code and write the "minimum amount of code just enough to pass the test". Do not over-engineer or consider future extensibility at this stage.
+- **Validation**: Run the test to ensure it passes.
+
+### 3. REFACTOR (Refactor and Optimize)
+
+**Code-Doc Alignment (Law of Code-Documentation Alignment - 程式碼與文件對齊定律)**:
+In the REFACTOR phase, you MUST verify that the implemented code actually aligns with the documented contracts and doesn't contain hardcoded mocking to "finesse" or cheat the tests. Use the `todo-driven-workflow` checklist items to audit that your implementation aligns 100% with the requirement specifications.
+
+- **Action**: Under the safety net of passing tests, begin optimizing the code.
+- Checks: Is the naming clear? Is there duplicated code? Can performance be improved? Does it comply with the project's Clean Code standards?
+- **Validation**: After every modification, re-run the tests to ensure refactoring hasn't broken the original functionality.
+
+## Circuit Breaker Defense
+If during a TDD cycle you get stuck in the **GREEN phase**, and 3 consecutive implementation attempts fail to pass the test:
+- **Trigger Condition Met**: You might have hit the reasoning ceiling, or the initial test logic (RED) was written incorrectly.
+- **Mandatory Action**: Stop guessing blindly. Immediately abort the TDD process and call the `zoom-out` skill: fact-check the assumption behind each failing attempt — including whether the RED test itself encodes the wrong expectation — and resume on a fresh diagnosis. Bring the human in only if the reflection surfaces a genuine decision (e.g., the test contradicts the requirement).

package/to-spec/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: to-spec
+description: "Turn the conversation into a written spec — feature PRD, CLI/API reference, schema doc, or dev doc, whichever fits — and publish it per this repos projectDocs framework; use when alignment is complete."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.6
+---
+
+# To Spec
+
+Turns the conversation into one published spec artifact. No interviewing — `grill-me`/`grill-with-docs` run beforehand.
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Explicit `/to-spec`; never auto-run. |
+| **Expected Output** | One doc from a matching `templates/*.md` skeleton. |
+| **State Mutations** | Writes spec doc; updates `projectDocs` in `manifest.json`. |
+| **Enforcement Gate** | Outline preview before writing; graceful Exit 1 fallback. |
+
+## Workflow
+
+1. Resolve path via `node "to-spec/scripts/check-project-docs.js" check`; else existing `docs/specs/`, `docs/reference/`, `docs/adr/`, `docs/`, `.scratch/`; else `.claude/`, `.github/`, or `.cursor/harness-everything/specs/<slug>.md`.
+2. Zero-trust context: cite `Evidence: <file:line> -> Finding: <meaning>`; blocking forks mean run `grill-me`/`grill-with-docs` first.
+3. Mandatory outline preview (closest fit, 10-20 lines + target path); write only after user confirms.
+4. Publish to `specs/<feature-slug>.md` (`Status: ready-for-agent`) or `reference/`, `adr/`.
+5. Golden Flow: Feature spec needs a Design Audit (`multi-agent-workspace`) before `/to-tickets`.
+
+Templates: `templates/feature-spec.md`, `templates/cli-reference.md`, `templates/schema-doc.md`, `templates/dev-doc.md`
+
+Deep dive: references/process.md
+
+## USE FOR:
+- conversation into a published PRD or design doc
+- document a new CLI command, endpoint, or schema
+- publish an ADR once alignment completes
+
+## DO NOT USE FOR:
+- interviewing (`grill-me` / `grill-with-docs`)
+- auto-running publication

package/to-spec/references/process.md

@@ -0,0 +1,77 @@
+# To Spec — Full Process Reference
+
+## Path Resolution Flow (Step 0)
+
+```mermaid
+flowchart TD
+    Start[Receive /to-spec Request] --> Outline[Phase 1: Present Outline Preview & Shape to User]
+    Outline --> Approved{User Approves Outline?}
+
+    Approved -- No / Request Adjustments --> Modify[Adjust Template Shape & Outline] --> Outline
+    Approved -- Yes --> CheckScript{Phase 2: Node.js & Script Executable?}
+
+    CheckScript -- Yes --> RunCheck[Run check-project-docs.js check]
+    RunCheck -- Exit 0 (Configured/Inferred) --> PathConfig[Use Project Configured / Inferred Path<br>e.g. docs/specs/, docs/reference/, docs/adr/]
+    RunCheck -- Exit 1 (Unset) --> InspectRepo
+
+    CheckScript -- No / Fails --> InspectRepo{Inspect Existing Workspace Conventions}
+
+    InspectRepo -- Existing Folder Found --> PathRepo[Use Workspace Folder<br>e.g. docs/, docs/specs/, docs/adr/, .scratch/]
+    InspectRepo -- No Folder --> CheckPlatform{Fallback to Active Platform Home}
+
+    CheckPlatform -- Claude Code --> PathClaude[Write to .claude/harness-everything/specs/]
+    CheckPlatform -- GitHub Copilot / VS Code --> PathCopilot[Write to .github/harness-everything/specs/]
+    CheckPlatform -- Cursor / Other --> PathCursor[Write to .cursor/harness-everything/specs/]
+
+    PathConfig --> WriteDoc[Generate Full Spec Document]
+    PathRepo --> WriteDoc
+    PathClaude --> WriteDoc
+    PathCopilot --> WriteDoc
+    PathCursor --> WriteDoc
+```
+
+## Evidence-Driven Context (Zero-Trust Boundaries) — full rules
+
+When gathering context, you are strictly forbidden from "guessing" the architecture or existing behavior. Every finding MUST be backed by an explicit evidence chain presented in your thought process or chat output.
+
+- **Format**: `Evidence: [File path & line number / Tool output] -> Finding: [What it means]`
+- **Example**: `Evidence: read src/auth.ts line 45 -> Finding: The API currently lacks JWT token validation.`
+
+Use the project's domain glossary vocabulary throughout, and respect any ADRs in the area you're touching. If `grill-with-docs` or `grill-me` ran earlier in this conversation, treat their resolved decisions (updated `CONTEXT.md` entries, new ADRs) as settled input — cite them, don't reopen them. For anything they didn't cover, synthesize from what's already been said rather than asking new questions. If a genuinely new, unresolved fork turns up that blocks writing the doc, that's a sign this conversation needed a grilling pass first — say so and suggest running `grill-me`/`grill-with-docs` before continuing, rather than interviewing ad hoc inside this skill.
+
+## Template Selection — full guidance
+
+| Shape | File | Fits when... |
+| :--- | :--- | :--- |
+| Feature spec (PRD) | [templates/feature-spec.md](../templates/feature-spec.md) | New user-facing feature/product surface with several implementation decisions — the thing that gets broken into tickets afterward (Tier 3, usually). |
+| CLI / API reference | [templates/cli-reference.md](../templates/cli-reference.md) | A new or changed command, flag set, or single endpoint (Tier 2 or 3). |
+| Schema / file format | [templates/schema-doc.md](../templates/schema-doc.md) | A data shape change — DB schema, config format, wire payload, on-disk state (Tier 2 or 3). |
+| Dev / design doc | [templates/dev-doc.md](../templates/dev-doc.md) | A scoped technical decision worth recording that doesn't clear `grill-with-docs`'s bar for a full ADR (Tier 2, usually). |
+
+Look at what's actually being built and choose the closest fit — don't default to the heaviest one out of habit.
+
+## Interface Confirmation details
+
+What "confirm" means depends on the shape picked:
+
+- **Feature spec** → sketch the seams at which you'll test the feature. Prefer existing seams to new ones; use the highest seam possible; the ideal number is one. Check with the user that the seams match their expectations.
+- **CLI/API reference or schema doc** → confirm the surface itself (the flag names, the field names/types) with the user before writing the full doc — that's the part expensive to change after the fact.
+- **Dev doc / ADR** → confirm the decision statement in one line before expanding it into the full doc.
+
+Skip this step only if the conversation already pinned down the relevant surface explicitly (e.g. a prior `grill-with-docs` pass already fixed the schema).
+
+## Publishing details
+
+Write the doc using the adapted template at the resolved storage path:
+
+- **Feature spec** → files as a feature PRD or issue document:
+  - Output path: `<resolved-path>/specs/<feature-slug>.md` or `<resolved-path>/<feature-slug>/spec.md`.
+  - Apply status marker `Status: ready-for-agent`.
+- **CLI/API reference, schema doc, dev doc / ADR** → standalone reference document:
+  - Output path: `<resolved-path>/reference/<slug>.md` or `<resolved-path>/adr/<slug>.md`.
+
+No additional triage needed beyond the `issueDefinition` marker. A clearly-shaped doc in the right place is what lets `to-tickets` cut clean vertical slices afterward instead of guessing at scope from a raw conversation transcript.
+
+## Golden Flow rationale
+
+After publishing a `Feature spec` (Tier 3), do NOT immediately instruct the user to run `/to-tickets`. Instead, instruct the user to initiate a Design Audit first: recommend invoking `multi-agent-workspace` (or manually starting parallel Sub-agents) to conduct a Fan-out architectural audit (e.g., Security Auditor, Senior Architect) on the newly published spec. State explicitly: "This specification must pass a Design Audit before being broken down by `/to-tickets`. Any architectural flaws or over-engineering must be caught now, not during implementation."