k-harness 0.9.0 → 0.9.1

package/harness/agents/planner.md

@@ -18,6 +18,7 @@ The Planner is the entry point for new features — use it BEFORE writing code.
 - docs/dependency-map.md
 - docs/project-state.md
 - docs/failure-patterns.md
+- docs/agent-memory/planner.md — Past estimation accuracy and architecture insights
 
 ## Input
 
@@ -38,6 +39,17 @@ Before proceeding, verify that required state files have content (not just TODO
 If ALL files are empty/placeholder-only → **Stop and run the `bootstrap` skill first.** Report: "State files are empty. Running bootstrap to onboard this project."
 If `docs/project-brief.md` alone is empty → Warn the user but proceed (the plan will lack direction guard).
 
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/planner.md` for past learnings:
+- Estimation accuracy from previous sprints (did Wave estimates match reality?)
+- Architecture patterns that worked or failed in this project
+- Repeated planning mistakes to avoid
+
+Apply these insights when creating the implementation plan. If the memory file is empty or contains only placeholders, skip this step.
+
+> **Team Mode**: In Team mode, agent memory is personal (`.harness/agent-memory/`). Each developer accumulates their own planning insights.
+
 ### For New Feature
 
 1. Read `docs/project-brief.md` to understand project vision, goals, **non-goals**, and **Decision Log**

package/harness/agents/reviewer.md

@@ -13,9 +13,12 @@ Finds issues and auto-fixes where safe, escalates where not.
 
 ## Referenced Files
 
+- docs/project-brief.md — Project vision, goals, non-goals, and Decision Log
+- docs/features.md — Feature registry (for Step 6 Feature Registry Check)
 - docs/failure-patterns.md — Project failure patterns
 - docs/project-state.md — Current Story scope
 - docs/dependency-map.md — Module dependency graph
+- docs/agent-memory/reviewer.md — Past review patterns and frequently missed items
 
 ## Procedure
 
@@ -27,6 +30,15 @@ Before reviewing, verify that required state files exist and are not empty:
 
 If state files are empty/placeholder-only → Warn: "State files are not filled. Review will proceed but scope check and failure pattern cross-check will be limited. Consider running `bootstrap` skill."
 
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/reviewer.md` for past learnings:
+- Frequently missed review items in this project
+- Common code patterns that caused issues
+- Review statistics (pass rate, common failure categories)
+
+Pay extra attention to items flagged in past reviews. If the memory file is empty or contains only placeholders, skip this step.
+
 ### Input
 
 Changed file list (user-provided or from `git diff --name-only`)
@@ -138,3 +150,10 @@ Report using: **DONE** | **DONE_WITH_CONCERNS** | **BLOCKED** | **NEEDS_CONTEXT*
 - Do not refactor beyond the review scope
 - Auto-apply security fixes but always record them in output
 - Escalate with NEEDS_CONTEXT after 3 uncertain judgments
+
+## STATE-AUDIT Handoff
+
+When Step 8 (State File Audit) produces `[STATE-AUDIT]` flags:
+1. List all flagged items in the review output
+2. The `learn` skill (run at session end) will verify and resolve these flags
+3. If a flag is critical (missing module in dependency-map, unregistered feature), recommend fixing immediately rather than deferring to learn

package/harness/agents/sprint-manager.md

@@ -5,10 +5,21 @@
 Manage Sprint/Story state, guide development sequence, and prevent scope drift.
 Keeps the LLM focused on the current work item.
 
+## Referenced Skills
+
+- bootstrap — Recommended when state files are empty
+- learn — Recommended at session end or when all stories are done
+- pivot — Recommended when direction change is detected
+- investigate — Recommended when bug is blocking progress
+
 ## Referenced Files
 
 - docs/project-state.md — Current state (this is the core file)
+- docs/project-brief.md — Project vision and goals (for direction checks)
+- docs/features.md — Feature registry (for progress overview)
+- docs/dependency-map.md — Module graph (for scope validation)
 - docs/failure-patterns.md — Recurring failure tracking
+- docs/agent-memory/sprint-manager.md — Past velocity and scope drift data
 
 ## Procedure
 
@@ -18,7 +29,18 @@ Before handling any request, verify `docs/project-state.md` has content:
 - Quick Summary must not be all TODO placeholders
 - Story Status table must have at least one row
 
-If `docs/project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: docs/project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
+If `docs/project-state.md` is empty/placeholder-only → **Recommend running `bootstrap` skill first.** Report: "docs/project-state.md is empty. Run bootstrap to initialize project state before tracking sprints."
+
+### Step 0.5: Load Agent Memory
+
+Read `docs/agent-memory/sprint-manager.md` for past learnings:
+- Team velocity data (stories per sprint)
+- Scope drift history (how often did scope expand?)
+- Story sizing accuracy (were estimates correct?)
+
+Use these insights when recommending story order and estimating sprint capacity. If the memory file is empty or contains only placeholders, skip this step.
+
+> **Team Mode**: In Team mode, agent memory is personal (`.harness/agent-memory/`). Each developer tracks their own velocity and scope drift patterns.
 
 ### Input
 
@@ -63,8 +85,10 @@ After every status check, recommend the next action based on current context:
 **Request: "new story" / "next task"**
 1. Find next `todo` Story in docs/project-state.md
 2. Change its status to `in-progress`
-3. Specify Story scope (related files/directories)
-4. Alert relevant docs/failure-patterns.md items
+3. Read `docs/dependency-map.md` to identify modules involved in this Story
+4. Specify Story scope (related files/directories from dependency-map)
+5. Alert relevant docs/failure-patterns.md items
+6. Recommend relevant skill: "Consider running `planner` if this story needs detailed breakdown"
 
 **Request: "new sprint"**
 1. Check all Stories in current Sprint
@@ -108,3 +132,7 @@ STATUS: DONE
 - Do not modify code directly — manage state only
 - Only write to docs/project-state.md; read-only for all other files
 - Always confirm with user before modifying scope boundaries
+
+## Related Failure Patterns
+
+- FP-003: Scope drift → Scope Check handler detects out-of-scope modifications and warns the user before proceeding

package/harness/core-rules.md

@@ -9,6 +9,8 @@ Read `docs/project-state.md` first. If all state files are empty, run `bootstrap
 
 ## Workflow
 
+- First time / empty state → run `bootstrap`
+- Session start → run `sprint-manager` to check status
 - New feature → run `planner` before coding
 - Before commit → run `reviewer`
 - Bug or issue → run `investigate`

package/harness/skills/feature-breakdown.md

@@ -5,6 +5,10 @@
 Decompose a feature into implementation tasks ordered by dependency.
 Ensures bottom-up implementation: foundations first, then layers that depend on them.
 
+## Invoked By
+
+- **planner** agent — Step 8: Create ordered task list for new features
+
 ## When to Apply
 
 - Starting a new feature or Story
@@ -15,24 +19,26 @@ Ensures bottom-up implementation: foundations first, then layers that depend on
 ## Procedure
 
 1. **Describe the feature** in one sentence
-2. **Read docs/dependency-map.md** to understand current module relationships
-3. **Identify affected modules**: List every module that needs changes
-4. **Classify changes per module**:
+2. **Read docs/project-brief.md** — verify the feature aligns with Goals and does not violate Non-Goals. If it conflicts with Non-Goals, **stop and warn the user** before proceeding. (Direction Guard — prevents breakdown of out-of-scope features even when invoked directly without planner)
+3. **Read docs/dependency-map.md** to understand current module relationships
+4. **Identify affected modules**: List every module that needs changes
+5. **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**:
+6. **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:
+7. **Create task sequence**: Convert waves into numbered tasks
+8. **Annotate each task** with:
    - Module name
-   - Change type (from step 4)
+   - Change type (from step 5)
    - Files to create/modify
    - Tests to write
    - Dependency (which prior task must finish first)
+   - ⚠️ Relevant failure patterns (check docs/failure-patterns.md)
 
 ## Output Format
 
@@ -87,3 +93,9 @@ After completing the breakdown, update these files in the same session:
 | Skip dependency-map registration | Register immediately when creating module |
 | Tests "later" | Tests in the same task |
 | Produce breakdown but skip state file updates | State file updates are part of the breakdown, not a separate step |
+
+## Related Failure Patterns
+
+- FP-001: Interface changed, mock not updated → When creating tasks that modify interfaces, include "Update mock" as an explicit sub-task
+- FP-002: Type confusion → When annotating tasks, specify expected types for new interfaces
+- FP-003: Scope drift → If the breakdown exceeds the current Story scope, stop and report

package/harness/skills/impact-analysis.md

@@ -5,6 +5,11 @@
 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.
 
+## Invoked By
+
+- **planner** agent — Step 9: for each existing module being modified
+- **reviewer** agent — Step 7: when interface changes affect 2+ dependent modules
+
 ## When to Apply
 
 - Adding, removing, or changing a module's public interface
@@ -16,21 +21,25 @@ The most common cause of regressions in growing projects is changing one module
 
 1. **Identify the target module**: Which module are you about to change?
 2. **Read docs/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?
+3. **Read docs/failure-patterns.md**: Check if any active patterns (FP-001, FP-002, etc.) apply to the target module or change type. If FP-001 frequency > 0, flag mock updates as mandatory in step 6.
+4. **List dependents**: Read the "Depended By" column — these are the blast radius
+5. **Read docs/features.md**: Identify which features include the target module in their Key Files column. These features may need status or Key Files updates.
+6. **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**:
+   - If YES → continue to step 7
+7. **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 docs/project-state.md)
+8. **Plan updates**: Create a task list of all files that need modification
+9. **Verify scope**: Confirm all files are within the current Story scope (docs/project-state.md)
 
 ## Checklist
 
 - [ ] Target module identified in docs/dependency-map.md
