k-harness 0.1.0

package/harness/project-state.md

@@ -0,0 +1,55 @@
+# Project State
+
+> **Keep this file under 200 lines.** Move completed items to an archive if needed.
+
+## Quick Summary
+
+<!-- 3-line summary for new sessions. Update this EVERY time before ending a chat session. -->
+<!-- Line 1: What was accomplished in the last session -->
+<!-- Line 2: What is currently in progress -->
+<!-- Line 3: What should be done next -->
+
+## Current Sprint
+
+- Sprint: 1 — Initial Setup
+- Started: <!-- TODO: date -->
+- Branch: main
+
+## Story Status
+
+| ID | Title | Status | Assignee |
+|----|-------|--------|----------|
+| S1-1 | Project scaffolding | ⬜ todo | |
+| S1-2 | Core feature implementation | ⬜ todo | |
+| S1-3 | Test coverage | ⬜ todo | |
+
+## Module Registry
+
+<!-- Summary of current modules. Full details in dependency-map.md -->
+| Module | Layer | Status |
+|--------|-------|--------|
+<!-- Fill as modules are created -->
+
+## Technical Decisions
+
+<!-- Record key architectural decisions here -->
+
+## Recent Changes
+
+<!-- Log recent completions here -->
+
+---
+
+## Session Handoff Protocol
+
+Before ending a chat session, you MUST:
+1. Update the **Quick Summary** section above (3 lines)
+2. Update **Story Status** table with current progress
+3. Add any new failure patterns to `failure-patterns.md`
+4. Update `features.md` if any features were added/changed
+
+When starting a new chat session, read these files first:
+1. `project-state.md` (this file) — where we are
+2. `features.md` — what exists
+3. `failure-patterns.md` — what to watch out for
+4. `project-brief.md` — why we're building this

package/harness/skills/feature-breakdown.md