+- [ ] docs/failure-patterns.md checked for active patterns
 - [ ] All dependent modules listed
+- [ ] Affected features identified from docs/features.md
 - [ ] Interface vs internal change classified
 - [ ] Files importing from target module enumerated
 - [ ] Mock/test updates planned for each dependent (FP-001)
@@ -62,9 +71,10 @@ Plan: 4 files to update, all within S3-2 scope
 After completing the analysis, update these files:
 
 - [ ] **docs/dependency-map.md**: Update the Interface Change Log table with: Date, Module, Change description, Affected Modules, Status. **This is mandatory for ALL interface changes** — do not skip even if the change seems minor.
+- [ ] **docs/features.md**: If the interface change affects a feature's Key Files, update the Key Files column. If test files change, update the Test Files column.
 - [ ] **docs/project-state.md**: If scope exceeds current Story, add a note to Recent Changes.
 
 ## Related Failure Patterns
 
-- FP-001: Interface changed, mock not updated → Checklist item 5
-- FP-002: Type confusion across modules → Step 5 verification
+- FP-001: Interface changed, mock not updated → Checklist item 7 (mock/test updates planned)
+- FP-002: Type confusion across modules → Step 7 (trace each dependent, verify types)

package/harness/skills/investigate.md

@@ -26,8 +26,10 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 ### Phase 2: Scope Lock
 
 1. Identify the module/directory containing the root cause
-2. Exclude files outside that scope from modification
-3. Check docs/failure-patterns.md for matching patterns
+2. **Read docs/dependency-map.md**: Find the target module's row. Check "Depended By" column to understand which other modules might be affected by the same root cause or by your fix.
+3. **Read docs/project-state.md**: Verify the fix scope is within the current Story scope. If the root cause is in a module outside the current Story, **warn the user** before proceeding (Iron Law #3: Scope Compliance).
+4. Exclude files outside that scope from modification
+5. Check docs/failure-patterns.md for matching patterns
 
 ### Phase 3: Hypothesis + Fix
 
@@ -45,6 +47,8 @@ Debug bugs systematically. Prevent "symptom patching" — fixing without underst
 
 - [ ] Root cause hypothesis is stated explicitly
 - [ ] Did NOT skip Phase 1 (evidence collection) and jump straight to fixing
+- [ ] docs/dependency-map.md consulted for blast radius understanding
+- [ ] Fix scope verified against current Story in docs/project-state.md
 - [ ] Fix scope is limited to the problem's scope
 - [ ] All related tests pass after the fix
 - [ ] Regression test is added
@@ -82,5 +86,6 @@ After the fix is verified (Phase 4):
 
 ## Related Failure Patterns
 
-- FP-002: Type confusion → Phase 1 requires verifying actual types
 - FP-001: Mock not updated → Phase 4 requires checking mock sync
+- FP-002: Type confusion → Phase 1 requires verifying actual types
+- FP-003: Scope drift → Phase 2 Scope Lock must verify fix is within current Story scope

package/harness/skills/learn.md

@@ -60,6 +60,22 @@ For each issue/error that occurred in this session:
 2. If existing features were modified → update Key Files and Test Files columns
 3. If features were completed → update Status to `✅ done`
 
+### Step 4.5: Verify docs/dependency-map.md (mandatory)
+
+1. Check if any new modules were created in this session (scan `git diff --stat` for new directories)
+2. Check if any module interfaces changed
+3. For each finding:
+   - New module without dependency-map entry → **add it now**
+   - Interface change without Interface Change Log entry → **add it now**
+4. Cross-reference `docs/features.md` Key Files against `docs/dependency-map.md` modules — flag orphaned modules
+
+### Step 4.6: Resolve STATE-AUDIT Flags (if applicable)
+
+If the `reviewer` agent was run in this session and produced `[STATE-AUDIT]` flags:
+1. Review each flagged item
+2. Apply the recommended state file update
+3. If the flag was already resolved during the session, skip it
+
 ### Step 5: Update Agent Memory (if applicable)
 
 If an agent (reviewer, planner, sprint-manager) was used in this session, update its memory file in `docs/agent-memory/`:
@@ -88,9 +104,10 @@ Present a summary of all updates made.
 - [FP-NNN] (new/updated): [description]
 
 ### State Files Updated:
-- [x]docs/project-state.md — Quick Summary refreshed
-- [x]docs/failure-patterns.md — [N] patterns added/updated
-- [x]docs/features.md — [N] features updated (if applicable)
+- [x] docs/project-state.md — Quick Summary refreshed
+- [x] docs/failure-patterns.md — [N] patterns added/updated
+- [x] docs/features.md — [N] features updated (if applicable)
+- [x] docs/dependency-map.md — [N] modules verified/added (if applicable)
 - [x] docs/agent-memory/{name}.md — [N] agents updated (if applicable)
 
 ### Next Session Should:

package/harness/skills/security-checklist.md

@@ -5,6 +5,10 @@
 Inspect for security risks before committing code.
 Prevents credential leaks and accidental commits of sensitive files. (FP-004)
 
+## Invoked By
+
+- **reviewer** agent — Step 4: Security risk inspection
+
 ## When to Apply
 
 - Before running `git add` or committing
@@ -15,13 +19,15 @@ Prevents credential leaks and accidental commits of sensitive files. (FP-004)
 ## 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
+2. **Read docs/failure-patterns.md**: Check FP-004 status. If frequency > 0, apply extra scrutiny to all staged files and verify .gitignore coverage is comprehensive.
+3. **Scan for forbidden files**: Check if .env, credentials, *.pem, *.key files are staged
+4. **Scan for hardcoded secrets**: Search staged files for passwords, API keys, tokens
+5. **Verify .gitignore**: Ensure new environment files are covered by .gitignore
+6. **Check for temp files**: Verify tmp_*, debug_*, coverage_* files are not staged
 
 ## Checklist
 
+- [ ] docs/failure-patterns.md reviewed for FP-004 history
 - [ ] (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
@@ -49,7 +55,8 @@ const dbPassword = "super_secret_123";
 After completing the security check:
 
 - [ ] **docs/failure-patterns.md**: If a security issue was found (credentials staged, hardcoded secret), add a new FP-NNN entry or increment FP-004 Frequency.
+- [ ] **docs/project-state.md**: If a security issue was found, add to Recent Changes: "⚠️ Security: [description of issue found/fixed]". This ensures the next session's Quick Summary includes the security context.
 
 ## Related Failure Patterns
 
-- FP-004: Dangerous file committed → Checklist items 1, 4
+- FP-004: Dangerous file committed → Checklist items 2, 5 (no forbidden files, no temp files)

package/harness/skills/test-integrity.md

@@ -5,6 +5,10 @@
 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)
 
+## Invoked By
+
+- **reviewer** agent — Step 3: Mock synchronization verification
+
 ## When to Apply
 
 - Adding, removing, or modifying methods on a repository/service interface
@@ -13,16 +17,18 @@ Prevents the most common LLM coding failure: updating an interface but forgettin
 
 ## 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
+1. **Read docs/failure-patterns.md**: Check FP-001 status. If frequency > 0, this project has a history of mock sync failures — apply extra scrutiny to every interface change.
+2. **Identify changed interfaces**: Find modified files in your interface directory
+3. **Map to mock files**: Locate the corresponding mock file for each changed interface
+4. **Sync methods**: Verify every interface method exists in the mock
+5. **Verify return types**: Confirm mock return values match the interface return types (FP-002: watch for type confusion)
+6. **Check consumers**: Verify use case tests configure the mock correctly for new methods
 
 ## Checklist
 
+- [ ] docs/failure-patterns.md reviewed for FP-001 history
 - [ ] (FP-001) Every changed interface method is reflected in its mock
-- [ ] Mock return types match interface signatures
+- [ ] (FP-002) Mock return types match interface signatures (no type confusion)
 - [ ] New methods have default mock return values set
 - [ ] Use case tests correctly use the new mock methods
 - [ ] Existing tests still pass
@@ -47,6 +53,7 @@ After synchronizing mocks:
 
 - [ ] **docs/failure-patterns.md**: If mock sync was missed and caused a test failure, increment FP-001 Frequency.
 - [ ] **docs/dependency-map.md**: If the interface change altered module relationships, update the relevant row.
+- [ ] **docs/project-state.md**: If mock sync issues were found and fixed, add to Recent Changes: "🔧 Test: [interface] mock synchronized". This ensures the next session is aware of the fix.
 
 ## Testing Rules (enforced during this skill)
 
@@ -59,4 +66,5 @@ After synchronizing mocks:
 
 ## Related Failure Patterns
 
-- FP-001: Interface changed, mock not updated → Checklist item 1
+- FP-001: Interface changed, mock not updated → Checklist item 2
+- FP-002: Type confusion → Step 5 return type verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k-harness",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "LLM Development Harness — IDE-agnostic rules, skills, and agents that prevent common AI coding failures",
   "keywords": [
     "llm",