@@ -0,0 +1,80 @@
+# Feature Breakdown
+
+## Purpose
+
+Decompose a feature into implementation tasks ordered by dependency.
+Ensures bottom-up implementation: foundations first, then layers that depend on them.
+
+## When to Apply
+
+- Starting a new feature or Story
+- A feature touches 3+ modules
+- Unsure which module to build first
+- After the Planner agent creates a high-level plan
+
+## Procedure
+
+1. **Describe the feature** in one sentence
+2. **Read dependency-map.md** to understand current module relationships
+3. **Identify affected modules**: List every module that needs changes
+4. **Classify changes per module**:
+   - NEW_MODULE: Entirely new module to create
+   - INTERFACE_CHANGE: Existing module's public interface changes
+   - INTERNAL_CHANGE: Only internal implementation changes
+   - TEST_ONLY: Only test updates needed
+5. **Build dependency order**:
+   - Draw a mini dependency graph for just the affected modules
+   - Sort topologically: modules with no dependencies come first
+   - Group into implementation waves (parallel-safe batches)
+6. **Create task sequence**: Convert waves into numbered tasks
+7. **Annotate each task** with:
+   - Module name
+   - Change type (from step 4)
+   - Files to create/modify
+   - Tests to write
+   - Dependency (which prior task must finish first)
+
+## Output Format
+
+```markdown
+## Feature: [one-sentence description]
+
+### Wave 1 (no dependencies)
+- [ ] Task 1: [Module A] — Create entity + repository interface
+  - Files: src/domain/entities/X.ts, src/domain/repositories/XRepository.ts
+  - Tests: tests/domain/X.test.ts
+  - Depends on: none
+
+### Wave 2 (depends on Wave 1)
+- [ ] Task 2: [Module B] — Implement use case
+  - Files: src/application/usecases/DoX.ts
+  - Tests: tests/application/DoX.test.ts
+  - Depends on: Task 1
+
+### Wave 3 (depends on Wave 2)
+- [ ] Task 3: [Module C] — Add API endpoint
+  - Files: src/presentation/routes/x.ts, src/presentation/dto/XDto.ts
+  - Tests: tests/presentation/x.test.ts
+  - Depends on: Task 2
+
+### Dependency Map Updates
+- [ ] Register Module A in dependency-map.md
+- [ ] Update Module B's "Depends On" column
+```
+
+## Rules
+
+- Never implement a module before its dependencies exist
+- Each task should be completable in one session
+- Every task must include its test files
+- New modules MUST be registered in dependency-map.md (Iron Law #6)
+- If a task exceeds Story scope, stop and report to user
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Start from UI, work backward | Start from domain, work forward |
+| One giant task for the whole feature | Break into single-module tasks |
+| Skip dependency-map registration | Register immediately when creating module |
+| Tests "later" | Tests in the same task |

package/harness/skills/impact-analysis.md

@@ -0,0 +1,63 @@
+# Impact Analysis
+
+## Purpose
+
+Before modifying any module, trace all affected modules to prevent cascade failures.
+The most common cause of regressions in growing projects is changing one module without updating its dependents.
+
+## When to Apply
+
+- Adding, removing, or changing a module's public interface
+- Modifying shared types, entities, or DTOs
+- Refactoring that touches more than 2 files
+- When a test fails in a module you didn't directly change
+
+## Procedure
+
+1. **Identify the target module**: Which module are you about to change?
+2. **Read dependency-map.md**: Find the target module's row
+3. **List dependents**: Read the "Depended By" column — these are the blast radius
+4. **Check interface impact**: Does your change affect the module's public interface?
+   - If NO (internal-only change) → proceed, but still run dependent tests
+   - If YES → continue to step 5
+5. **Trace each dependent**:
+   - List files in each dependent module that import from the target
+   - Identify which functions/types they use
+   - Determine if the interface change breaks them
+6. **Plan updates**: Create a task list of all files that need modification
+7. **Verify scope**: Confirm all files are within the current Story scope (project-state.md)
+
+## Checklist
+
+- [ ] Target module identified in dependency-map.md
+- [ ] All dependent modules listed
+- [ ] Interface vs internal change classified
+- [ ] Files importing from target module enumerated
+- [ ] Mock/test updates planned for each dependent (FP-001)
+- [ ] All changes within current Story scope
+- [ ] Escalated to user if scope exceeds current Story
+
+## Example
+
+### Good
+```
+Target: auth module
+Change: Added `resetPassword(email: string): Promise<void>`
+Dependents: api, admin
+Impact:
+  - api/routes/auth.ts imports AuthService → needs new route
+  - admin/controllers/user.ts imports AuthService → needs admin endpoint
+  - tests/__mocks__/AuthService.ts → needs new mock method
+Plan: 4 files to update, all within S3-2 scope
+```
+
+### Bad
+```
+"I'll just add this method and see what breaks."
+→ Tests fail in 3 modules, mock out of sync, 2 hours wasted
+```
+
+## Related Failure Patterns
+
+- FP-001: Interface changed, mock not updated → Checklist item 5
+- FP-002: Type confusion across modules → Step 5 verification

package/harness/skills/investigate.md

@@ -0,0 +1,73 @@
+# Investigate
+
+## Purpose
+
+Debug bugs systematically. Prevent "symptom patching" — fixing without understanding root cause.
+4-phase debugging process inspired by gstack's /investigate.
+
+## When to Apply
+
+- Test failures with unclear cause
+- Runtime errors
+- Regression bugs ("it worked yesterday")
+- Unexplained behavior
+
+## Procedure
+
+### Phase 1: Evidence Collection (NO FIXES)
+
+1. Record the full error message and stack trace
+2. Trace the code path backwards from the error
+3. Check recent changes: `git log --oneline -20 -- <related files>`
+4. Verify the bug is reproducible
+
+**Do NOT modify code in this phase.**
+
+### Phase 2: Scope Lock
+
+1. Identify the module/directory containing the root cause
+2. Exclude files outside that scope from modification
+3. Check failure-patterns.md for matching patterns
+
+### Phase 3: Hypothesis + Fix
+
+1. State the root cause hypothesis in one sentence
+2. Implement the minimal fix based on the hypothesis
+3. Verify the fix does not break existing tests
+
+### Phase 4: Verify + Record
+
+1. Run all related tests after the fix
+2. Add a regression test (prevent the same bug from recurring)
+3. Decide if the pattern should be recorded in failure-patterns.md
+
+## Checklist
+
+- [ ] Root cause hypothesis is stated explicitly
+- [ ] Did NOT skip Phase 1 (evidence collection) and jump straight to fixing
+- [ ] Fix scope is limited to the problem's scope
+- [ ] All related tests pass after the fix
+- [ ] Regression test is added
+- [ ] Escalated to user after 3 failed attempts
+
+## Example
+
+### Good
+```
+Phase 1: TypeError: Cannot read property 'id' of undefined at UserService.ts:45
+Phase 2: Scope → src/application/services/UserService.ts, src/domain/entities/User.ts
+Phase 3: Hypothesis — findById returns null but no null check exists
+         Fix — add null guard at UserService.ts:44
+Phase 4: Tests pass, null case test added
+```
+
+### Bad
+```
+"Error occurred so I added an if statement."
+→ Root cause unknown, no reproduction conditions recorded, same error possible elsewhere
+```
+
+## Related Failure Patterns
+
+- FP-002: Type confusion → Phase 1 requires verifying actual types
+- FP-001: Mock not updated → Phase 4 requires checking mock sync

package/harness/skills/security-checklist.md

@@ -0,0 +1,49 @@
+# Security Checklist
+
+## Purpose
+
+Inspect for security risks before committing code.
+Prevents credential leaks and accidental commits of sensitive files. (FP-004)
+
+## When to Apply
+
+- Before running `git add` or committing
+- When creating new files
+- When modifying config or environment files
+- When changing authentication/authorization code
+
+## Procedure
+
+1. **Check staging area**: Run `git diff --cached --name-only` to list files staged for commit
+2. **Scan for forbidden files**: Check if .env, credentials, *.pem, *.key files are staged
+3. **Scan for hardcoded secrets**: Search staged files for passwords, API keys, tokens
+4. **Verify .gitignore**: Ensure new environment files are covered by .gitignore
+5. **Check for temp files**: Verify tmp_*, debug_*, coverage_* files are not staged
+
+## Checklist
+
+- [ ] (FP-004) No .env, credentials, *.key files in staging area
+- [ ] (FP-004) No hardcoded passwords, API keys, or tokens in code
+- [ ] Sensitive file patterns are registered in .gitignore
+- [ ] No temp files (tmp_*, debug_*, coverage_*) in staging area
+- [ ] Using explicit per-file staging, not `git add .`
+
+## Example
+
+### Good
+```bash
+git add src/auth/login.ts tests/auth/login.test.ts
+# Environment variable via config module
+const dbPassword = process.env.DB_PASSWORD;
+```
+
+### Bad
+```bash
+git add .
+# Hardcoded password
+const dbPassword = "super_secret_123";
+```
+
+## Related Failure Patterns
+
+- FP-004: Dangerous file committed → Checklist items 1, 4

package/harness/skills/test-integrity.md

@@ -0,0 +1,46 @@
+# Test Integrity
+
+## Purpose
+
+Ensure test mocks stay synchronized when repository/service interfaces change.
+Prevents the most common LLM coding failure: updating an interface but forgetting to update corresponding mocks. (FP-001)
+
+## When to Apply
+
+- Adding, removing, or modifying methods on a repository/service interface
+- Creating a new repository or service
+- When a use case starts calling a new interface method
+
+## Procedure
+
+1. **Identify changed interfaces**: Find modified files in your interface directory
+2. **Map to mock files**: Locate the corresponding mock file for each changed interface
+3. **Sync methods**: Verify every interface method exists in the mock
+4. **Verify return types**: Confirm mock return values match the interface return types
+5. **Check consumers**: Verify use case tests configure the mock correctly for new methods
+
+## Checklist
+
+- [ ] (FP-001) Every changed interface method is reflected in its mock
+- [ ] Mock return types match interface signatures
+- [ ] New methods have default mock return values set
+- [ ] Use case tests correctly use the new mock methods
+- [ ] Existing tests still pass
+
+## Example
+
+### Good
+```
+Interface adds findByFilters() → Mock adds findByFilters with mockResolvedValue([])
+Both changes in the same commit.
+```
+
+### Bad
+```
+Interface adds findByFilters() → Mock unchanged
+→ Runtime error: method not found on mock object
+```
+
+## Related Failure Patterns
+
+- FP-001: Interface changed, mock not updated → Checklist item 1

package/harness/testing-rules.md

@@ -0,0 +1,21 @@
+# Testing Rules
+
+## Required
+
+- When interface changes, update corresponding mocks in the same commit (FP-001).
+- Mocks must implement ALL interface methods. Missing method = build failure.
+- Do not use real credentials in test data. Use fixtures or fakers.
+- Async tests must use `await`. No floating promises.
+- Each test must be independent. No shared state between tests.
+
+## Forbidden
+
+- Casting mocks with `any` type. Create mocks using the actual interface type.
+- Creating mocks with bare `jest.fn()` only. Set default return values with `mockResolvedValue` etc.
+- Committing with `skip` or `only` left in test files.
+- Committing with `console.log` debugging statements.
+
+## References
+
+- test-integrity skill
+- failure-patterns.md FP-001: Mock not updated

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "k-harness",
+  "version": "0.1.0",
+  "description": "LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures",
+  "keywords": [
+    "llm",
+    "ai",
+    "copilot",
+    "claude",
+    "cursor",
+    "codex",
+    "windsurf",
+    "harness",
+    "development",
+    "agents",
+    "skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OG056501-Opensource-Poc/k-harness.git"
+  },
+  "license": "MIT",
+  "author": "",
+  "main": "src/init.js",
+  "bin": {
+    "k-harness": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "harness/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}